Chat Completions API

Chat Completions 是最常用的 API，用于与 AI 模型进行对话交互。

端点

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

请求参数

必填参数

参数	类型	描述
model	string	模型名称，如 deepseek-chat、gpt-4o
messages	array	对话消息数组

可选参数

参数	类型	默认值	描述
temperature	number	1.0	采样温度 (0-2)，越高越随机
top_p	number	1.0	核采样参数
max_tokens	integer	-	最大生成 Token 数
stream	boolean	false	是否启用流式响应
stop	string/array	-	停止生成的标记
presence_penalty	number	0	存在惩罚 (-2 到 2)
frequency_penalty	number	0	频率惩罚 (-2 到 2)
n	integer	1	生成几个回复
user	string	-	用户标识符

Messages 格式

{
  "messages": [
    {"role": "system", "content": "你是一个有帮助的助手"},
    {"role": "user", "content": "你好"},
    {"role": "assistant", "content": "你好！有什么可以帮你的？"},
    {"role": "user", "content": "介绍一下自己"}
  ]
}

角色说明:

• system: 系统指令，设定 AI 的行为和人设
• user: 用户消息
• assistant: AI 回复（用于多轮对话历史）

完整请求示例

curl https://api.lurus.cn/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-api-key" \
  -d '{
    "model": "deepseek-chat",
    "messages": [
      {
        "role": "system",
        "content": "你是一位专业的技术顾问，擅长用简洁的语言解释复杂概念。"
      },
      {
        "role": "user",
        "content": "什么是 RESTful API？"
      }
    ],
    "temperature": 0.7,
    "max_tokens": 500
  }'

响应格式

标准响应

{
  "id": "chatcmpl-abc123xyz",
  "object": "chat.completion",
  "created": 1700000000,
  "model": "deepseek-chat",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "RESTful API 是一种基于 REST（表述性状态转移）架构风格设计的 Web API..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 45,
    "completion_tokens": 120,
    "total_tokens": 165
  }
}

字段说明

字段	描述
id	请求唯一标识
object	固定为 chat.completion
created	Unix 时间戳
model	实际使用的模型
choices	生成的回复数组
choices[].message	AI 回复消息
choices[].finish_reason	结束原因：stop、length、content_filter
usage	Token 使用统计

流式响应

启用 stream: true 后，响应通过 Server-Sent Events 逐块返回：

curl https://api.lurus.cn/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-api-key" \
  -d '{
    "model": "deepseek-chat",
    "messages": [{"role": "user", "content": "写一首诗"}],
    "stream": true
  }'

流式响应格式

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"delta":{"content":"春"},"index":0}]}

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"delta":{"content":"风"},"index":0}]}

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"delta":{"content":"送"},"index":0}]}

data: [DONE]

Python 流式处理

from openai import OpenAI

client = OpenAI(
    base_url="https://api.lurus.cn/v1",
    api_key="sk-your-api-key"
)

stream = client.chat.completions.create(
    model="deepseek-chat",
    messages=[{"role": "user", "content": "写一首诗"}],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

多模态输入 (Vision)

部分模型支持图像输入：

{
  "model": "gemini-3-pro-image-preview",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "描述这张图片"},
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/image.jpg"
          }
        }
      ]
    }
  ]
}

也支持 Base64 编码：

{
  "type": "image_url",
  "image_url": {
    "url": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
  }
}

最佳实践

1. 设置合理的 System Prompt

{
  "messages": [
    {
      "role": "system",
      "content": "你是一位专业的客服代表。请用友好、专业的语气回复客户问题。回复要简洁明了，控制在100字以内。"
    }
  ]
}

2. 控制输出长度

{
  "max_tokens": 500,
  "stop": ["\n\n", "---"]
}

3. 调整创造性

// 精确回答（代码、数学）
{"temperature": 0.1}

// 创意写作
{"temperature": 0.9}

4. 保持对话上下文

conversation = []

def chat(user_message):
    conversation.append({"role": "user", "content": user_message})
    
    response = client.chat.completions.create(
        model="deepseek-chat",
        messages=conversation
    )
    
    assistant_message = response.choices[0].message.content
    conversation.append({"role": "assistant", "content": assistant_message})
    
    return assistant_message

错误处理

常见错误：

错误码	原因	解决方案
400	请求参数错误	检查 JSON 格式和必填参数
401	API Key 无效	检查 Key 是否正确
403	无权限访问模型	联系管理员开通权限
429	速率限制	降低请求频率
500	服务器错误	重试或联系支持

详见 错误处理。