对话补全
DeerAPI Chat Completions 文档：统一调用 OpenAI 等模型的 /v1/chat/completions 接口，基于 messages 对话列表生成回复，支持 stream 流式输出、reasoning_effort 推理控制、web_search_options 网页搜索等参数，并说明响应透传与模型差异。
curl https://api.deerapi.com/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <DEERAPI_KEY>" \
-d '{
"model": "gpt-5.4",
"messages": [
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Hello!"}
]
}'{
"id": "<string>",
"object": "<string>",
"created": 123,
"model": "<string>",
"system_fingerprint": "<string>",
"choices": [
{
"index": 123,
"message": {
"content": "<string>",
"refusal": "<string>",
"role": "<string>",
"annotations": [
{}
],
"tool_calls": [
{}
]
},
"finish_reason": "<string>"
}
],
"usage": {
"completion_tokens": 123,
"completion_tokens_details": {
"reasoning_tokens": 123,
"audio_tokens": 123,
"accepted_prediction_tokens": 123,
"rejected_prediction_tokens": 123
},
"prompt_tokens": 123,
"prompt_tokens_details": {
"cached_tokens": 123,
"audio_tokens": 123
},
"total_tokens": 123
},
"service_tier": "<string>"
}概述
chat/completions 是目前 LLM 最常见的 API 接口，通过由多条消息组成的对话列表作为输入，获取模型响应结果。
重要说明
⚠️ 模型差异性不同模型供应商支持的请求参数和返回的响应字段可能存在差异。我们强烈建议您查阅相应模型供应商的官方文档以了解完整的参数列表和使用方法。 ⚠️ 响应透传原则
DeerAPI 通常情况下不会修改逆向格式之外的模型响应结果，确保您能获得与原始 API 一致的响应内容。 ⚠️ OpenAI Pro 模型限制
对于 OpenAI Pro 系列模型，请使用
responses 接口。
参考文档
如果您想了解更多关于chat/completions 接口的详细信息，建议参考 OpenAI 官方文档。
OpenAI 相关指南：
常见问题
如何处理速率限制？
遇到429 Too Many Requests 时，建议实现指数退避重试：
import time
import random
def chat_with_retry(messages, max_retries=3):
for i in range(max_retries):
try:
response = client.chat.completions.create(
model="gpt-5.4",
messages=messages
)
return response
except RateLimitError:
if i < max_retries - 1:
wait_time = (2 ** i) + random.random()
time.sleep(wait_time)
else:
raise
如何维护对话上下文？
将完整的对话历史包含在messages 数组中：
conversation_history = [
{"role": "developer", "content": "你是一个有帮助的助手"},
{"role": "user", "content": "什么是 Python？"},
{"role": "assistant", "content": "Python 是一种编程语言..."},
{"role": "user", "content": "它有什么优势？"}
]
finish_reason 的含义？
| 值 | 含义 |
|---|---|
stop | 自然结束 |
length | 达到 max_completion_tokens 限制 |
content_filter | 触发内容过滤 |
tool_calls | 模型调用了工具 |
如何控制成本？
- 使用
max_completion_tokens限制输出长度 - 选择合适的模型（如 gpt-5-mini 更经济）
- 精简 prompt，避免冗余上下文
- 监控
usage字段的 token 消耗 - 对支持推理的模型，可通过
reasoning_effort降低推理强度
Authorizations
Bearer token authentication. Use your DeerAPI key.
Body
兼容 OpenAI Chat Completions。这里优先列出最常用、最稳定的字段；未列出的兼容字段通常也会按原格式透传，但建议优先围绕这些字段设计请求。不同模型对工具调用、音频输出、结构化输出等能力的支持度会有差异。
要调用的模型 ID。对于常规文本对话、多轮上下文、函数调用，通常直接使用 /v1/chat/completions 即可。示例：gpt-5.4、gpt-5-mini、gpt-4.1。
对话历史数组，按时间顺序传入。最后一条通常是最新问题。最重要的是把模型需要参考的上下文都放进这里；是否支持 developer、图像块、工具结果等高级内容，取决于具体模型。
Show child attributes
Show child attributes
是否启用流式响应。设为 true 后，会以 SSE 逐块返回增量内容；适合打字机效果、长文本生成和工具调用过程展示。
采样温度，范围通常为 0-2。越低越稳定，越高越发散。做分类、抽取、改写时建议用低值；做创意生成时再提高。建议只调 temperature 或 top_p 其中一个。
0 <= x <= 2核采样阈值，范围 0-1。如果你更习惯控制“候选词覆盖面”，可以用它代替 temperature。
0 <= x <= 1限制本次回复最多生成多少 token。对 GPT-5 及部分新模型，更推荐优先使用这个字段，因为它通常同时覆盖可见输出和推理 token。
旧字段，仍有不少模型兼容。若你主要面向历史 Chat Completions 工作流，可以继续使用；若文档或代码面向新模型，优先改用 max_completion_tokens。
存在惩罚，范围通常为 -2 到 2。正值会鼓励模型引入新主题，适合避免一直围绕同一表述打转。
频率惩罚，范围通常为 -2 到 2。正值更适合压制重复措辞、列表赘述和模板化回答。
停止序列。你可以传单个字符串，或最多 4 个字符串数组。命中后模型会提前停止输出，适合严格控制模板结尾。
可供模型调用的工具列表。最常见的是 function 工具，用于让模型按你定义的 JSON 参数去调用业务函数。
Show child attributes
Show child attributes
控制模型如何使用工具。常见值：auto（自动判断）、none（禁用工具）、required（必须调用工具），也可以指定某一个函数。
控制输出格式。最常见用法是要求 json_schema，让模型按固定结构返回，适合表单抽取、工作流节点和前端直出 JSON。
Show child attributes
Show child attributes
声明希望模型返回哪些模态。大多数文本场景不传即可；若要语音输出，可结合 audio 使用。
text, audio 当请求音频输出时使用。
Show child attributes
Show child attributes
流式输出的附加控制项。只有 stream=true 时才需要传。
Show child attributes
Show child attributes
附加到请求上的业务元数据。适合写入任务 ID、场景名、租户标识等，便于你在日志与回调中追踪。
推理强度控制。用于推理模型（如 o 系列、gpt-5.1 及更新模型），值越高推理越深入但耗时更长。gpt-5.1 默认 none，更早模型默认 medium。
none, minimal, low, medium, high, xhigh 为每条输入生成多少个候选回复。注意所有候选消耗的 token 都会计费。大多数场景保持默认 1 即可。
1 <= x <= 128是否返回输出 token 的 log 概率。设为 true 后在 choices[].logprobs 中可获取每个 token 的概率信息。
每个位置返回前 N 个最可能的 token 及其 log 概率。需要同时设置 logprobs=true。
0 <= x <= 20修改指定 token 的出现概率。传入 token ID 到偏置值（-100 到 100）的映射。
是否允许并行函数调用。默认 true，在需要顺序执行工具时可关闭。
预测输出内容。适合文件重新生成等已知大部分输出的场景，可以加速生成并降低成本。
Show child attributes
Show child attributes
是否存储本次请求输出，供模型蒸馏或评估使用。
终端用户稳定标识，用于安全风控和违规检测。建议传哈希后的用户 ID。
处理档位。auto 使用项目默认设置，flex 和 priority 分别对应不同延迟和价格策略。
auto, default, flex, priority 控制模型回答的冗长度。low 更简洁，high 更详细。
low, medium, high 网页搜索工具选项。启用后模型可搜索网络获取实时信息。
Show child attributes
Show child attributes
提示词缓存键。用于提高相似请求的缓存命中率。替代旧版 user 字段的缓存功能。
提示词缓存保留策略。24h 可延长缓存前缀的有效时间。
in-memory, 24h 旧版用户标识字段，正在被 safety_identifier 和 prompt_cache_key 替代。
Response
Successful Response
本次API请求的唯一标识符。
返回对象的类型，
请求处理完成时的Unix时间戳
本次请求所使用的具体模型名称。
系统指纹，代表了模型运行所使用的后端配置。
模型返回的候选结果列表。多数场景只有 1 个元素；如果显式请求多个候选，这里会按顺序返回。
Show child attributes
Show child attributes
本次请求的 token 使用量统计。
Show child attributes
Show child attributes
实际使用的服务档位。
curl https://api.deerapi.com/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <DEERAPI_KEY>" \
-d '{
"model": "gpt-5.4",
"messages": [
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Hello!"}
]
}'{
"id": "<string>",
"object": "<string>",
"created": 123,
"model": "<string>",
"system_fingerprint": "<string>",
"choices": [
{
"index": 123,
"message": {
"content": "<string>",
"refusal": "<string>",
"role": "<string>",
"annotations": [
{}
],
"tool_calls": [
{}
]
},
"finish_reason": "<string>"
}
],
"usage": {
"completion_tokens": 123,
"completion_tokens_details": {
"reasoning_tokens": 123,
"audio_tokens": 123,
"accepted_prediction_tokens": 123,
"rejected_prediction_tokens": 123
},
"prompt_tokens": 123,
"prompt_tokens_details": {
"cached_tokens": 123,
"audio_tokens": 123
},
"total_tokens": 123
},
"service_tier": "<string>"
}