跳到主要内容

Responses API

POST 

/responses

以 OpenAI Responses API 格式创建模型响应。

该 API 是无状态的:服务端不存储响应与会话。多轮对话需要客户端在每次请求的 input 中回传完整对话历史。详细说明(含完整的参数兼容性表)请参考 Responses API 指南。

Request​

Body

required

    model stringrequired

    Possible values: deepseek-flash, deepseek-v4-pro

    使用的模型的 ID。请使用 deepseek-flash 或 deepseek-v4-pro。

    input string | object[]

    nullable

    模型的输入。既可以传纯字符串(视作一条 user 消息),也可以传输入 item 列表。

    支持的输入 item 类型为 message / function_call / function_call_output / custom_tool_call / custom_tool_call_output / reasoning / web_search_call,其他类型会被忽略。消息角色支持 user / assistant / system / developer(developer 在 deepseek-flash 上视同 system,在 deepseek-v4-pro 上视同 user)。使用 deepseek-flash 模型时,user / system / developer 消息 item 以及 function_call_output / custom_tool_call_output item 的 output 中支持 input_image 内容块;assistant 消息中的图片将返回 400 错误。user 消息中支持用 input_file 的 file_id 引用已上传的文件,见文件解析;file_url 不支持。

    input 与 instructions 至少传一个。

    使用联网工具或 safety_check 为 high 时,部分输入 item 不被接受。详见 联网工具指南。

    oneOf

    string

    instructions stringnullable

    系统级指令,作为模型上下文中的第一条 system 消息。

    reasoning

    object

    nullable

    思考模式配置。

    effort string

    Possible values: none, low, high, max

    控制思考模式开关与思考强度。none 关闭思考模式;low / high / max 开启思考模式。不传时使用模型默认的思考行为(默认开启)。出于兼容考虑,minimal 映射为 low,medium / xhigh 映射为 high。

    max_output_tokens integernullable

    响应可生成的 token 数上限,包含可见的输出 token 与思维链 token。

    stream booleannullable

    Default value: false

    如果设置为 true,响应将以语义化的流式 SSE 事件返回。最后一个事件是 response.completed / response.incomplete / response.failed(没有 data: [DONE] 消息)。完整事件列表请参考 Responses API 指南。

    temperature numbernullable

    Possible values: >= 0 and <= 2

    Default value: 1

    采样温度,介于 0 和 2 之间。更高的值(如 0.8)会使输出更随机,而更低的值(如 0.2)会使其更加集中和确定。思考模式下不生效。

    top_p numbernullable

    Possible values: >= 0 and <= 1

    用于调节输出的随机性,可替代 temperature。实际生效值取决于模型和模式:

    • deepseek-flash:思考模式下默认值为 1.0,低于 0.95 的取值会按 0.95 处理;非思考模式下恒为 1.0,传入的值会被忽略。
    • deepseek-v4-pro:思考模式下,启用工具调用时恒为 0.95,否则恒为 1.0,传入的值会被忽略。即使提供了 tools,将 tool_choice 设为 none 也会关闭工具调用。非思考模式下使用传入的值,默认值为 1.0。

    text

    object

    nullable

    文本输出配置。

    format

    object

    输出格式。{"type": "text"}(默认)为纯文本输出;{"type": "json_object"} 为 JSON 模式;{"type": "json_schema", "name": ..., "schema": ...} 为结构化输出,输出符合给定的 JSON Schema。

    省略 text、将 text 设为 null,或省略 format 时,使用纯文本输出。提供 format 对象时,type 必填。

    type stringrequired

    Possible values: text, json_object, json_schema

    name string

    schema 的名称。type 为 json_schema 时必填。

    schema object

    输出必须符合的 JSON Schema。type 为 json_schema 时必填。

    tools

    object[]

    nullable

    模型可能会调用的工具的列表。函数名必须非空、不超过 128 个字符、匹配 ^[a-zA-Z0-9_-]+$,且所有工具的名称必须唯一。支持 function 工具;web_search 在 deepseek-v4-pro 下支持,其余内置工具类型会被忽略。详情请参考 Responses API 指南。

    模型可能会调用的工具。function 定义一个函数工具——注意在 Responses API 格式中,name / parameters 等函数字段位于工具对象的顶层。custom 定义 custom 工具,仅支持 {"type": "custom", "name": "apply_patch"},其他名称会返回 400 错误。web_search 启用服务端网页搜索,在 deepseek-v4-pro 下支持。deepseek_web_search 与 deepseek_read_url 是联网工具,不能与 web_search 同时声明,详见 联网工具指南。

  • Array [

  • type stringrequired

    Possible values: function, custom, web_search, deepseek_web_search, deepseek_read_url

    工具类型:function、custom(仅 apply_patch)、web_search(仅 deepseek-v4-pro)、deepseek_web_search 或 deepseek_read_url。

    name string

    用于 function / custom 工具。工具的名称。对于函数工具,必须非空、不超过 128 个字符、匹配 ^[a-zA-Z0-9_-]+$,且所有工具的名称必须唯一。对于 custom 工具,必须为 apply_patch。

    description string

    用于 function 工具。函数功能的描述,供模型理解何时以及如何调用该函数。

    parameters

    object

    function 的输入参数,以 JSON Schema 对象描述。请参阅Tool Calls 指南获取示例,并参阅JSON Schema 参考了解有关格式的文档。省略 parameters 会定义一个参数列表为空的 function。

    property name* anynullable
  • ]

  • tool_choice string | object

    nullable

    控制模型调用工具的行为。

    none 意味着模型不会调用任何工具,而是生成一条消息。

    auto(默认)意味着模型可以选择生成一条消息或调用一个或多个工具。

    required 意味着模型必须调用一个或多个工具。

    通过 {"type": "function", "name": "my_function"} 指定特定工具,会强制模型调用该工具。

    oneOf

    string

    Possible values: none, auto, required

    top_logprobs integernullable

    Possible values: >= 0 and <= 20

    Default value: null

    一个介于 0 到 20 之间的整数 N,指定每个输出位置返回输出概率 top N 的 token,且返回这些 token 的对数概率。

    user stringnullable

    自定义终端用户标识。建议仅使用英文字母、数字、下划线(_)和连字符(-)。UTF-8 编码后不得超过 512 字节。请勿在其中包含用户隐私信息。

    • 可用于区分您业务侧的用户身份,以帮助我们进行内容安全审核;也可用于 KVCache 隔离与调度隔离。详情请参考限速与用户隔离

    safety_check

    object

    nullable

    DeepSeek 扩展字段。level 设为 high 时开启基础风控,审核模型的输入与输出。详见 模型内容安全指南。

    level stringrequired

    Possible values: low, high

    high:开启基础风控。low:默认检查,与不传 safety_check 相同。

    title

    object

    nullable

    DeepSeek 扩展字段。传入 {"enabled": true},响应会带上简短的会话标题。详见 会话标题指南。

    enabled booleanrequired

    是否返回会话标题。

Responses​

OK, 返回一个 response 对象。

Schema

    id stringrequired

    该响应的唯一标识符。

    object stringrequired

    Possible values: response

    object 的类型,其值恒为 response。

    created_at integerrequired

    标志响应创建时间的 Unix 时间戳(以秒为单位)。

    status stringrequired

    Possible values: in_progress, completed, incomplete, failed

    响应的状态。

    error objectnullable

    响应失败时的错误对象,包含 code 和 message 字段。

    incomplete_details

    object

    nullable

    响应不完整的原因详情。reason 字段可能为 max_output_tokens 或 content_filter。

    reason string

    Possible values: max_output_tokens, content_filter

    model stringrequired

    生成该响应的模型。

    output

    object[]

    required

    模型生成的输出 item 列表。思考模式下,思维链以 reasoning item 的形式在 message item 之前返回。函数调用以 function_call item 返回。

    模型生成的输出 item。message item 承载模型回复文本,reasoning item 承载思维链,function_call item 表示函数调用,custom_tool_call item 表示 custom 工具调用(如 apply_patch),web_search_call item 表示服务端网页搜索(仅 deepseek-v4-pro),tool_search_call item 表示工具搜索。使用联网工具时,每次工具调用都是一个 web_search_call item,并带扩展字段 kind、page、signature 与 error。

  • Array [

  • type string

    Possible values: message, reasoning, function_call, custom_tool_call, web_search_call, tool_search_call

    输出 item 的类型:message / reasoning / function_call / custom_tool_call / web_search_call / tool_search_call。

    id string

    输出 item 的唯一 ID。

    status string

    Possible values: in_progress, completed, incomplete

    输出 item 的状态。

    role string

    Possible values: assistant

    用于 message item。其值恒为 assistant。

    content

    object[]

    用于 message item 时为 output_text 内容块列表。用于 reasoning item 时为 reasoning_text 内容块列表,以明文承载思维链内容。

  • Array [

  • type string

    Possible values: output_text, reasoning_text

    text string
  • ]

  • call_id string

    用于 function_call / custom_tool_call / tool_search_call item。将工具结果回传给 API 时使用的标识符。

    name string

    用于 function_call / custom_tool_call item。要调用的函数或 custom 工具的名称。

    arguments string

    用于 function_call item。模型生成的调用函数的入参,格式为 JSON。请注意,模型并不总是生成有效的 JSON,且可能会虚构出您的函数模式中未定义的参数。在调用函数之前,请在您的代码中验证这些入参是否有效。

    kind 联网工具能力 (string)

    Possible values: search, deep_search, read_link, image_search, deep_image_search

    DeepSeek 扩展字段,出现在联网工具产生的块上:search 表示联网搜索,deep_search 表示深度思考搜索,read_link 表示阅读用户消息中的链接,image_search 与 deep_image_search(深度思考搜索中)表示图片搜索。回传时请原样保留。

    action object

    用于 web_search_call item。type 为 search(带 queries 与 sources)、open_page(带 url)或 find_in_page(带 url 与 pattern)。使用联网工具时,sources 的每个元素还带有用于展示的 title、snippet、site_name、site_icon 与 published_at。

    page object

    DeepSeek 扩展字段,用于打开或阅读了网页的 web_search_call item:url、title 与 published_at。不返回网页正文。

    signature string

    DeepSeek 扩展字段,用于成功的 read_link 调用,是加密后的网页。请原样回传,网页才会拼回上下文。

    error object

    DeepSeek 扩展字段,用于失败的 web_search_call item(status 为 failed)。code 为 unavailable、url_not_accessible 或 url_not_allowed。

  • ]

  • title string

    DeepSeek 扩展字段。会话标题,只在请求开启了 title 且生成了标题时出现。流式响应请从结束事件的 response.title 中读取。

    usage

    object

    nullable

    该响应的 token 和服务端工具用量统计信息。流式响应的初始事件中为 null,请读取最终响应的 usage。

    input_tokens integerrequired

    输入 token 数。

    input_tokens_details

    object

    输入 token 的细分信息。

    cached_tokens integer

    命中上下文缓存的输入 token 数。参考上下文硬盘缓存。

    output_tokens integerrequired

    输出 token 数。

    output_tokens_details

    object

    输出 token 的细分信息。

    reasoning_tokens integer

    模型生成的思维链 token 数。

    safety_tokens integer

    Possible values: >= 0

    DeepSeek 扩展字段。安全审核产生的 token 数,已包含在 output_tokens 中。仅在 safety_check 为 high 时返回。

    total_tokens integerrequired

    该请求使用的 token 总数(输入 + 输出)。

    server_tool_use

    object

    成功的服务端网页搜索和抓取次数,与 token 用量分别统计。仅在其中一项计数大于零时返回,否则省略整个字段。返回时各个子字段均存在。流式响应中,请从终止事件 response.completed、response.incomplete 或 response.failed 的 response.usage 读取。这些计数是累计值,不是增量。详见服务端工具用量。

    tool_search integerrequired

    Possible values: >= 0

    成功的网页搜索查询次数。一次搜索含多个查询时可能累计多次。

    tool_fetch integerrequired

    Possible values: >= 0

    通过 open_page 或 find_in_page 成功抓取网页的次数。使用联网工具时,页内查找不计入。

    tool_image_search integer

    Possible values: >= 0

    使用联网工具时返回。成功的图片搜索次数。

Loading...