创建 Response

POST/v1/responses

使用 OpenAI Responses API 创建模型响应。该端点适用于兼容 Responses API 的模型。

认证

Authorization Bearer

在 Authorization 请求头中使用 API Key 作为 Bearer Token。

请求头

Authorizationstring

必填。Bearer API Key。

Content-Typestring

请求体类型。

Request Body

backgroundboolean

是否在后台运行响应。不支持显式 true。

context_managementobject[]

上下文管理配置。

context_management.type"compaction"

上下文管理项类型。

context_management.compact_thresholdnumber

触发压缩的 token 阈值。

conversationstring | object

Conversation ID 或 conversation 对象。不支持有状态 conversations。

conversation.idstring

Conversation ID。

includestring[]

请求响应中包含额外输出数据。取值必须与请求的模型和已启用功能匹配。

inputstring | ResponseInputItem[]

文本、图片、文件或结构化输入项。

input.typestring

输入项类型。

input.role"user" | "assistant" | "system" | "developer"

消息角色。

input.contentstring | ResponseInputContent[]

文本或内容部件。

input.idstring

引用已有输入项时的输入项 ID。

input.call_idstring

工具或函数调用 ID。

input.outputstring | object[]

函数、computer 或工具调用结果。

input.status"in_progress" | "completed" | "incomplete"

输入项状态（如有）。

instructionsstring

系统级指令。

max_output_tokensnumber

生成 token 上限，包括可见输出 token 和 reasoning token。

max_tool_callsnumber

单次响应中内置工具调用总数上限。适用于启用工具的请求。

metadataobject

附加到响应上的最多 16 个键值对。

modelstring

必填。来自 /v1/models 的模型 ID。

moderationobject

Moderation 配置，取决于模型支持。

moderation.modelstring

要使用的 moderation 模型。

parallel_tool_callsboolean

是否允许并行工具调用，取决于模型支持。

previous_response_idstring

用于多轮状态的 previous response ID。不支持该字段。

promptobject

可复用 prompt 模板引用。需要已有 prompt 模板 ID。

prompt.idstring

Prompt 模板 ID。

prompt.variablesobject

模板变量值。

prompt.versionstring

Prompt 模板版本。

prompt_cache_keystring

用于提高缓存命中率的 cache key。

prompt_cache_retention"in_memory" | "24h"

Prompt cache 保留策略。

reasoningobject

推理配置。

reasoning.context"auto" | "current_turn" | "all_turns"

后续轮次中带回哪些 reasoning 项。

推理 effort。

reasoning.generate_summary"auto" | "concise" | "detailed"

已弃用的 reasoning summary 选项。

reasoning.summary"auto" | "concise" | "detailed"

Reasoning summary 选项。

safety_identifierstring

用于安全系统的稳定终端用户标识。

service_tier"auto" | "default" | "flex" | "scale" | "priority"

处理层级。

storeboolean

必须为 false 或省略。不支持显式 true。

streamboolean

是否通过 Server-Sent Events 流式返回响应。

stream_optionsobject

流式响应选项。适用于流式请求。

stream_options.include_obfuscationboolean

是否包含 stream obfuscation 字段。

temperaturenumber

采样温度，范围 0 到 2。

textobject

文本响应配置。

text.formatobject

响应格式配置。

text.verbosity"low" | "medium" | "high"

响应详细程度。

tool_choice"none" | "auto" | "required" | object

模型应如何选择工具。可用工具选择取决于已提供工具和模型能力。

tool_choice.typestring

工具选择对象类型。

tool_choice.mode"auto" | "required"

Allowed tools 模式。

tool_choice.toolsobject[]

允许的工具定义。

tool_choice.namestring

强制指定工具时的工具名。

tool_choice.server_labelstring

MCP server label。

toolsobject[]

模型生成响应时可以调用的工具。工具类型和嵌套字段取决于模型和账号能力。

tools.typestring

工具类型。

tools.namestring

工具或函数名。

tools.descriptionstring

工具描述。

tools.parametersobject

函数参数 JSON Schema。

tools.input_schemaobject

自定义工具输入 schema。

tools.vector_store_idsstring[]

File search 使用的 vector store ID。

tools.filtersobject

File search 过滤条件。

tools.max_num_resultsnumber

最大 file search 结果数。

tools.search_context_size"low" | "medium" | "high"

Web search 上下文大小。

tools.user_locationobject

Web search 使用的大致用户位置。

tools.server_labelstring

MCP server label。

tools.server_urlstring

MCP server URL。

tools.allowed_toolsobject | string[]

允许的 MCP 工具。

tools.require_approvalstring | object

MCP 工具审批策略。

tools.containerobject | string

Code 工具的 container 配置。

tools.partial_imagesnumber

Image generation 流式模式中的 partial image 数量。

top_logprobsnumber

每个 token 位置返回的高概率 token 数量，范围 0 到 20。

top_pnumber

核采样值。

truncation"auto" | "disabled"

输入截断策略。

userstring

已弃用的稳定终端用户标识。建议使用 safety_identifier 和 prompt_cache_key。

参数兼容性

部分字段会受所选模型、已启用功能以及请求是否依赖已存储响应状态影响：

background: true、conversation、previous_response_id 和 store: true 属于有状态操作，会返回 501 unsupported_feature。
prompt 需要已有 prompt 模板 ID。
图片和文件输入部件需要模型支持，并提供有效的 file_id、URL 或数据。
工具字段取决于工具类型。
include 取值和 top_logprobs 必须与请求的输出功能匹配。
stream_options 适用于流式请求。

Response

idstring

响应 ID。

created_atnumber

Unix 秒级时间戳。

errorobject|null

响应生成失败时的错误对象。

error.codestring

错误代码。

error.messagestring

错误消息。

incomplete_detailsobject|null

Incomplete 响应的详细信息。

incomplete_details.reason"max_output_tokens" | "content_filter"

Incomplete 原因。

instructionsstring | object[] | null

该响应使用的指令。

max_output_tokensnumber|null

最大输出 token 设置。

modelstring

模型标识符。

object"response"

对象类型。

outputobject[]

输出项。

output.idstring

输出项 ID。

output.typestring

输出项类型。

output.status"in_progress" | "completed" | "incomplete"

输出项状态。

output.rolestring

消息输出项的角色。

output.contentobject[]

内容部件。

output.call_idstring

工具或函数调用 ID。

output.namestring

工具或函数名。

output.argumentsstring

函数调用参数。

output.outputstring | object[]

函数或工具输出。

output.summaryobject[]

Reasoning summary 项。

output.encrypted_contentstring

请求 include 时返回的加密 reasoning 内容。

output_textstring

可用时的拼接文本输出。

parallel_tool_callsboolean

是否允许并行工具调用。

previous_response_idstring|null

Previous response ID。

promptobject|null

Prompt 模板引用。

prompt.idstring

Prompt 模板 ID。

prompt.variablesobject

Prompt 变量。

prompt.versionstring

Prompt 版本。

prompt_cache_keystring

Prompt cache key。

prompt_cache_retention"in_memory" | "24h"

Prompt cache 保留策略。

reasoningobject|null

实际使用的 reasoning 配置。

reasoning.context"auto" | "current_turn" | "all_turns"

Reasoning context 模式。

Reasoning effort。

reasoning.summary"auto" | "concise" | "detailed" | null

Reasoning summary 模式。

safety_identifierstring

稳定终端用户标识。

service_tier"auto" | "default" | "flex" | "scale" | "priority"

实际使用的服务层级。

响应状态。

storeboolean

响应是否被存储。

temperaturenumber

采样温度。

textobject

文本响应配置。

text.formatobject

text.verbosity"low" | "medium" | "high"

Verbosity 设置。

tool_choicestring | object

实际使用的工具选择。

toolsobject[]

实际使用的工具定义。

top_logprobsnumber

Top logprobs 设置。

top_pnumber

核采样设置。

truncation"auto" | "disabled"

截断策略。

usageobject

Token 用量。

usage.input_tokensnumber

输入 token 数。

usage.input_tokens_detailsobject

usage.output_tokensnumber

输出 token 数。

usage.output_tokens_detailsobject

usage.total_tokensnumber

总 token 数。

userstring

已弃用终端用户标识。

metadataobject

附加到响应上的 metadata。

不支持的有状态操作

需要已存储响应状态的请求会返回 501 unsupported_feature，包括：

previous_response_id
conversation
background: true
store: true
/v1/responses/{response_id}
/v1/responses/{response_id}/input_items
/v1/responses/{response_id}/cancel

请求

1curl -X POST https://api.token360.ai/v1/responses \
2  -H "Authorization: Bearer sk-your-api-key" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "model": "gpt-5.5",
6    "input": "Reply with the exact text: Paris.",
7    "max_output_tokens": 32,
8    "reasoning": { "effort": "low" }
9  }'

响应

JSON

1{
2  "id": "resp_...",
3  "object": "response",
4  "created_at": 1783584000,
5  "model": "gpt-5.5-2026-04-23",
6  "status": "completed",
7  "output": [
8    {
9      "type": "message",
10      "role": "assistant",
11      "content": [
12        {
13          "type": "output_text",
14          "text": "Paris."
15        }
16      ]
17    }
18  ],
19  "usage": {
20    "input_tokens": 18,
21    "output_tokens": 4,
22    "total_tokens": 22
23  }
24}

此页面对您有帮助吗？