Chat Completions
Generate text responses using the OpenAI-compatible Chat Completions API.
Endpoint
POST /v1/chat/completionsThe Chat Completions API is the primary endpoint for text generation. It is fully compatible with the OpenAI Chat Completions format, allowing you to use any OpenAI SDK client.
Request Body
{
"model": "model-id",
"messages": [
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "What is the capital of France?"}
],
"temperature": 0.7,
"max_tokens": 1024,
"stream": false
}Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
model | string | Yes | Model ID to use (query /v1/models for available models) |
messages | array | Yes | Array of message objects |
temperature | number | No | Sampling temperature (0–2). Default: 1 |
max_tokens | integer | No | Maximum tokens to generate |
top_p | number | No | Nucleus sampling parameter (0–1) |
stream | boolean | No | Enable streaming. Default: false |
stop | string/array | No | Stop sequences |
frequency_penalty | number | No | Frequency penalty (-2 to 2) |
presence_penalty | number | No | Presence penalty (-2 to 2) |
tools | array | No | Available function tools |
tool_choice | string/object | No | Tool selection strategy |
response_format | object | No | Output format (e.g., {"type": "json_object"}) |
Message Object
| Field | Type | Required | Description |
|---|---|---|---|
role | string | Yes | system, user, assistant, or tool |
content | string/array | Yes | Message content (text or multimodal array) |
name | string | No | Name of the participant |
tool_calls | array | No | Tool calls made by the assistant |
tool_call_id | string | No | ID of the tool call being responded to |
Response
{
"id": "chatcmpl-abc123",
"object": "chat.completion",
"created": 1709251200,
"model": "model-id",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "The capital of France is Paris."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 25,
"completion_tokens": 8,
"total_tokens": 33
}
}Examples
Basic Conversation
from openai import OpenAI
client = OpenAI(
api_key="YOUR_API_KEY",
base_url="https://api.yuhuanstudio.com/v1"
)
response = client.chat.completions.create(
model="model-id",
messages=[
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Explain quantum computing in simple terms."}
],
temperature=0.7,
max_tokens=500
)
print(response.choices[0].message.content)import OpenAI from "openai";
const client = new OpenAI({
apiKey: "YOUR_API_KEY",
baseURL: "https://api.yuhuanstudio.com/v1",
});
const response = await client.chat.completions.create({
model: "model-id",
messages: [
{ role: "system", content: "You are a helpful assistant." },
{ role: "user", content: "Explain quantum computing in simple terms." },
],
temperature: 0.7,
max_tokens: 500,
});
console.log(response.choices[0].message.content);curl https://api.yuhuanstudio.com/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"model": "model-id",
"messages": [
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Explain quantum computing in simple terms."}
],
"temperature": 0.7,
"max_tokens": 500
}'JSON Mode
Force the model to output valid JSON:
response = client.chat.completions.create(
model="model-id",
messages=[
{"role": "system", "content": "Output JSON only."},
{"role": "user", "content": "List 3 programming languages with their year of creation."}
],
response_format={"type": "json_object"}
)Multi-Turn Conversation
messages = [
{"role": "system", "content": "You are a math tutor."},
{"role": "user", "content": "What is a derivative?"},
{"role": "assistant", "content": "A derivative measures the rate of change of a function..."},
{"role": "user", "content": "Can you give me an example?"}
]
response = client.chat.completions.create(
model="model-id",
messages=messages
)Multimodal Messages
The content field of a message supports an array of content parts, enabling you to send text, images, documents, and videos in a single request.
Content Types
| Type | Description | Example |
|---|---|---|
text | Plain text content | {"type": "text", "text": "Describe this image"} |
image_url | Image via URL or base64 data URI | {"type": "image_url", "image_url": {"url": "https://..."}} |
video_url | Video via URL | {"type": "video_url", "video_url": {"url": "https://..."}} |
file_url | Document/file via URL | {"type": "file_url", "file_url": {"url": "https://..."}} |
Image Input
{
"role": "user",
"content": [
{"type": "text", "text": "What's in this image?"},
{"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg"}}
]
}Images can be provided as HTTPS URLs or base64 data URIs:
import base64
with open("image.png", "rb") as f:
b64 = base64.b64encode(f.read()).decode()
response = client.chat.completions.create(
model="model-id",
messages=[{
"role": "user",
"content": [
{"type": "text", "text": "Describe this image."},
{"type": "image_url", "image_url": {"url": f"data:image/png;base64,{b64}"}}
]
}]
)Document Input
Attach documents (PDFs, text files, etc.) for analysis using file_url:
{
"role": "user",
"content": [
{"type": "text", "text": "Summarize this document."},
{"type": "file_url", "file_url": {"url": "https://example.com/report.pdf"}}
]
}You can also use files uploaded via the File API:
# Upload a file first
file = client.files.create(
file=open("report.pdf", "rb"),
purpose="assistants"
)
# Then reference it in a chat message
response = client.chat.completions.create(
model="model-id",
messages=[{
"role": "user",
"content": [
{"type": "text", "text": "Summarize this report."},
{"type": "file_url", "file_url": {"url": f"https://api.yuhuanstudio.com/v1/files/{file.id}/content"}}
]
}]
)Video Input
{
"role": "user",
"content": [
{"type": "text", "text": "Describe what happens in this video."},
{"type": "video_url", "video_url": {"url": "https://example.com/clip.mp4"}}
]
}Not all models support all content types. Use the GET /v1/models endpoint and check the model's capabilities array (e.g., vision) to determine which content types a model supports.
How is this guide?