136 lines
3.5 KiB
Plaintext
136 lines
3.5 KiB
Plaintext
---
|
||
title: Stateful Responses 文本接口
|
||
description: 使用 OpenAI Responses 风格的 HTTP 与 SSE 接口调用平台助手。
|
||
---
|
||
|
||
# Stateful Responses 文本接口
|
||
|
||
`POST /v1/responses` 为 Pipeline 助手提供文本调用。服务端保存每轮输入和输出，后续请求通过 `previous_response_id` 恢复上下文。语音、视频和长连接交互继续使用 `/v1/realtime`。
|
||
|
||
接口使用后台创建的长期 `sk-rt-...` API Key。短期 `ek-rt-...` Client Secret 不能调用文本接口。
|
||
|
||
## 首轮请求
|
||
|
||
```bash
|
||
curl -X POST "https://api.example.com/v1/responses" \
|
||
-H "Authorization: Bearer $REALTIME_API_KEY" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"model": "assistant:asst_xxx",
|
||
"input": "请介绍一下这个产品"
|
||
}'
|
||
```
|
||
|
||
响应中的 `id` 是下一轮使用的状态指针：
|
||
|
||
```json
|
||
{
|
||
"id": "resp_xxx",
|
||
"object": "response",
|
||
"status": "completed",
|
||
"model": "assistant:asst_xxx",
|
||
"previous_response_id": null,
|
||
"output": [
|
||
{
|
||
"id": "msg_xxx",
|
||
"type": "message",
|
||
"status": "completed",
|
||
"role": "assistant",
|
||
"content": [
|
||
{"type": "output_text", "text": "……", "annotations": []}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
## 继续多轮对话
|
||
|
||
后续请求可以省略 `model`。服务端从父响应恢复助手、动态变量、消息和工具上下文：
|
||
|
||
```bash
|
||
curl -X POST "https://api.example.com/v1/responses" \
|
||
-H "Authorization: Bearer $REALTIME_API_KEY" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"previous_response_id": "resp_xxx",
|
||
"input": "它适合哪些行业？"
|
||
}'
|
||
```
|
||
|
||
同一个父响应可以创建多个独立分支。Response 只能由创建它的 API Key 查询或继续：
|
||
|
||
```bash
|
||
curl "https://api.example.com/v1/responses/resp_xxx" \
|
||
-H "Authorization: Bearer $REALTIME_API_KEY"
|
||
```
|
||
|
||
## SSE 流式输出
|
||
|
||
设置 `stream: true` 后返回 `text/event-stream`：
|
||
|
||
```json
|
||
{
|
||
"model": "assistant:asst_xxx",
|
||
"input": "给我一个简短介绍",
|
||
"stream": true
|
||
}
|
||
```
|
||
|
||
主要事件依次为 `response.created`、`response.in_progress`、`response.output_text.delta`、`response.output_text.done` 和 `response.completed`。连接中断会取消运行，并把 Response 标记为 `cancelled`。
|
||
|
||
## 动态变量
|
||
|
||
首轮可以传入项目扩展字段，后续请求会继承并可增量覆盖：
|
||
|
||
```json
|
||
{
|
||
"model": "assistant:asst_xxx",
|
||
"input": "查询我的权益",
|
||
"x_interactive_media": {
|
||
"variables": {
|
||
"customer_name": "王女士",
|
||
"membership_level": "gold"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## Client Tool 续传
|
||
|
||
当助手需要调用客户端工具时，Response 的 `output` 会包含 `function_call`：
|
||
|
||
```json
|
||
{
|
||
"type": "function_call",
|
||
"call_id": "call_xxx",
|
||
"name": "show_message",
|
||
"arguments": "{\"message\":\"请确认\"}"
|
||
}
|
||
```
|
||
|
||
客户端执行后，通过父响应和对应的 `call_id` 继续：
|
||
|
||
```json
|
||
{
|
||
"previous_response_id": "resp_xxx",
|
||
"input": [
|
||
{
|
||
"type": "function_call_output",
|
||
"call_id": "call_xxx",
|
||
"output": "{\"status\":\"ok\",\"data\":{\"action\":\"confirmed\"}}"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
如果父链存在多个尚未完成的 Client Tool，本轮必须一次提交全部对应结果。
|
||
|
||
## 首版边界
|
||
|
||
- 仅支持 `runtimeMode=pipeline` 的 Prompt、Workflow、Dify 和 FastGPT 助手。
|
||
- 只支持文本 `message` 和 `function_call_output` 输入。
|
||
- `store` 必须为 `true` 或省略。
|
||
- 不支持 `conversation`、`background`、图片、文件以及调用方覆盖 instructions 或 tools。
|
||
- 不提供 `/v1/chat/completions` 兼容接口。
|