---
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` 兼容接口。