API 使用指南
聊天（Chat Completions）
用 OpenAI Chat Completions 协议调用 LynShen 中的任意聊天模型。
Chat Completions 是兼容性最广的协议。OpenAI SDK、LangChain 和大多数第三方客户端默认使用它。
- 端点：
POST https://api.lynshen.org/v1/chat/completions - 认证：
Authorization: Bearer sk-...或x-api-key: sk-...
基本请求
curl https://api.lynshen.org/v1/chat/completions \
-H "Authorization: Bearer $LYNSHEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-sonnet-5",
"messages": [
{ "role": "system", "content": "你是一名简洁的技术助手。" },
{ "role": "user", "content": "HTTP 和 HTTPS 的区别是什么？" }
],
"max_tokens": 1024
}'常用请求字段
| 字段 | 说明 |
|---|---|
model | 必填。从 /v1/models 中选择。 |
messages | 必填。角色可以是 system、developer、user、assistant、tool。 |
stream | 设为 true 时返回 SSE 流。见流式输出。 |
max_tokens / max_completion_tokens | 输出上限。 |
temperature、top_p、stop、seed | 采样参数。部分推理模型只接受默认值，见下文。 |
tools、tool_choice、parallel_tool_calls | 工具调用。见工具调用。 |
response_format | 结构化输出。见结构化输出。 |
reasoning_effort | 推理强度。见思维链（推理）。 |
n | 只能省略或设为 1。其他值返回 HTTP 400。 |
网关会把未识别的字段转发给兼容的上游。上游不支持某个字段时，可能忽略它或返回错误。
多轮对话
网关不保存 Chat Completions 的对话历史。每次请求都要发送完整的 messages 数组，包括之前的 assistant 回复。
{
"model": "deepseek-v4-pro",
"messages": [
{ "role": "user", "content": "我叫小林。" },
{ "role": "assistant", "content": "你好，小林。" },
{ "role": "user", "content": "我叫什么名字？" }
]
}图片输入
把图片放进 user 消息的 content 数组。url 可以是 HTTPS 地址，也可以是 Base64 数据 URL。
{
"model": "claude-sonnet-5",
"messages": [
{
"role": "user",
"content": [
{ "type": "text", "text": "这张图里有什么？" },
{ "type": "image_url", "image_url": { "url": "data:image/png;base64,iVBORw0KGgo..." } }
]
}
]
}网关会把图片转换成上游需要的格式。例如，调用 Claude 模型时，网关把数据 URL 转换成 Messages 的 image 块。所选模型必须支持图片输入。
响应
{
"id": "chatcmpl-...",
"object": "chat.completion",
"created": 1791730160,
"model": "claude-sonnet-5",
"choices": [
{
"index": 0,
"message": { "role": "assistant", "content": "HTTPS 在 HTTP 之上加了 TLS 加密……" },
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 32,
"completion_tokens": 120,
"total_tokens": 152,
"prompt_tokens_details": { "cached_tokens": 0 },
"completion_tokens_details": { "reasoning_tokens": 0 }
}
}| 字段 | 说明 |
|---|---|
choices[0].message.content | 回复文本。只有工具调用时可能为 null。 |
choices[0].message.tool_calls | 模型请求调用的工具。 |
choices[0].message.reasoning、reasoning_content、reasoning_details | 推理内容。见思维链（推理）。 |
choices[0].finish_reason | stop、length、tool_calls 或 content_filter。 |
usage.prompt_tokens_details.cached_tokens | 命中缓存的输入 Token 数。 |
usage.completion_tokens_details.reasoning_tokens | 推理消耗的输出 Token 数。上游不报告时为 0。 |
响应中可能出现上游特有的额外字段。客户端应忽略不认识的字段。
限制和注意事项
- Chat Completions 不能返回图片。模型输出图片时，网关返回 HTTP
502unsupported_output_media。需要生成图片时，使用 Images 或 Responses 协议。 - 较新的 Claude 模型（例如 Opus 4.7 及以后、Sonnet 5 及以后）只接受默认的
temperature、top_p，并且不接受top_k。开启推理时，Claude 模型要求temperature为1或不传。不满足时，网关在发送前返回 HTTP400invalid_request。 - 请求体上限为 50 MiB。
旧版 Completions
网关也支持旧版 POST /v1/completions。网关把它转换成一次 Chat Completions 请求。prompt 必须是一个字符串，或只含一个字符串的数组。suffix、echo、best_of、logprobs 会返回 HTTP 400。新项目请使用 Chat Completions。