Skip to main content
POST

认证

string
必填
Bearer Token 认证。格式:Authorization: Bearer <api-key>获取 API Key:访问 API Key 管理页面 获取您的 API Key
string
替代认证方式,与 Authorization 二选一。格式:x-api-key: <api-key>

请求体参数

string
必填
要使用的模型名称。示例:gpt-4o、gpt-5.4、gpt-5.5等。可通过 GET /api/v1/models 获取完整模型列表。
array
必填
输入内容列表输入数组,每个输入项包含 role 和 content 两个字段。支持多轮对话和多模态内容(文本+图像)。
string
系统提示词(System Prompt)。用于设定模型的行为准则、角色身份或上下文背景。等效于消息数组中 role: "system" 的消息。
boolean
默认值:"true"
是否启用流式输出。
  • true(默认):以 SSE 事件流方式逐 token 返回,适合实时展示
  • false:等待完整响应后一次性返回,适合批量处理
integer
生成回复的最大 token 数。超出限制时响应 status 为 "incomplete",incomplete_details.reason 为 "max_output_tokens"。
number
采样温度,范围 0 ~ 2。值越高输出越随机,值越低输出越确定性。不建议同时修改 temperature 和 top_p。
number
核采样概率,范围 0 ~ 1。模型仅从累积概率达到 top_p 的 token 中采样。
array
可供模型调用的工具列表。当前仅支持 type: "function" 类型,不支持 web_search、file_search、computer_use 等内置工具。
string | object
默认值:"auto"
工具调用策略:
  • "auto":模型自动决定是否调用工具
  • "none":禁止调用工具
  • "required":强制调用至少一个工具
  • { "type": "function", "name": "function_name" }:强制调用指定工具
boolean
默认值:"true"
是否允许模型并行调用多个工具。仅在提供了 tools 时有效。
object
输出格式控制。
object
推理模式配置(适用于支持推理的模型,如 gpt-5.2 及以上)。

响应字段

string
响应唯一标识符,格式:resp_ + 24位随机字符串
string
固定为 "response"
number
响应创建时间,Unix 时间戳(秒,含毫秒精度)
string
响应状态:
  • "completed":正常完成
  • "incomplete":因 max_output_tokens 提前截止
  • "in_progress":流式输出进行中(仅在流式事件中出现)
  • "failed":生成失败
string
实际使用的模型名称
string
平台扩展字段。本次调用的计费任务 ID,可用于对账与消耗查询。注意:
  • 非流式:task_id 直接位于响应 JSON 的顶层
  • 流式:task_id 嵌套在 response.created(第一个事件)和 response.completed(最后一个事件)的 response 对象内,需解析原始 SSE 事件获取,OpenAI SDK 的流式接口不会自动暴露此字段
array
输出内容数组,可包含文本消息和工具调用两种类型。
string
快捷字段,等同于 output[0].content[0].text(纯文本场景)。工具调用场景下为空字符串。
object
Token 用量统计。
object | null
当 status 为 "incomplete" 时不为 null。

流式响应事件

当 stream: true 时,接口以 text/event-stream 格式返回 SSE 事件流。每个事件格式如下:
所有事件 payload 均包含 sequence_number 字段(从 0 递增),用于确保客户端按顺序处理事件。
获取 task_id:如需在流式模式下获取计费任务 ID,请监听第一个 response.created 事件并读取 event.response.task_id。

事件序列(文本响应)

事件序列(工具调用)

事件示例


使用示例

基础文本对话

图像理解

工具调用

结构化输出(JSON Schema)

推理模式

多轮对话

previous_response_id 当前不生效,需手动在 input 中拼接历史消息:

注意事项

  1. 默认流式:stream 参数默认为 true。如需非流式响应,需显式传入 "stream": false。
  2. 积分不足:余额不足时返回 HTTP 402,请充值后重试。
  3. text.format 支持有限:当前底层供应商对结构化输出支持有限——json_object 模式下模型可能仍输出 Markdown 代码块而非纯 JSON;json_schema 模式下 Schema 约束可能不被遵守。如需结构化输出,建议在 instructions 或 input 中明确描述所需格式。
  4. 工具参数:parameters 字段必须是合法的 JSON Schema,required 数组决定哪些参数为必填项。

错误码说明