通用对话接口 | API 文档

统一的对话 API 接口，支持通过 model 参数切换不同文本模型，并兼容 OpenAI Chat Completions 请求格式。

本接口默认返回完整 JSON。需要 SSE 流式输出时，请显式设置 stream: true。

text

POST https://api.requestbeam.com/v1/chat-completions

验证

所有接口都需要使用 Bearer Token 进行认证。

http

Authorization: Bearer YOUR_API_KEY

如果请求直接返回认证错误，请优先检查：

API Key 是否正确
Key 是否适用于当前 API Base URL
请求头是否拼写正确
代理层是否改写了请求头

Body

modelstring必填默认: gpt-5.4

当前 active 文本模型：

OpenAI：gpt-5.4、gpt-5.5、gpt-5.6-sol、gpt-5.6-terra、gpt-6-astra
Anthropic：claude-fable-5、claude-fable-5-1、claude-haiku-4-5、claude-opus-4-5、claude-opus-4-6、claude-opus-4-7、claude-opus-4-8、claude-opus-5、claude-opus-5-5、claude-sonnet-4-5、claude-sonnet-4-6、claude-sonnet-5
DeepSeek：deepseek-v4-flash、deepseek-v4-pro、deepseek-v4.1-flash

（V4.1 Flash 是独立模型 ID，部署启用后才可用，以 GET https://api.requestbeam.com/v1/models 为准）。

Gemini：gemini-3.6-flash、gemini-3.7-flash、gemini-3.8-flash、gemini-3.5-flash-lite
Kimi：kimi-k3
MiniMax：minimax-m3

完整目录和当前 API Key 的实际可见范围见模型目录。当前可用范围以你自己的 GET https://api.requestbeam.com/v1/models 返回为准。各模型族的选择建议和示例见 DeepSeek、 Gemini、Kimi 和 MiniMax 文档。

messagesobject[]必填

对话消息数组。每条消息都需要包含：

role：system、user 或 assistant
content：消息内容

角色说明：

user：用户输入
system：系统提示词，用于设置助手行为或角色
assistant：历史回复，用于多轮上下文

示例：

json

  [
    {"role": "system", "content": "你是专业的Python导师"},
    {"role": "user", "content": "如何学习编程？"}
  ]

temperaturenumber默认: 1.0

控制输出随机性。OpenAI-compatible 客户端常用 0 到 2，但本接口会把参数交给所选模型判断，实际范围以模型返回结果为准。

较低的值（如 0.2）：使输出更具确定性。
较高的值（如 1.8）：使输出更具随机性。

max_tokensinteger

可选的最大输出 token 数量，使用正整数。省略时使用所选模型的上游默认额度；默认额度和最大值限制因模型和上游配置而异。

不同模型的额度可能同时包含推理 token 和最终正文。较小额度可能导致 finish_reason: "length"、回答截断，或在生成正文前耗尽。提高额度可能增加费用。

max_completion_tokensinteger

max_tokens 的可选兼容字段，适用相同的额度注意事项。具体模型可能只接受其中一个字段，切换模型时建议从最小请求体开始验证。省略这两个字段时使用上游默认额度。

streamboolean默认: false

是否使用流式输出。

true：流式返回（SSE 格式）。
false：一次性返回完整响应。

top_pnumber默认: 1.0

核采样参数。OpenAI-compatible 客户端常用 0 到 1，实际范围由所选模型判断。

控制生成文本的多样性，建议与 temperature 二选一使用。

frequency_penaltynumber默认: 0

频率惩罚。OpenAI-compatible 客户端常用 -2.0 到 2.0，实际范围由所选模型判断。

正值会降低重复使用相同词汇的可能性。

presence_penaltynumber默认: 0

存在惩罚。OpenAI-compatible 客户端常用 -2.0 到 2.0，实际范围由所选模型判断。

正值会增加谈论新主题的可能性。

stopstring | array

停止序列。

可以传字符串或字符串数组。可接受的数量和具体效果由所选模型判断。

ninteger默认: 1

生成的回复数量。

⚠️ 注意：必须输入纯数字（如 1），不要加引号，否则会报错。

模型参数差异

当前文本模型支持最小非流式和流式 Chat 请求，但可选参数的接受范围与实际效果会因所选模型及其兼容实现而异。

2026-09-26 的最新复测中，claude-fable-5 的 temperature: 0 被接受并返回正文，但 claude-sonnet-5 的 top_p: 0.9 返回 HTTP 400，错误为 top_p is deprecated；使用该模型时请省略 top_p。请求被接受不证明参数实际改变采样行为，也不保证其他模型或后续请求具有相同表现，不能据此认定所有采样参数均受支持。

2026-09-26 的 OpenAI 验证中，gpt-5.6-sol 和 gpt-5.6-terra 接受了 stop。参数接受情况会随上游变化，接受请求不代表停止序列一定生效。

原生 OpenAI 兼容 Chat 转发会在上游请求中保留 top_p 和 stop。若所选通道将 Chat 转为 Responses，则保留 top_p，但不转发 stop。字段被转发不等于上游支持或实际生效，平台不保证这两个参数在所有通道上的表现一致。

切换模型时先使用最小请求，分别验证采样、停止序列和高级工具参数。对于停止序列，检查实际文本和停止原因，而不只检查 HTTP 状态；对于采样参数，不要把 HTTP 200 当作效果验证。输出预算需同时覆盖模型的 thinking 和最终正文。

请求体示例

基础对话

json

{
  "model": "gpt-5.4",
  "messages": [
    {
      "role": "user",
      "content": "你好，请介绍一下你自己"
    }
  ],
  "stream": false
}

Response

idstring

响应的唯一标识符。

objectstring

对象类型。

通常固定为 chat.completion（若是流式输出，通常为 chat.completion.chunk）。

createdinteger

创建时间戳。

记录该响应生成的 Unix 时间。

modelstring

响应中返回的模型标识。

choicesarray

模型生成结果列表。

包含了具体的回复内容（message）、索引（index）以及停止原因（finish_reason）等信息。

usageobject

Token 使用统计。

包含提示词消耗（prompt_tokens）、生成消耗（completion_tokens）以及总 Token 数量（total_tokens）。

成功响应示例

json

{
  "id": "chatcmpl-9876543210",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "人工智能（AI）的发展历史可以追溯到20世纪50年代..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 28,
    "completion_tokens": 320,
    "total_tokens": 348
  }
}

失败响应

完整错误码、协议差异和排查步骤见错误码与错误处理。

Chat Completions 的 HTTP 错误使用扁平 JSON 格式，包括 SSE 流开始前返回的上游 HTTP 错误。例如，HTTP 402 返回：

json

{
  "code": 40000,
  "message": "Insufficient credit. Required: 30000, Available: 20000",
  "type": "api_error"
}

字段说明：

code：数字平台业务错误码，与 HTTP 状态码分开，也不是字符串
message：供人阅读的错误说明
type：固定为 api_error
requestId：可选的请求标识，用于排查问题

HTTP 状态码	`code`	含义
400	10000	请求参数错误
401	20000	缺少认证信息或认证无效
402	40000	余额不足
403	20001	无访问权限或模型对当前 Key 不可用
404	30000	模型或资源不存在
409	30001	请求冲突
422	10001	参数校验失败
429	40001	请求频率超限
500	50003	内部错误
502	50000	上游供应商错误
503	50001	服务不可用
504	50002	网关超时

客户端应先根据 HTTP 状态码判断请求是否成功，再通过数字类型的 code 处理具体业务错误。不要将 code 与 "400" 等字符串比较，不要假设它等于 HTTP 状态码，也不要解析 message 来识别固定错误类型。messages 缺失或类型错误时，在调用供应商前返回 HTTP 400 和 code: 10000。

此格式仅适用于 Chat Completions 的 HTTP 错误响应，不适用于已经开始的 SSE 流内错误或其他 API 协议。模型目录及原生协议接口的错误格式以各自文档为准。