Token Switch 文档中心

中文

English

中文

English

Appearance

OpenAI Responses API ​

使用 Responses API 创建模型响应。支持文本、图片、文件输入，生成文本或 JSON 输出，可调用自定义函数或内置工具（网络搜索、文件搜索等）。适用于多模态对话、函数调用、推理模型等场景。

接口地址 ​

http
POST /v1/responses

认证 ​

方式说明
Bearer Token在请求头中携带 Authorization: Bearer <API_key> 用于验证账户信息。

请求头 ​

参数名类型必填说明
Content-Typestring是请求体的媒介类型，请设置为 application/json
Authorizationstring是Bearer API_key，用于验证账户信息

请求体 ​

基础参数 ​

参数名类型必填默认值说明
modelstring是-模型 ID，如 gpt-4o、o3 等
inputstring 或 array否-输入内容，可为纯文本字符串或消息数组。支持文本、图片、文件等多种输入类型
instructionsstring否-插入模型上下文的系统/开发者消息。与 previous_response_id 同时使用时，上一轮的 instructions 不会延续
storeboolean否true是否存储响应以供后续通过 API 检索
streamboolean否false是否启用 SSE 流式输出
temperaturenumber否1采样温度，取值范围 0~2。值越高输出越随机，值越低越确定。建议与 top_p 二选一调整
top_pnumber否1核采样阈值，取值范围 0~1.0。如 0.1 表示只考虑概率最高的 10% 的 token
top_logprobsnumber否-每个 token 位置返回最可能的 token 数量，取值范围 0~20
truncationstring否disabled截断策略。auto：超长输入自动截断；disabled：超长输入返回 400 错误
metadataobject否-键值对元数据，最多 16 对，键最长 64 字符，值最长 512 字符
userstring否-用户标识符。已废弃，建议使用 safety_identifier 和 prompt_cache_key
safety_identifierstring否-安全标识符，用于检测滥用。最长 64 字符，建议哈希处理
service_tierstring否auto服务层级。可选 auto/default/flex/scale/priority/fast/ultrafast
backgroundboolean否false是否在后台运行模型响应
max_output_tokensnumber否-响应最大 token 数（含推理 token）
parallel_tool_callsboolean否true是否允许模型并行调用工具
previous_response_idstring否-上一轮响应 ID，用于多轮对话。不能与 conversation 同时使用
conversationstring 或 object否-会话归属。传入会话 ID 或 { id } 对象，会话中的条目会自动拼接到 input 前
max_tool_callsnumber否-内置工具最大调用次数（所有工具合计）
includearray否-额外输出包含项，如 file_search_call.results、web_search_call.action.sources、message.output_text.logprobs 等

推理参数 ​

参数名类型必填默认值说明
reasoningobject否-推理配置（仅 gpt-5 和 o 系列模型支持）

reasoning 详细参数 ​

参数名类型必填默认值说明
effortstring否-推理力度。可选 none/minimal/low/medium/high/xhigh/max。值越高推理越充分但更慢更贵
summarystring否-推理摘要。可选 auto/concise/detailed
contextstring否auto推理上下文模式。auto：模型决定；current_turn：仅当前轮；all_turns：所有轮
modestring否-推理执行模式。可选 standard/pro
generate_summarystring否-已废弃，请使用 summary

文本格式参数 ​

参数名类型必填默认值说明
textobject否-文本响应格式配置

text 详细参数 ​

参数名类型必填默认值说明
formatobject否{"type":"text"}输出格式。text：纯文本；json_schema：结构化 JSON（推荐）；json_object：旧版 JSON 模式
verbositystring否medium响应详细程度。可选 low/medium/high

text.format（json_schema 模式） ​

参数名类型必填默认值说明
typestring是-固定为 json_schema
namestring是-格式名称，仅 a-z/A-Z/0-9/下划线/连字符，最长 64 字符
schemaobject是-JSON Schema 对象，描述响应结构
descriptionstring否-格式用途描述
strictboolean否-是否严格遵循 schema

工具参数 ​

参数名类型必填默认值说明
toolsarray否-工具列表。支持 Function、FileSearch、WebSearch、Computer、CodeInterpreter、ImageGeneration、MCP、Custom 等
tool_choicestring 或 object否auto工具选择策略。none：不调用；auto：模型决定；required：必须调用；也可指定特定工具

tools 支持的类型 ​

类型type 值说明
自定义函数function定义 name、parameters（JSON Schema）、description、strict
文件搜索file_search需指定 vector_store_ids，可选 max_num_results、filters、ranking_options
网络搜索web_search / web_search_preview可选 search_context_size（low/medium/high）、user_location、filters.allowed_domains
计算机控制computer / computer_use_preview控制虚拟计算机，需指定 display_width、display_height、environment
代码解释器code_interpreter运行 Python 代码，可指定 container（容器 ID 或自动配置）
图片生成image_generation使用 GPT 图片模型生成/编辑图片，可选 quality、size、output_format 等
MCP 工具mcp连接远程 MCP 服务器，需指定 server_label、server_url/connector_id/tunnel_id
自定义工具custom自定义格式工具，定义 name、description、format
命名空间namespace将 function/custom 工具分组到共享命名空间下
工具搜索tool_search延迟工具发现配置
本地 Shelllocal_shell / shell允许模型执行 Shell 命令
文件补丁apply_patch使用 unified diff 创建/删除/更新文件

缓存参数 ​

参数名类型必填默认值说明
prompt_cache_keystring否-缓存键，替代 user 字段用于优化缓存命中率
prompt_cache_optionsobject否-缓存选项（gpt-5.6+ 支持）
prompt_cache_retentionstring否-已废弃，请使用 prompt_cache_options.ttl。可选 in_memory/24h

prompt_cache_options 详细参数 ​

参数名类型必填默认值说明
modestring否implicit缓存模式。implicit：自动创建隐式断点；explicit：仅使用显式断点
ttlstring否30m缓存最小生存时间，目前仅支持 30m

审核参数 ​

参数名类型必填默认值说明
moderationobject否-内容审核配置

moderation 详细参数 ​

参数名类型必填默认值说明
modelstring否-审核模型，如 omni-moderation-latest
policyobject否-审核策略
policy.input.modestring否-输入审核模式：score/block
policy.output.modestring否-输出审核模式：score/block

上下文管理参数 ​

参数名类型必填默认值说明
context_managementarray否-上下文管理配置

context_management 详细参数 ​

参数名类型必填默认值说明
typestring是-上下文管理类型，目前仅支持 compaction
compact_thresholdnumber否-触发压缩的 token 阈值

提示模板参数 ​

参数名类型必填默认值说明
promptobject否-提示模板引用

prompt 详细参数 ​

参数名类型必填默认值说明
idstring是-提示模板唯一标识
variablesobject否-模板变量映射，值为字符串或输入内容类型
versionstring否-模板版本

流式参数 ​

参数名类型必填默认值说明
stream_optionsobject否-流式响应选项，仅在 stream: true 时生效

stream_options 详细参数 ​

参数名类型必填默认值说明
include_obfuscationboolean否true是否启用流混淆（添加随机字符归一化负载大小，防御侧信道攻击）

input 输入类型 ​

input 可为纯文本字符串，或消息数组。消息对象支持以下 content 类型：

内容类型type 值说明
文本input_text文本输入，字段：text
图片input_image图片输入，字段：image_url（URL 或 base64）、file_id、detail（low/high/auto/original）
文件input_file文件输入，字段：file_url、file_id、file_data、filename、detail（auto/low/high）

消息 role 可选：user、assistant、system、developer。

响应体 ​

参数名类型说明
idstring响应唯一标识
objectstring资源类型，固定为 response
created_atnumber创建时间（Unix 秒级时间戳）
completed_atnumber 或 null完成时间（Unix 秒级时间戳），仅 status 为 completed 时存在
statusstring响应状态：completed/failed/in_progress/cancelled/queued/incomplete
errorobject 或 null错误信息，含 code（错误码）和 message（描述）
incomplete_detailsobject 或 null不完整原因，reason：max_output_tokens/content_filter
instructionsstring 或 null插入的系统/开发者消息
modelstring使用的模型 ID
outputarray模型生成的内容数组，包含消息、工具调用等
output_textstring 或 nullSDK 便捷属性，聚合所有 output_text 项的文本（仅 Python/JS SDK）
parallel_tool_callsboolean是否允许并行工具调用
previous_response_idstring 或 null上一轮响应 ID
reasoningobject 或 null推理配置（effort/summary/context/mode）
service_tierstring 或 null实际使用的服务层级
temperaturenumber 或 null采样温度
textobject 或 null文本格式配置（format/verbosity）
tool_choicestring 或 object工具选择策略
toolsarray工具列表
top_pnumber 或 null核采样阈值
top_logprobsnumber 或 null对数概率返回数
truncationstring 或 null截断策略
usageobject 或 nulltoken 用量统计
backgroundboolean 或 null是否后台运行
conversationobject 或 null会话信息，含 id
max_output_tokensnumber 或 null最大输出 token 数
max_tool_callsnumber 或 null最大工具调用次数
moderationobject 或 null审核结果（input/output）
promptobject 或 null提示模板引用
prompt_cache_keystring 或 null缓存键
prompt_cache_optionsobject 或 null缓存选项（mode/ttl）
prompt_cache_retentionstring 或 null缓存保留策略
safety_identifierstring 或 null安全标识符
storeboolean 或 null是否存储响应
metadataobject 或 null元数据
userstring 或 null用户标识

output 数组项类型 ​

类型type 值说明
消息message模型输出消息，含 content（output_text/refusal）、role（assistant）、status、phase
函数调用function_call函数工具调用，含 arguments、call_id、name、status
函数调用输出function_call_output函数执行结果，含 output、call_id
文件搜索调用file_search_call文件搜索结果，含 queries、results、status
网络搜索调用web_search_call网络搜索结果，含 status、action
推理reasoning推理过程，含 summary、encrypted_content
代码解释器调用code_interpreter_call代码执行结果
计算机调用computer_call计算机操作调用

usage 对象 ​

参数名类型说明
input_tokensnumber输入 token 数
output_tokensnumber输出 token 数
total_tokensnumber总 token 数
input_tokens_details.cached_tokensnumber缓存命中的 token 数
input_tokens_details.cache_write_tokensnumber写入缓存的 token 数
output_tokens_details.reasoning_tokensnumber推理 token 数

基础文本对话 ​

bash
curl --location --request POST 'https://neolink.com/api/v1/responses' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <API Key>' \
     --data-raw '{
         "model": "<Model ID>",
         "input": "讲一个关于独角兽的三句话睡前故事"
     }'
python
import requests

url = "https://neolink.com/api/v1/responses"

headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <API Key>",
}

payload = {
    "model": "<Model ID>",
    "input": "讲一个关于独角兽的三句话睡前故事"
}

response = requests.post(url, headers=headers, json=payload, timeout=30)
response.raise_for_status()
result = response.json()
print(result)

多模态请求（图片输入） ​

bash
curl --location --request POST 'https://neolink.com/api/v1/responses' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <API Key>' \
     --data-raw '{
         "model": "<Model ID>",
         "input": [
             {
                 "role": "user",
                 "content": [
                     {"type": "input_text", "text": "描述这张图片"},
                     {"type": "input_image", "image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"}
                 ]
             }
         ]
     }'
python
import requests

url = "https://neolink.com/api/v1/responses"

headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <API Key>",
}

payload = {
    "model": "<Model ID>",
    "input": [
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "描述这张图片"},
                {"type": "input_image", "image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"}
            ]
        }
    ]
}

response = requests.post(url, headers=headers, json=payload, timeout=30)
response.raise_for_status()
result = response.json()
print(result)

文件输入 ​

bash
curl --location --request POST 'https://neolink.com/api/v1/responses' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <API Key>' \
     --data-raw '{
         "model": "<Model ID>",
         "input": [
             {
                 "role": "user",
                 "content": [
                     {"type": "input_text", "text": "这个文件里有什么内容？"},
                     {"type": "input_file", "file_url": "https://example.com/document.pdf", "detail": "auto"}
                 ]
             }
         ]
     }'
python
import requests

url = "https://neolink.com/api/v1/responses"

headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <API Key>",
}

payload = {
    "model": "<Model ID>",
    "input": [
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "这个文件里有什么内容？"},
                {"type": "input_file", "file_url": "https://example.com/document.pdf", "detail": "auto"}
            ]
        }
    ]
}

response = requests.post(url, headers=headers, json=payload, timeout=30)
response.raise_for_status()
result = response.json()
print(result)

函数调用 ​

bash
curl --location --request POST 'https://neolink.com/api/v1/responses' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <API Key>' \
     --data-raw '{
         "model": "<Model ID>",
         "input": "今天波士顿天气怎么样？",
         "tools": [
             {
                 "type": "function",
                 "name": "get_current_weather",
                 "description": "获取指定城市的当前天气",
                 "parameters": {
                     "type": "object",
                     "properties": {
                         "location": {"type": "string", "description": "城市名，如 Boston, MA"},
                         "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
                     },
                     "required": ["location", "unit"]
                 }
             }
         ],
         "tool_choice": "auto"
     }'
python
import requests

url = "https://neolink.com/api/v1/responses"

headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <API Key>",
}

payload = {
    "model": "<Model ID>",
    "input": "今天波士顿天气怎么样？",
    "tools": [
        {
            "type": "function",
            "name": "get_current_weather",
            "description": "获取指定城市的当前天气",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {"type": "string", "description": "城市名，如 Boston, MA"},
                    "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
                },
                "required": ["location", "unit"]
            }
        }
    ],
    "tool_choice": "auto"
}

response = requests.post(url, headers=headers, json=payload, timeout=30)
response.raise_for_status()
result = response.json()
print(result)

网络搜索 ​

bash
curl --location --request POST 'https://neolink.com/api/v1/responses' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <API Key>' \
     --data-raw '{
         "model": "<Model ID>",
         "input": "今天有什么积极的新闻？",
         "tools": [{"type": "web_search_preview"}]
     }'
python
import requests

url = "https://neolink.com/api/v1/responses"

headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <API Key>",
}

payload = {
    "model": "<Model ID>",
    "input": "今天有什么积极的新闻？",
    "tools": [{"type": "web_search_preview"}]
}

response = requests.post(url, headers=headers, json=payload, timeout=30)
response.raise_for_status()
result = response.json()
print(result)

文件搜索 ​

bash
curl --location --request POST 'https://neolink.com/api/v1/responses' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <API Key>' \
     --data-raw '{
         "model": "<Model ID>",
         "input": "古代棕龙有什么属性？",
         "tools": [
             {
                 "type": "file_search",
                 "vector_store_ids": ["vs_1234567890"],
                 "max_num_results": 20
             }
         ]
     }'
python
import requests

url = "https://neolink.com/api/v1/responses"

headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <API Key>",
}

payload = {
    "model": "<Model ID>",
    "input": "古代棕龙有什么属性？",
    "tools": [
        {
            "type": "file_search",
            "vector_store_ids": ["vs_1234567890"],
            "max_num_results": 20
        }
    ]
}

response = requests.post(url, headers=headers, json=payload, timeout=30)
response.raise_for_status()
result = response.json()
print(result)

推理模型 ​

bash
curl --location --request POST 'https://neolink.com/api/v1/responses' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <API Key>' \
     --data-raw '{
         "model": "<Model ID>",
         "input": "一只土拨鼠能扔多少木头？",
         "reasoning": {
             "effort": "high"
         }
     }'
python
import requests

url = "https://neolink.com/api/v1/responses"

headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <API Key>",
}

payload = {
    "model": "<Model ID>",
    "input": "一只土拨鼠能扔多少木头？",
    "reasoning": {
        "effort": "high"
    }
}

response = requests.post(url, headers=headers, json=payload, timeout=30)
response.raise_for_status()
result = response.json()
print(result)

流式输出 ​

bash
curl --location --request POST 'https://neolink.com/api/v1/responses' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <API Key>' \
     --data-raw '{
         "model": "<Model ID>",
         "instructions": "你是一个有用的助手。",
         "input": "你好！",
         "stream": true
     }'
python
import requests

url = "https://neolink.com/api/v1/responses"

headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <API Key>",
}

payload = {
    "model": "<Model ID>",
    "instructions": "你是一个有用的助手。",
    "input": "你好！",
    "stream": True
}

response = requests.post(url, headers=headers, json=payload, timeout=30, stream=True)
for line in response.iter_lines():
    if line:
        print(line.decode("utf-8"))

流式响应使用 SSE 格式，主要事件类型：

事件说明
response.created响应创建
response.in_progress响应进行中
response.output_item.added输出项添加
response.content_part.added内容部分添加
response.output_text.delta文本增量
response.output_text.done文本输出完成
response.content_part.done内容部分完成
response.output_item.done输出项完成
response.completed响应完成

结构化输出（JSON Schema） ​

bash
curl --location --request POST 'https://neolink.com/api/v1/responses' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <API Key>' \
     --data-raw '{
         "model": "<Model ID>",
         "input": "列出三种水果及其颜色",
         "text": {
             "format": {
                 "type": "json_schema",
                 "name": "fruit_list",
                 "schema": {
                     "type": "object",
                     "properties": {
                         "fruits": {
                             "type": "array",
                             "items": {
                                 "type": "object",
                                 "properties": {
                                     "name": {"type": "string"},
                                     "color": {"type": "string"}
                                 },
                                 "required": ["name", "color"]
                             }
                         }
                     },
                     "required": ["fruits"]
                 },
                 "strict": true
             }
         }
     }'
python
import requests

url = "https://neolink.com/api/v1/responses"

headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <API Key>",
}

payload = {
    "model": "<Model ID>",
    "input": "列出三种水果及其颜色",
    "text": {
        "format": {
            "type": "json_schema",
            "name": "fruit_list",
            "schema": {
                "type": "object",
                "properties": {
                    "fruits": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "name": {"type": "string"},
                                "color": {"type": "string"}
                            },
                            "required": ["name", "color"]
                        }
                    }
                },
                "required": ["fruits"]
            },
            "strict": True
        }
    }
}

response = requests.post(url, headers=headers, json=payload, timeout=30)
response.raise_for_status()
result = response.json()
print(result)

多轮对话 ​

使用 previous_response_id 实现多轮对话：

bash
curl --location --request POST 'https://neolink.com/api/v1/responses' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <API Key>' \
     --data-raw '{
         "model": "<Model ID>",
         "previous_response_id": "resp_abc123",
         "input": "请用中文重新回答上一个问题"
     }'
python
import requests

url = "https://neolink.com/api/v1/responses"

headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <API Key>",
}

payload = {
    "model": "<Model ID>",
    "previous_response_id": "resp_abc123",
    "input": "请用中文重新回答上一个问题"
}

response = requests.post(url, headers=headers, json=payload, timeout=30)
response.raise_for_status()
result = response.json()
print(result)

响应示例 ​

json
{
  "id": "resp_67ccd2bed1ec8190b14f964abc0542670bb6a6b452d3795b",
  "object": "response",
  "created_at": 1741476542,
  "status": "completed",
  "completed_at": 1741476543,
  "error": null,
  "incomplete_details": null,
  "instructions": null,
  "max_output_tokens": null,
  "model": "gpt-5.4",
  "output": [
    {
      "type": "message",
      "id": "msg_67ccd2bf17f0819081ff3bb2cf6508e60bb6a6b452d3795b",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "在银月下的宁静树林中，一只名叫流光的独角兽发现了一个隐藏的水池...",
          "annotations": []
        }
      ]
    }
  ],
  "parallel_tool_calls": true,
  "previous_response_id": null,
  "reasoning": {
    "effort": null,
    "summary": null
  },
  "store": true,
  "temperature": 1.0,
  "text": {
    "format": {"type": "text"}
  },
  "tool_choice": "auto",
  "tools": [],
  "top_p": 1.0,
  "truncation": "disabled",
  "usage": {
    "input_tokens": 36,
    "input_tokens_details": {
      "cached_tokens": 0,
      "cache_write_tokens": 0
    },
    "output_tokens": 87,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 123
  },
  "metadata": {}
}

流式响应示例 ​

json
event: response.created
data: {"type":"response.created","response":{"id":"resp_abc","object":"response","created_at":1741290958,"status":"in_progress","model":"gpt-5.4","output":[]}}

event: response.output_item.added
data: {"type":"response.output_item.added","output_index":0,"item":{"id":"msg_abc","type":"message","status":"in_progress","role":"assistant","content":[]}}

event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_abc","output_index":0,"content_index":0,"delta":"你好"}

event: response.output_text.done
data: {"type":"response.output_text.done","item_id":"msg_abc","output_index":0,"content_index":0,"text":"你好！有什么可以帮你的吗？"}

event: response.completed
data: {"type":"response.completed","response":{"id":"resp_abc","object":"response","status":"completed","output":[{"id":"msg_abc","type":"message","status":"completed","role":"assistant","content":[{"type":"output_text","text":"你好！有什么可以帮你的吗？","annotations":[]}]}],"usage":{"input_tokens":37,"output_tokens":11,"total_tokens":48}}}

支持模型Id：