> ## Documentation Index
> Fetch the complete documentation index at: https://docs.laozhang.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Chat Completions API | Unified LLM Interface | LaoZhang API
> OpenAI-compatible Chat Completions API. Access GPT-4, Claude, Gemini and 200+ models through a single endpoint. Complete documentation with code examples.
## API Endpoint
```
POST https://api2.laozhang.ai/v1/chat/completions
```
**Full compatibility with OpenAI official format**
Laozhang API is fully compatible with OpenAI official interface format, you can directly replace `https://api.openai.com/v1` with `https://api2.laozhang.ai/v1` to use.
## Request Parameters
### Required Parameters
Model name to use
Supported models:
* **OpenAI Series**: `gpt-4o`, `gpt-4o-mini`, `gpt-4-turbo`, `gpt-3.5-turbo`, etc.
* **Claude Series**: `claude-3-5-sonnet`, `claude-3-opus`, `claude-3-haiku`, etc.
* **Gemini Series**: `gemini-1.5-pro`, `gemini-1.5-flash`, `gemini-2.0-flash-exp`, etc.
* **Chinese Models**: `deepseek-chat`, `qwen-max`, `glm-4-flash`, `yi-lightning`, etc.
For complete model list, see [API Reference - Models](/en/api-reference/models)
Conversation message array, each message contains `role` and `content`
```json theme={null}
[
{
"role": "system",
"content": "You are a helpful assistant"
},
{
"role": "user",
"content": "Hello!"
}
]
```
**Role Descriptions**:
* `system`: System prompt, defines AI assistant behavior
* `user`: User message
* `assistant`: AI assistant's previous response
### Optional Parameters
Randomness of generated results, range 0-2
* **0**: Deterministic, minimal randomness (recommended for translation, summarization, etc.)
* **0.7**: Balanced, suitable for most scenarios
* **1.5-2**: High creativity (recommended for creative writing, brainstorming, etc.)
Maximum number of tokens to generate
If not set, model will use its default limit. If response is truncated, try increasing this value.
**Recommended Values**:
* Short responses: 500-1000
* Medium responses: 2000-4000
* Long responses: 8000+
Whether to use stream output
* `false`: Wait for complete response
* `true`: Receive response in chunks (better user experience)
Nucleus sampling parameter, range 0-1
Controls diversity of output. Generally use either `temperature` or `top_p`, not both simultaneously.
Frequency penalty, range -2.0 to 2.0
Positive values reduce repetition of already appearing content.
Presence penalty, range -2.0 to 2.0
Positive values encourage discussion of new topics.
Stop sequences, generation stops when these strings are encountered
Can be a single string or array of up to 4 strings.
End user unique identifier for abuse detection
Recommended for multi-user scenarios.
## Message Format
### Basic Text Message
```json theme={null}
{
"role": "user",
"content": "Please introduce yourself"
}
```
### Multimodal Message (Image Understanding)
```json theme={null}
{
"role": "user",
"content": [
{
"type": "text",
"text": "What's in this image?"
},
{
"type": "image_url",
"image_url": {
"url": "https://example.com/image.jpg"
}
}
]
}
```
```json theme={null}
{
"role": "user",
"content": [
{
"type": "text",
"text": "Please analyze this image"
},
{
"type": "image_url",
"image_url": {
"url": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
}
}
]
}
```
**Multimodal Models**
Support image understanding:
* OpenAI: `gpt-4o`, `gpt-4o-mini`, `gpt-4-turbo`
* Claude: `claude-3-5-sonnet`, `claude-3-opus`, `claude-3-sonnet`, `claude-3-haiku`
* Gemini: `gemini-1.5-pro`, `gemini-1.5-flash`, `gemini-2.0-flash-exp`
## Request Examples
### cURL
```bash Basic Dialogue theme={null}
curl https://api2.laozhang.ai/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"model": "gpt-4o-mini",
"messages": [
{
"role": "system",
"content": "You are a helpful assistant"
},
{
"role": "user",
"content": "What is the capital of France?"
}
]
}'
```
```bash Stream Output theme={null}
curl https://api2.laozhang.ai/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"model": "gpt-4o-mini",
"messages": [
{
"role": "user",
"content": "Tell me a story"
}
],
"stream": true
}'
```
```bash Image Understanding theme={null}
curl https://api2.laozhang.ai/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"model": "gpt-4o",
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "What is in this image?"
},
{
"type": "image_url",
"image_url": {
"url": "https://example.com/image.jpg"
}
}
]
}
]
}'
```
### Node.js
```javascript Official OpenAI SDK theme={null}
import OpenAI from 'openai';
const openai = new OpenAI({
apiKey: 'YOUR_API_KEY',
baseURL: 'https://api2.laozhang.ai/v1'
});
// Basic dialogue
const completion = await openai.chat.completions.create({
model: 'gpt-4o-mini',
messages: [
{ role: 'system', content: 'You are a helpful assistant' },
{ role: 'user', content: 'What is the capital of France?' }
]
});
console.log(completion.choices[0].message.content);
// Stream output
const stream = await openai.chat.completions.create({
model: 'gpt-4o-mini',
messages: [
{ role: 'user', content: 'Tell me a story' }
],
stream: true
});
for await (const chunk of stream) {
process.stdout.write(chunk.choices[0]?.delta?.content || '');
}
```
```javascript Axios theme={null}
import axios from 'axios';
const response = await axios.post(
'https://api2.laozhang.ai/v1/chat/completions',
{
model: 'gpt-4o-mini',
messages: [
{ role: 'user', content: 'Hello!' }
]
},
{
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer YOUR_API_KEY'
}
}
);
console.log(response.data.choices[0].message.content);
```
### Python
```python Official OpenAI SDK theme={null}
from openai import OpenAI
client = OpenAI(
api_key="YOUR_API_KEY",
base_url="https://api2.laozhang.ai/v1"
)
# Basic dialogue
completion = client.chat.completions.create(
model="gpt-4o-mini",
messages=[
{"role": "system", "content": "You are a helpful assistant"},
{"role": "user", "content": "What is the capital of France?"}
]
)
print(completion.choices[0].message.content)
# Stream output
stream = client.chat.completions.create(
model="gpt-4o-mini",
messages=[
{"role": "user", "content": "Tell me a story"}
],
stream=True
)
for chunk in stream:
if chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="")
# Image understanding
completion = client.chat.completions.create(
model="gpt-4o",
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "What's in this image?"},
{
"type": "image_url",
"image_url": {
"url": "https://example.com/image.jpg"
}
}
]
}
]
)
print(completion.choices[0].message.content)
```
```python Requests theme={null}
import requests
url = "https://api2.laozhang.ai/v1/chat/completions"
headers = {
"Content-Type": "application/json",
"Authorization": "Bearer YOUR_API_KEY"
}
data = {
"model": "gpt-4o-mini",
"messages": [
{"role": "user", "content": "Hello!"}
]
}
response = requests.post(url, headers=headers, json=data)
result = response.json()
print(result['choices'][0]['message']['content'])
```
### Go
```go theme={null}
package main
import (
"context"
"fmt"
"github.com/sashabaranov/go-openai"
)
func main() {
config := openai.DefaultConfig("YOUR_API_KEY")
config.BaseURL = "https://api2.laozhang.ai/v1"
client := openai.NewClientWithConfig(config)
resp, err := client.CreateChatCompletion(
context.Background(),
openai.ChatCompletionRequest{
Model: "gpt-4o-mini",
Messages: []openai.ChatCompletionMessage{
{
Role: openai.ChatMessageRoleSystem,
Content: "You are a helpful assistant",
},
{
Role: openai.ChatMessageRoleUser,
Content: "What is the capital of France?",
},
},
},
)
if err != nil {
fmt.Printf("Error: %v\n", err)
return
}
fmt.Println(resp.Choices[0].Message.Content)
}
```
## Response Format
### Standard Response
```json theme={null}
{
"id": "chatcmpl-abc123",
"object": "chat.completion",
"created": 1699999999,
"model": "gpt-4o-mini",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "The capital of France is Paris."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 20,
"completion_tokens": 10,
"total_tokens": 30
}
}
```
### Stream Response
Each chunk format:
```json theme={null}
{
"id": "chatcmpl-abc123",
"object": "chat.completion.chunk",
"created": 1699999999,
"model": "gpt-4o-mini",
"choices": [
{
"index": 0,
"delta": {
"content": "Paris"
},
"finish_reason": null
}
]
}
```
Last chunk (finish\_reason not null):
```json theme={null}
{
"id": "chatcmpl-abc123",
"object": "chat.completion.chunk",
"created": 1699999999,
"model": "gpt-4o-mini",
"choices": [
{
"index": 0,
"delta": {},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 20,
"completion_tokens": 10,
"total_tokens": 30
}
}
```
## Response Field Descriptions
Unique request identifier
Object type:
* `chat.completion`: Standard response
* `chat.completion.chunk`: Stream response chunk
Creation timestamp (Unix timestamp)
Model name used
Generated results array, typically containing one result
Result index
Message object (standard response)
Role, always `assistant`
Generated content
Incremental content (stream response)
This chunk's content
Completion reason:
* `stop`: Natural completion
* `length`: Reached `max_tokens` limit
* `content_filter`: Content filtered by policy
* `null`: Not yet finished (stream output)
Token usage statistics
Input tokens
Output tokens
Total tokens
## Special Usage
### GPT-4o Vision
```python theme={null}
from openai import OpenAI
client = OpenAI(
api_key="YOUR_API_KEY",
base_url="https://api2.laozhang.ai/v1"
)
completion = client.chat.completions.create(
model="gpt-4o",
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "Please describe this image in detail"},
{
"type": "image_url",
"image_url": {
"url": "https://example.com/image.jpg",
# Optional: control image quality
# "detail": "high" # or "low"
}
}
]
}
],
max_tokens=1000
)
print(completion.choices[0].message.content)
```
**Multiple Images**
GPT-4o supports analyzing multiple images simultaneously, just add multiple `image_url` objects to the content array.
### Claude Native Format
Claude models also support native format:
```python theme={null}
import anthropic
client = anthropic.Anthropic(
api_key="YOUR_API_KEY",
base_url="https://api2.laozhang.ai/v1"
)
message = client.messages.create(
model="claude-3-5-sonnet-20241022",
max_tokens=1024,
messages=[
{"role": "user", "content": "Hello, Claude"}
]
)
print(message.content[0].text)
```
### O1 Series Special Parameters
O1 series models (o1-preview, o1-mini) have parameter limitations:
**O1 Series Limitations**
* Do not support `system` role messages
* Do not support stream output (`stream` must be `false`)
* Do not support `temperature`, `top_p`, `presence_penalty`, `frequency_penalty` parameters
* `max_tokens` defaults to model's maximum value
Correct usage:
```python theme={null}
completion = client.chat.completions.create(
model="o1-mini",
messages=[
{
"role": "user",
"content": "Please solve this math problem: ..."
}
]
)
```
## Usage Tips
### Multi-turn Dialogue
Implement multi-turn dialogue by passing context:
```python theme={null}
messages = [
{"role": "system", "content": "You are a helpful assistant"},
]
# First round
messages.append({"role": "user", "content": "What's the weather in Beijing?"})
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=messages
)
messages.append({"role": "assistant", "content": response.choices[0].message.content})
# Second round
messages.append({"role": "user", "content": "What about Shanghai?"})
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=messages
)
```
### JSON Output
Get structured JSON output:
```python theme={null}
completion = client.chat.completions.create(
model="gpt-4o-mini",
messages=[
{
"role": "system",
"content": "You are a helpful assistant. Always output in JSON format."
},
{
"role": "user",
"content": "Extract structured fields from this support ticket: ticket A-1024, priority high, department engineering"
}
],
response_format={"type": "json_object"} # Force JSON output
)
import json
result = json.loads(completion.choices[0].message.content)
print(result)
```
**JSON Mode Support**
Currently supports JSON mode models:
* GPT-4o series
* GPT-4-turbo series
* GPT-3.5-turbo-1106 and later versions
## Billing
Billing is based on actual token usage:
**Total Cost = (Input Tokens × Input Price + Output Tokens × Output Price)**
**Save Costs**
1. Choose appropriate models: Most scenarios don't require GPT-4o, gpt-4o-mini or gpt-3.5-turbo are sufficient
2. Control context length: Only pass necessary historical messages
3. Set `max_tokens`: Avoid unnecessarily long output
4. Use mini series models: For simple tasks, mini models are lightweight choices
### Model Price Reference
| Model | Input Price | Output Price | Features |
| ----------------- | ----------------- | ---------------- | ------------------------------------------------- |
| gpt-4o-mini | \$0.15/1M tokens | \$0.60/1M tokens | Cost-effective, supports image understanding |
| gpt-4o | \$2.5/1M tokens | \$10/1M tokens | Strongest capabilities, supports multimodal |
| claude-3-5-sonnet | \$3/1M tokens | \$15/1M tokens | Excellent reasoning, supports image understanding |
| gemini-1.5-flash | \$0.075/1M tokens | \$0.3/1M tokens | Fastest speed, long context |
For complete pricing, see [Pricing](/en/pricing)
## Error Handling
Common error codes:
| Error Code | Meaning | Solution |
| ---------- | --------------------------- | -------------------------------------------------------- |
| 401 | API Key invalid or missing | Check if API Key is correct |
| 429 | Request rate limit exceeded | Slow down request frequency or upgrade plan |
| 500 | Server internal error | Retry request or contact support |
| 400 | Request parameter error | Check if request parameters conform to API documentation |
Error response example:
```json theme={null}
{
"error": {
"message": "Invalid API key provided",
"type": "invalid_request_error",
"code": "invalid_api_key"
}
}
```
## Best Practices
1. **Use Appropriate Temperature**
* Translation, summarization, Q\&A: temperature=0
* General dialogue: temperature=0.7
* Creative writing: temperature=1.0-1.5
2. **Control Context Length**
* Only pass necessary historical messages
* Regularly clean up irrelevant context
* Long documents can be processed in segments
3. **Choose Right Model**
* Simple tasks: gpt-4o-mini, gpt-3.5-turbo
* Reasoning tasks: claude-3-5-sonnet, gpt-4o
* Cost-sensitive: gemini-1.5-flash
4. **Error Retry**
* Implement exponential backoff retry mechanism
* Catch and handle different error types
* Set reasonable timeout
5. **Stream Output**
* Better user experience for long responses
* Reduce perceived latency
* Can implement typewriter effect
## Related Resources
* [Models API](/en/api-reference/models) - Get complete available model list
* [Images API](/en/api-reference/images) - Image generation and editing
* [OpenAI Models Guide](/en/api-reference/openai) - Detailed GPT-4o usage
* [Claude Models Guide](/en/api-reference/claude) - Detailed Claude usage
* [Gemini Models Guide](/en/api-reference/gemini) - Detailed Gemini usage