跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://platform.stepfun.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

调用 Responses API,获取模型生成的响应数据。该接口兼容 OpenAI Responses API 的请求与响应格式。

请求地址

POST https://api.stepfun.com/v1/responses

请求参数

  • model string required
    需要使用的模型名称。当前仅支持 step-3.7-flash
  • input string or object array required
    输入内容,可以是纯文本字符串,也可以是按时序排列的消息/事件数组。
图片和视频 URL 必须能被服务端公网访问;如果服务端无法抓取 URL,会返回参数错误。图片输入推荐使用 base64 data URL,以避免外部 URL 鉴权、防盗链或网络访问失败。
  • instructions string optional
    顶层系统级指令。
  • stream bool optional
    是否启用 SSE 流式输出,默认 false
  • temperature float optional
    采样温度,介于 0.0 和 2.0 之间。
  • top_p float optional
    核采样参数。
  • max_output_tokens int optional
    限制本次响应的最大输出 token 数。
max_output_tokens 会同时限制推理过程和最终输出。使用 medium / high 推理强度、JSON Schema、视频等复杂输入时,建议预留更大的输出预算;预算不足时响应可能返回 status="incomplete"output 中可能只有 reasoning 项而没有最终 message
  • reasoning object optional
    推理配置。
  • tools object array optional
    工具定义列表。当前仅支持 function 类型工具。
  • tool_choice string or object optional
    工具调用策略。当前仅支持字符串 "auto"(由模型自行决定是否调用工具)。
  • text object optional
    文本输出格式配置。

响应格式

非流式响应

stream=false(默认)时,返回单个 Response 对象。

属性

  • id string
    响应唯一 ID,格式形如 resp_xxx
  • object string
    固定为 response
  • created_at int
    创建时间的 Unix 时间戳(秒)。
  • completed_at int or null
    完成时间的 Unix 时间戳(秒)。
  • status string
    响应状态,取值为 completedincompletefailed
  • error object or null
    错误信息,仅在 status=failed 时非空。
  • incomplete_details object or null
    未完成详情,仅在 status=incomplete 时非空,常见为 { "reason": "max_output_tokens" }
  • model string
    实际使用的模型 ID。
  • output object array
    输出项数组。元素可能为以下类型:
  • usage object
    token 使用统计。
  • instructions string or null
    回显请求中的顶层指令。
  • max_output_tokens int or null
    回显请求参数。
  • reasoning object or null
    回显推理配置。
  • temperature float or null
    回显采样温度。
  • top_p float or null
    回显核采样参数。
  • text object
    回显文本输出格式配置。
  • tool_choice string or object
    回显工具调用策略。
  • tools object array
    回显工具定义列表。

示例

{
  "id": "resp_xxxxxxxxxxxxxxxx",
  "object": "response",
  "created_at": 1772624997,
  "completed_at": 1772624998,
  "model": "step-3.7-flash",
  "status": "completed",
  "error": null,
  "incomplete_details": null,
  "output": [
    {
      "type": "reasoning",
      "id": "rs_xxxxxxxxxxxxxxxx",
      "summary": [],
      "content": null,
      "encrypted_content": null,
      "status": null
    },
    {
      "type": "message",
      "id": "msg_xxxxxxxxxxxxxxxx",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "量子计算是一种利用量子力学原理(如叠加和纠缠)来处理信息的新型计算范式。",
          "annotations": []
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 14,
    "input_tokens_details": { "cached_tokens": 0 },
    "output_tokens": 52,
    "output_tokens_details": { "reasoning_tokens": 0, "tool_output_tokens": 0 },
    "total_tokens": 66
  },
  "instructions": null,
  "max_output_tokens": null,
  "reasoning": { "effort": "medium", "summary": null },
  "temperature": 1.0,
  "top_p": 1.0,
  "text": { "format": { "type": "text" } },
  "tool_choice": "auto",
  "tools": []
}

流式响应

stream=true 时,返回 Server-Sent Events (SSE) 流式数据。每条事件由 event: 行和 data: 行组成。 每个事件的 data 对象都包含 typesequence_numbertypeevent 名称保持一致;sequence_number 从 0 开始递增,可用于客户端按顺序处理事件。

事件类型

事件名触发时机
response.created响应创建
response.in_progress开始生成
response.output_item.added新输出项创建
response.reasoning_part.added推理内容块开始
response.reasoning_text.delta推理文本增量
response.reasoning_text.done推理文本完成
response.reasoning_part.done推理内容块完成
response.content_part.added文本内容块开始
response.output_text.delta文本增量
response.output_text.done文本完成
response.content_part.done内容块完成
response.function_call_arguments.delta工具参数增量
response.function_call_arguments.done工具参数完成
response.output_item.done输出项完成
response.completed响应完成
response.incomplete因输出截断结束
response.failed生成失败
error传输层错误

示例

文本流式输出:
event: response.created
data: {"type":"response.created","sequence_number":0,"response":{"id":"resp_xxx","object":"response","created_at":1772624997,"model":"step-3.7-flash","status":"in_progress","output":[]}}

event: response.in_progress
data: {"type":"response.in_progress","sequence_number":1,"response":{"id":"resp_xxx","status":"in_progress"}}

event: response.output_item.added
data: {"type":"response.output_item.added","sequence_number":2,"output_index":0,"item":{"id":"rs_xxx","type":"reasoning","summary":[],"content":null,"encrypted_content":null,"status":"in_progress"}}

event: response.reasoning_part.added
data: {"type":"response.reasoning_part.added","sequence_number":3,"output_index":0,"item_id":"rs_xxx","content_index":0,"part":{"type":"reasoning_text","text":""}}

event: response.reasoning_text.delta
data: {"type":"response.reasoning_text.delta","sequence_number":4,"output_index":0,"item_id":"rs_xxx","content_index":0,"delta":"用户要求问候。"}

event: response.reasoning_text.done
data: {"type":"response.reasoning_text.done","sequence_number":5,"output_index":0,"item_id":"rs_xxx","content_index":0,"text":"用户要求问候。"}

event: response.reasoning_part.done
data: {"type":"response.reasoning_part.done","sequence_number":6,"output_index":0,"item_id":"rs_xxx","content_index":0,"part":{"type":"reasoning_text","text":"用户要求问候。"}}

event: response.output_item.done
data: {"type":"response.output_item.done","sequence_number":7,"output_index":0,"item":{"id":"rs_xxx","type":"reasoning","summary":[],"content":null,"encrypted_content":null,"status":"completed"}}

event: response.output_item.added
data: {"type":"response.output_item.added","sequence_number":8,"output_index":1,"item":{"id":"msg_xxx","type":"message","role":"assistant","status":"in_progress","content":[]}}

event: response.content_part.added
data: {"type":"response.content_part.added","sequence_number":9,"item_id":"msg_xxx","output_index":1,"content_index":0,"part":{"type":"output_text","text":"","annotations":[]}}

event: response.output_text.delta
data: {"type":"response.output_text.delta","sequence_number":10,"item_id":"msg_xxx","output_index":1,"content_index":0,"delta":"你好"}

event: response.output_text.done
data: {"type":"response.output_text.done","sequence_number":11,"item_id":"msg_xxx","output_index":1,"content_index":0,"text":"你好"}

event: response.content_part.done
data: {"type":"response.content_part.done","sequence_number":12,"item_id":"msg_xxx","output_index":1,"content_index":0,"part":{"type":"output_text","text":"你好","annotations":[]}}

event: response.output_item.done
data: {"type":"response.output_item.done","sequence_number":13,"output_index":1,"item":{"id":"msg_xxx","type":"message","role":"assistant","status":"completed","content":[{"type":"output_text","text":"你好","annotations":[]}]}}

event: response.completed
data: {"type":"response.completed","sequence_number":14,"response":{"id":"resp_xxx","object":"response","status":"completed","output":[{"id":"rs_xxx","type":"reasoning","summary":[],"content":null,"encrypted_content":null,"status":"completed"},{"id":"msg_xxx","type":"message","role":"assistant","status":"completed","content":[{"type":"output_text","text":"你好","annotations":[]}]}],"usage":{"input_tokens":10,"output_tokens":2,"total_tokens":12}}}
工具调用流式输出(节选):
event: response.output_item.added
data: {"type":"response.output_item.added","sequence_number":0,"output_index":0,"item":{"id":"fc_xxx","type":"function_call","call_id":"call_xxx","name":"get_weather","arguments":"","status":"in_progress"}}

event: response.function_call_arguments.delta
data: {"type":"response.function_call_arguments.delta","sequence_number":1,"item_id":"fc_xxx","output_index":0,"delta":"{\"city\":\"北京\"}"}

event: response.function_call_arguments.done
data: {"type":"response.function_call_arguments.done","sequence_number":2,"item_id":"fc_xxx","output_index":0,"arguments":"{\"city\":\"北京\"}","name":"get_weather"}

event: response.output_item.done
data: {"type":"response.output_item.done","sequence_number":3,"output_index":0,"item":{"id":"fc_xxx","type":"function_call","call_id":"call_xxx","name":"get_weather","arguments":"{\"city\":\"北京\"}","status":"completed"}}

event: response.completed
data: {"type":"response.completed","sequence_number":4,"response":{"id":"resp_xxx","object":"response","status":"completed","output":[{"id":"fc_xxx","type":"function_call","call_id":"call_xxx","name":"get_weather","arguments":"{\"city\":\"北京\"}","status":"completed"}]}}

示例

from openai import OpenAI

client = OpenAI(api_key="YOUR_STEP_API_KEY", base_url="https://api.stepfun.com/v1")

response = client.responses.create(
    model="step-3.7-flash",
    input="用一句话介绍量子计算",
)

print(response.output_text)