Chat Completions API

The most commonly used conversation API, fully compatible with the OpenAI Chat Completions interface.

POST/v1/chat/completions创建聊天对话

POST https://hub.lurus.cn/v1/chat/completions

Streaming Responses

Token-by-token via SSE

Function Calling

Let the model call your functions

Multimodal Vision

Mix text and images in one input

Best Practices

Temperature / System Prompt / Multi-turn

---

Request Parameters

Required

Parameter	Type	Description
model	string	Model name, such as deepseek-chat or gpt-4o
messages	array	Array of conversation messages, see the format below

Common Optional Parameters

Parameter	Type	Default	Description
temperature	number	1.0	Randomness (0–2). Use 0.1 for code/math, 0.9 for creative writing
max_tokens	integer	—	Maximum number of tokens to generate. If unset, the model decides
stream	boolean	false	Streaming outputStreamingA streaming response where the AI model returns results token by token rather than waiting for full generation, reducing time to first token. (SSE), see Streaming Responses
top_p	number	1.0	Nucleus sampling; usually adjust either this or temperature, not both
stop	string/array	—	Stop generating when this string is encountered
n	integer	1	Number of candidate replies to generate at once
user	string	—	User identifier, used for audit logs

Messages Format

[
  {"role": "system",    "content": "你是一位专业的技术顾问。"},
  {"role": "user",      "content": "什么是 RESTful API？"},
  {"role": "assistant", "content": "RESTful API 是…"},
  {"role": "user",      "content": "能举个例子吗？"}
]

Role	Purpose
system	Defines the AI’s behavior, tone, and constraints. Place it first in the array
user	The user’s input
assistant	The AI’s reply. In multi-turn conversations you need to include past replies

For the full field definitions of the request body (ChatCompletionRequest) and messages (Message), see the Schema Reference.

---

Basic Example

---

Streaming Responses

Set stream: true and the response is returned token by token via Server-Sent Events, which is ideal for chat-style applications.

Streaming Data Format

data: {"id":"chatcmpl-abc","choices":[{"delta":{"content":"落"},"index":0}]}
data: {"id":"chatcmpl-abc","choices":[{"delta":{"content":"叶"},"index":0}]}
...
data: [DONE]

TIP

The final data: [DONE] indicates the end of the stream, at which point delta.content is empty.

---

Function Calling

Let the AI decide when to call functions you provide, returning structured parameters (Tool CallTool CallWhen an AI model decides during reasoning to call an external tool (such as search or a database query) and returns structured call arguments.). This is useful for scenarios like search, database queries, and calling external APIs.

Workflow

Function Calling Workflow

graph LR; A[Your request<br/>with tools definition] --> B[Model returns<br/>finish_reason: tool_calls]; B --> C[You run the function<br/>result returned as role: tool]; C --> D[Model combines the result<br/>to produce the final answer]

Complete Example: Querying the Weather

Model Support

Function Calling requires model support. We recommend using gpt-4o, gpt-4o-mini, or claude-3-5-sonnet. The DeepSeek series is also supported, but the parameter format has subtle differences, so verify carefully when testing.

---

Multimodal Input (Vision)

Some models can understand image content; mix text and images together in content.

Models That Support Vision

gpt-4o, gpt-4o-mini, gemini-3-pro-preview, gemini-3-pro-image-preview

Image size limits: URL images must be publicly accessible; for Base64, we recommend no more than 5 MB per image.

---

Best Practices

Writing a System Prompt

{
  "role": "system",
  "content": "你是一位专业客服。请用友好简洁的语气回答，每条回复不超过 150 字。如遇无法回答的问题，引导用户联系 support@lurus.cn。"
}

A good System Prompt includes: role definition + tone requirements + length limit + boundary handling.

Temperature Setting Reference

Scenario	temperature	Description
Code generation, math computation	0.0–0.2	Highly deterministic, less randomness
Q&A, summarization, classification	0.3–0.6	Accurate but with some flexibility
Creative writing, brainstorming	0.7–1.0	High diversity
Random stories, role-play	1.0–1.5	Highly creative, may be unstable

Managing Multi-turn Conversations

conversation = [
    {"role": "system", "content": "你是一位历史老师。"}
]

def chat(user_input: str) -> str:
    conversation.append({"role": "user", "content": user_input})
    response = client.chat.completions.create(
        model="deepseek-chat",
        messages=conversation,
        max_tokens=500
    )
    reply = response.choices[0].message.content
    conversation.append({"role": "assistant", "content": reply})
    return reply

print(chat("秦始皇是谁？"))
print(chat("他有哪些重要成就？"))  # 模型能记住上文的"秦始皇"

Context Window Management

Each model has a limited context length (for example, deepseek-chat is 64K tokens). When a conversation grows too long, you can:

1. Truncate the oldest messages (keep system + the most recent N turns)
2. Periodically summarize the conversation history to compress token usage

---

Error Handling

Common status codes: 400 malformed request → check the JSON structure and required parameters; 401 invalid/expired key; 403 no access to this model → contact your administrator; 429 rate limit exceeded → retry with exponential backoff; 500/502 upstream model error → retry or switch to a backup model. For the full list of error codes and retry strategies, see Error Handling.

---

Next Steps

Error HandlingSchemasAuthenticationAPI OverviewSupported Models