72 lines
2.6 KiB
Markdown
72 lines
2.6 KiB
Markdown
# OpenAI Responses API
|
||
|
||
Responses API 是 OpenAI 当前统一的文本与工具调用接口，输入使用 `input`，可同时承载简单字符串、结构化消息和工具回合。宿主默认发送字符串提示词，并从同步响应的 `output_text` 或 `output[]` 中提取文本。
|
||
|
||
## 接口、鉴权与请求模式
|
||
|
||
{{OPERATIONS}}
|
||
|
||
```http
|
||
POST {channel_base_url}/v1/responses
|
||
Authorization: Bearer <API_KEY>
|
||
Content-Type: application/json
|
||
```
|
||
|
||
## 模型与能力发现
|
||
|
||
插件不硬编码模型表。请使用渠道模型管理中已验证支持 Responses API 的模型 ID。兼容服务即使实现 `/v1/responses`，也可能不支持内置工具、状态延续、结构化输出或多模态输入，能力必须以该服务文档和实际探测为准。
|
||
|
||
## 参数与字段映射
|
||
|
||
{{PARAMETERS}}
|
||
|
||
`extra` 可透传 `input`、`instructions`、`temperature`、`top_p`、`max_output_tokens`、`stream`、`tools` 和 `text`。`extra.input` 会替换默认字符串；复杂输入必须使用上游规定的 item 结构，不应把 Chat Completions 的 `messages` 原样塞进来。
|
||
|
||
## 请求示例
|
||
|
||
```bash
|
||
curl "{channel_base_url}/v1/responses" \
|
||
-H "Authorization: Bearer <API_KEY>" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"model": "YOUR_MODEL",
|
||
"instructions": "输出可直接拍摄的镜头清单。",
|
||
"input": "一名女孩在停电的商场里寻找出口。",
|
||
"max_output_tokens": 1200
|
||
}'
|
||
```
|
||
|
||
```json
|
||
{
|
||
"id": "resp_xxx",
|
||
"status": "completed",
|
||
"output_text": "镜头 1……",
|
||
"usage": {"input_tokens":28,"output_tokens":174,"total_tokens":202}
|
||
}
|
||
```
|
||
|
||
## 结构化输入示例
|
||
|
||
```json
|
||
{
|
||
"model": "YOUR_MODEL",
|
||
"input": [{
|
||
"role": "user",
|
||
"content": [{"type":"input_text","text":"分析这段剧情的节奏问题"}]
|
||
}]
|
||
}
|
||
```
|
||
|
||
## 响应解析与限制
|
||
|
||
解析器优先读取顶层 `output_text`；缺失时遍历 `output`，尝试读取 item 的 `text` 或 `content`，并保留 `usage`。当前实现没有完整执行 function call、computer use、file search 等输出 item，也不通过 `previous_response_id` 自动续接状态。需要这些能力时必须在 Agent 调用链中显式实现，不能只靠文档声称支持。
|
||
|
||
流式响应由文本事件链路处理。上游拒绝、模型不支持、输入结构错误、输出 token 超限和工具参数校验失败均应作为失败返回。
|
||
|
||
## 官方资料
|
||
|
||
- [OpenAI Responses API Reference](https://developers.openai.com/api/reference/resources/responses/methods/create)
|
||
- [OpenAI Responses migration guide](https://developers.openai.com/api/docs/guides/migrate-to-responses)
|
||
|
||
{{CONTRACT}}
|