# Responses 接口使用说明

## 一、功能简介

Responses API 是 OpenAI 推出的新一代模型调用接口，可视为 Chat Completions API 的升级版。万界方舟 MaaS 平台对 Responses 接口做了完整兼容，相比 Chat Completions，它具有以下特点：

- **服务端会话状态**：通过 `previous_response_id` 即可实现多轮对话，无需在客户端维护完整上下文；
- **面向 Agent 的交互模型**：原生支持函数调用（Function Calling）、结构化输出（Structured Outputs）等能力；
- **更细粒度的流式事件**：以 SSE 事件流的方式返回 `response.created`、`response.output_text.delta`、`response.completed` 等结构化事件。

> 如果您的应用只需简单的单轮/多轮文本对话，也可以继续使用 [Chat Completions 接口](/maas/Interface)；构建智能体（Agent）、工具编排类应用时推荐使用 Responses 接口。

## 二、准备工作

1. 登录[万界方舟](https://www.wjark.com)，完成[实名认证](/maas/authentication)（未认证账号可调用接口，但存在购买限制）。
2. 获取 API Key：进入[万界方舟 API Key](https://www.wjark.com/center/api-key) 页面，点击一键复制；也可自行创建 API Key 并设置名称、限额与权限。
3. 获取模型 ID：进入[万界方舟模型广场](https://www.wjark.com/center/model)，选择支持 Responses 协议的授权模型并复制模型名称。

## 三、接口基础信息

- Base URL（OpenAI 兼容）：`https://maas-openapi.wanjiedata.com/api/v1`
- 鉴权方式：请求头携带 `Authorization: Bearer <你的 API KEY>`
- 请求报文：`POST` 请求参数以 `JSON` 格式填入 Body，Content-Type 为 `application/json; charset=utf-8`
- 响应报文：`JSON` 格式，Content-Type 为 `application/json; charset=utf-8`

### 接口一览

| 接口 | 请求方式 | 接口地址 | 说明 |
| --- | --- | --- | --- |
| 创建 Response | POST | `/v1/responses` | 创建模型响应，支持流式 / 非流式 |
| 查询 Response | GET | `/v1/responses/{response_id}` | 根据响应 ID 查询已创建的响应 |
| 删除 Response | DELETE | `/v1/responses/{response_id}` | 删除指定响应 |
| 取消 Response | POST | `/v1/responses/{response_id}/cancel` | 取消后台模式（`background=true`）创建的响应 |
| 查询输入项 | GET | `/v1/responses/{response_id}/input_items` | 查询创建该响应时使用的输入项列表 |

## 四、快速开始

### 4.1 非流式请求

::: code-group

```shell [shell]
export API_KEY="<你的 API KEY>"
export MODEL="<你的授权模型名称>"

curl --location --request POST 'https://maas-openapi.wanjiedata.com/api/v1/responses' \
--header "Authorization: Bearer $API_KEY" \
--header 'Content-Type: application/json' \
--data-raw '{
    "model": "'"$MODEL"'",
    "input": "你好，请用一句话介绍万界方舟"
}'
```

```python [python]
# 需要 openai SDK >= 1.66.0：pip install -U openai
from openai import OpenAI

client = OpenAI(
    api_key="<你的 API KEY>",
    base_url="https://maas-openapi.wanjiedata.com/api/v1",
)

response = client.responses.create(
    model="<你的授权模型名称>",
    input="你好，请用一句话介绍万界方舟",
)

print(response.output_text)
```

```javascript [javascript]
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "<你的 API KEY>",
  baseURL: "https://maas-openapi.wanjiedata.com/api/v1",
});

const response = await client.responses.create({
  model: "<你的授权模型名称>",
  input: "你好，请用一句话介绍万界方舟",
});

console.log(response.output_text);
```
:::

**非流式响应示例**

```json
{
  "id": "resp_5c3d2a1b",
  "object": "response",
  "created_at": 1755676800,
  "status": "completed",
  "model": "<你的授权模型名称>",
  "output": [
    {
      "id": "msg_8f2e9d",
      "type": "message",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "你好！万界方舟是模型即服务（MaaS）平台，通过一个 API 即可调用多种主流大模型。",
          "annotations": []
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 15,
    "output_tokens": 42,
    "total_tokens": 57
  }
}
```

> `output_text` 是 OpenAI SDK 提供的便捷聚合字段（汇总 `output` 数组中所有文本输出），直接通过 HTTP 调用时请以 `output[].content[].text` 为准。

### 4.2 流式请求

将 `stream` 设置为 `true`，服务端将以 SSE（Server-Sent Events）方式逐事件推送生成过程。

::: code-group

```shell [shell]
curl -N --location --request POST 'https://maas-openapi.wanjiedata.com/api/v1/responses' \
--header "Authorization: Bearer $API_KEY" \
--header 'Content-Type: application/json' \
--data-raw '{
    "model": "<你的授权模型名称>",
    "input": "讲一个关于程序员的笑话",
    "stream": true
}'
```

```python [python]
from openai import OpenAI

client = OpenAI(
    api_key="<你的 API KEY>",
    base_url="https://maas-openapi.wanjiedata.com/api/v1",
)

stream = client.responses.create(
    model="<你的授权模型名称>",
    input="讲一个关于程序员的笑话",
    stream=True,
)

for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)
    elif event.type == "response.completed":
        print("\n[完成] usage:", event.response.usage)
```

```javascript [javascript]
const stream = await client.responses.create({
  model: "<你的授权模型名称>",
  input: "讲一个关于程序员的笑话",
  stream: true,
});

for await (const event of stream) {
  if (event.type === "response.output_text.delta") {
    process.stdout.write(event.delta);
  }
}
```
:::

**流式事件示例（SSE 原始报文）**

```
event: response.created
data: {"type":"response.created","response":{"id":"resp_5c3d2a1b","object":"response","status":"in_progress", ...}}

event: response.output_item.added
data: {"type":"response.output_item.added","output_index":0,"item":{"id":"msg_8f2e9d","type":"message","role":"assistant", ...}}

event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_8f2e9d","output_index":0,"content_index":0,"delta":"为什么"}

event: response.output_text.delta
data: {"type":"response.output_text.delta","item_id":"msg_8f2e9d","output_index":0,"content_index":0,"delta":"程序员喜欢黑夜？"}

event: response.output_text.done
data: {"type":"response.output_text.done","item_id":"msg_8f2e9d","output_index":0,"content_index":0,"text":"为什么程序员喜欢黑夜？因为没有bug。"}

event: response.completed
data: {"type":"response.completed","response":{"id":"resp_5c3d2a1b","status":"completed", ...}}
```

**常用流式事件说明**

| 事件 | 说明 |
| --- | --- |
| `response.created` | 响应已创建，`status` 为 `in_progress` |
| `response.in_progress` | 模型开始生成 |
| `response.output_item.added` / `response.output_item.done` | 输出项（message、function_call、reasoning 等）新增 / 完成 |
| `response.content_part.added` / `response.content_part.done` | 消息内容块新增 / 完成 |
| `response.output_text.delta` / `response.output_text.done` | 文本增量输出 / 文本输出完成 |
| `response.function_call_arguments.delta` / `response.function_call_arguments.done` | 函数调用参数增量输出 / 完成 |
| `response.completed` | 整个响应生成完成，携带完整 Response 对象 |
| `response.failed` / `response.incomplete` | 生成失败 / 生成未完成（原因见 `incomplete_details`） |
| `error` | 发生错误 |

### 4.3 多轮对话（previous_response_id）

Responses 接口支持服务端维护会话上下文：首轮请求拿到返回的 `id` 后，后续请求通过 `previous_response_id` 传入即可，无需重发历史消息。

```shell
# 第一轮
curl --location --request POST 'https://maas-openapi.wanjiedata.com/api/v1/responses' \
--header "Authorization: Bearer $API_KEY" \
--header 'Content-Type: application/json' \
--data-raw '{
    "model": "<你的授权模型名称>",
    "input": "武汉有什么特产？"
}'
# 响应中返回 "id": "resp_5c3d2a1b"

# 第二轮：携带上一轮的 response id
curl --location --request POST 'https://maas-openapi.wanjiedata.com/api/v1/responses' \
--header "Authorization: Bearer $API_KEY" \
--header 'Content-Type: application/json' \
--data-raw '{
    "model": "<你的授权模型名称>",
    "previous_response_id": "resp_5c3d2a1b",
    "input": "那哪一样最适合送朋友？"
}'
```

> 注意：使用 `previous_response_id` 时，上一轮的 `instructions` 不会被自动携带，如需系统提示词请每次请求都传入。

## 五、进阶用法

### 5.1 系统指令（instructions）

`instructions` 相当于 Chat Completions 中的 system 消息：

```json
{
  "model": "<你的授权模型名称>",
  "instructions": "你是一名资深旅游顾问，回答需简洁、分点列出。",
  "input": "推荐三个适合周末去的城市"
}
```

### 5.2 函数调用（Function Calling）

**第一步：声明工具并发起请求**

```json
{
  "model": "<你的授权模型名称>",
  "input": "北京今天的天气怎么样？",
  "tools": [
    {
      "type": "function",
      "name": "get_weather",
      "description": "获取指定城市的实时天气",
      "parameters": {
        "type": "object",
        "properties": {
          "city": { "type": "string", "description": "城市名称" }
        },
        "required": ["city"]
      }
    }
  ]
}
```

模型会返回 `type` 为 `function_call` 的输出项：

```json
{
  "id": "resp_7a9b",
  "output": [
    {
      "type": "function_call",
      "call_id": "call_3x2k",
      "name": "get_weather",
      "arguments": "{\"city\": \"北京\"}",
      "status": "completed"
    }
  ]
}
```

**第二步：本地执行函数后，将结果回传给模型**

```json
{
  "model": "<你的授权模型名称>",
  "previous_response_id": "resp_7a9b",
  "input": [
    {
      "type": "function_call_output",
      "call_id": "call_3x2k",
      "output": "{\"temperature\": 25, \"weather\": \"晴\"}"
    }
  ]
}
```

模型将基于函数结果生成最终自然语言回答。

### 5.3 结构化输出（Structured Outputs）

通过 `text.format` 指定 JSON Schema，模型将严格按 Schema 输出 JSON：

```json
{
  "model": "<你的授权模型名称>",
  "input": "提取这句话中的信息：张三，男，32岁，电话13800000000",
  "text": {
    "format": {
      "type": "json_schema",
      "name": "person_info",
      "schema": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "gender": { "type": "string" },
          "age": { "type": "integer" },
          "phone": { "type": "string" }
        },
        "required": ["name", "gender", "age", "phone"]
      }
    }
  }
}
```

### 5.4 图片理解（多模态输入）

`input` 支持 `input_image` 内容块，可传公网 URL 或 base64 data URL（要求模型具备多模态能力）：

```json
{
  "model": "<你的授权模型名称>",
  "input": [
    {
      "role": "user",
      "content": [
        { "type": "input_text", "text": "这张图片里有什么？" },
        {
          "type": "input_image",
          "image_url": "https://example.com/photo.jpg",
          "detail": "auto"
        }
      ]
    }
  ]
}
```

`detail` 取值：`low`、`high`、`auto`、`original`，默认 `auto`。

### 5.5 后台任务与取消（background / cancel）

创建请求时设置 `"background": true`，接口会立即返回一个排队中（`queued`）的 Response，可稍后通过查询接口获取结果；仅后台模式创建的响应支持取消：

```shell
# 取消指定的后台响应
curl --location --request POST 'https://maas-openapi.wanjiedata.com/api/v1/responses/{response_id}/cancel' \
--header "Authorization: Bearer $API_KEY"
```

> 后台模式、取消能力是否可用以授权模型实际支持情况为准，建议先小规模测试验证。

## 六、创建 Response 请求参数说明

| 参数名 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| model | string | required | 模型 ID，从[模型广场](https://www.wjark.com/center/model)复制授权模型名称 |
| input | string 或 array | required | 模型输入。可以是纯文本字符串，也可以是消息/内容块数组（`message`、`input_text`、`input_image`、`input_file`、`function_call_output` 等） |
| instructions | string | optional | 系统（developer）指令，相当于 system prompt |
| stream | boolean | optional | 是否流式输出，默认 `false` |
| previous_response_id | string | optional | 上一轮响应 ID，用于多轮对话 |
| max_output_tokens | integer | optional | 最大输出 token 数 |
| temperature | number | optional | 采样温度，0~2 |
| top_p | number | optional | 核采样参数 |
| tools | array | optional | 工具列表，支持 `{"type": "function", ...}` 等定义 |
| tool_choice | string 或 object | optional | 工具选择策略，如 `auto`、`none` 或指定函数 |
| parallel_tool_calls | boolean | optional | 是否允许并行调用工具，默认 `true` |
| text | object | optional | 文本输出配置，`format` 可设为 `text`、`json_schema`、`json_object` |
| reasoning | object | optional | 推理模型配置（`effort`、`summary` 等），仅推理类模型支持，以模型实际能力为准 |
| truncation | string | optional | 上下文截断策略：`auto` 或 `disabled`（默认 `disabled`） |
| metadata | object | optional | 最多 16 个键值对，用于业务侧标记与检索 |
| store | boolean | optional | 是否在服务端存储该响应（存储后才能通过查询/删除接口操作），以平台实际支持为准 |
| background | boolean | optional | 是否后台异步生成，默认 `false` |
| include | array | optional | 额外返回内容，如推理详情等，以模型实际支持为准 |

> 完整参数定义与 OpenAI Responses API 保持一致，详见 [OpenAI Responses API 参考](https://platform.openai.com/docs/api-reference/responses)。

## 七、Response 对象说明

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| id | string | 响应唯一标识，如 `resp_xxx` |
| object | string | 固定为 `response` |
| created_at | number | 创建时间（Unix 秒级时间戳） |
| status | string | 响应状态：`completed`、`failed`、`in_progress`、`cancelled`、`queued`、`incomplete` |
| model | string | 实际使用的模型 ID |
| output | array | 输出项列表，可能包含 `message`（文本/拒绝）、`function_call`、`reasoning` 等 |
| output_text | string | （SDK 便捷字段）聚合后的文本输出 |
| error | object | 生成失败时的错误对象，包含 `code` 与 `message`；常见 code：`server_error`、`rate_limit_exceeded`、`invalid_prompt` 等 |
| incomplete_details | object | 响应未完成的原因，`reason` 取值 `max_output_tokens`、`content_filter` |
| usage | object | token 用量：`input_tokens`、`output_tokens`、`total_tokens` |
| previous_response_id | string | 本次响应关联的上一轮响应 ID |
| instructions | string | 本次请求使用的系统指令 |
| metadata | object | 请求时附带的元数据 |

## 八、查询 / 删除 / 输入项接口示例

::: code-group

```shell [查询 Response]
curl 'https://maas-openapi.wanjiedata.com/api/v1/responses/resp_5c3d2a1b' \
  -H "Authorization: Bearer $API_KEY"
```

```shell [删除 Response]
curl --request DELETE 'https://maas-openapi.wanjiedata.com/api/v1/responses/resp_5c3d2a1b' \
  -H "Authorization: Bearer $API_KEY"
```

```shell [查询输入项]
curl 'https://maas-openapi.wanjiedata.com/api/v1/responses/resp_5c3d2a1b/input_items' \
  -H "Authorization: Bearer $API_KEY"
```
:::

## 九、错误处理

请求失败时返回的 Response 对象中会包含 `error` 字段：

```json
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Requests rate limit exceeded, please try again later."
  }
}
```

常见错误码：

| 错误码 | 说明 |
| --- | --- |
| `invalid_prompt` | 输入内容不合法或格式错误 |
| `rate_limit_exceeded` | 触发频率限制，请稍后重试 |
| `server_error` | 服务端错误，可重试 |
| `invalid_image` 等 | 图片输入相关问题（格式、大小、下载失败等） |

HTTP 状态码及更多错误说明见[错误编码说明](https://platform.openai.com/docs/guides/error-codes)。

## 十、常见问题

**Q1：Responses 接口和 Chat Completions 有什么区别？**
Chat Completions 通过 `messages` 数组传递完整历史；Responses 接口可通过 `previous_response_id` 让服务端维护会话，并对工具调用、结构化输出、流式事件做了原生增强。两者在万界方舟上使用同一个 API Key 与 Base URL。

**Q2：OpenAI 官方 SDK 可以直接使用吗？**
可以。将 `base_url` 指向 `https://maas-openapi.wanjiedata.com/api/v1`、`api_key` 替换为万界方舟 API Key 即可。注意 SDK 版本要求：Python `openai >= 1.66.0`，Node.js `openai >= 4.86.0`。

**Q3：哪些模型支持 Responses 接口？**
以[万界方舟模型广场](https://www.wjark.com/center/model)中已授权模型为准，建议优先选择 GPT、DeepSeek、Qwen、Kimi 等主流系列模型，调用前可先用简单输入验证。

**Q4：内置工具（如 web_search、file_search）支持吗？**
内置工具能力取决于模型与平台的实际支持情况，函数调用（`type: "function"`）为通用支持项，其余工具建议先测试验证。

**Q5：如何计费？**
按模型实际消耗的 token 用量（`usage` 中的输入/输出 token）计费，详见平台计费规则。