Chat Completions

Endpoint

POST /v1/chat/completions

The 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

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["YUNXIN_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: process.env.YUNXIN_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 $YUNXIN_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://..."}}`
`file_url`	Document/file (e.g. PDF) via URL or base64 data URI	`{"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"}}
        ]
    }]
)

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. Image and document inputs are routed to the underlying provider's native format automatically.

Streaming & response metadata

Set "stream": true to receive the response incrementally as server-sent events. See Streaming for the chunk format and SDK examples.

Every response carries an X-Request-ID header (echoed in errors as error.request_id). When Yunxin routes or falls back to an alternate provider, it surfaces this transparently:

Header	Meaning
`X-Request-ID`	Unique id for the request — include it in support tickets.
`X-Routing-Mode`	`auto` (Yunxin picked the provider) or `custom` (you pinned one).
`X-Routing-Resolved-Model`	The concrete model that served the request.
`X-Fallback-Used`	`true` if a fallback provider was used.
`X-Fallback-Provider` / `X-Fallback-Reason`	Which provider served the fallback, and why.

During streaming, the same information may also arrive as inline event: routing and event: fallback SSE events before the content chunks.

Endpoint

POST /v1/chat/completions

The 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

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["YUNXIN_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: process.env.YUNXIN_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 $YUNXIN_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://..."}}`
`file_url`	Document/file (e.g. PDF) via URL or base64 data URI	`{"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"}}
        ]
    }]
)

Streaming & response metadata

Set "stream": true to receive the response incrementally as server-sent events. See Streaming for the chunk format and SDK examples.

Every response carries an X-Request-ID header (echoed in errors as error.request_id). When Yunxin routes or falls back to an alternate provider, it surfaces this transparently:

Header	Meaning
`X-Request-ID`	Unique id for the request — include it in support tickets.
`X-Routing-Mode`	`auto` (Yunxin picked the provider) or `custom` (you pinned one).
`X-Routing-Resolved-Model`	The concrete model that served the request.
`X-Fallback-Used`	`true` if a fallback provider was used.
`X-Fallback-Provider` / `X-Fallback-Reason`	Which provider served the fallback, and why.

During streaming, the same information may also arrive as inline event: routing and event: fallback SSE events before the content chunks.

Endpoint

Request Body

Parameters

Message Object

Response

Examples

Basic Conversation

JSON Mode

Multi-Turn Conversation

Multimodal Messages

Content Types

Image Input

Document Input

Streaming & response metadata

On this page

Chat Completions

Endpoint

Request Body

Parameters

Message Object

Response

Examples

Basic Conversation

JSON Mode

Multi-Turn Conversation

Multimodal Messages

Content Types

Image Input

Document Input

Streaming & response metadata

On this page