> ## Documentation Index
> Fetch the complete documentation index at: https://doc.octopusx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAI 多模态响应接口

> 使用 OpenAI Responses API 格式创建响应，支持多模态输入、工具调用、流式输出和上下文压缩。

# OpenAI 多模态响应接口

Responses API 是面向多模态、工具调用和上下文续接的统一响应接口。相比 Chat Completions，它的输入、输出和工具调用结构更适合复杂任务编排。

## 请求体

<ParamField body="model" type="string" required>
  模型名称。
</ParamField>

<ParamField body="input" type="string | array<object>">
  用户输入。可以是字符串，也可以是结构化消息数组。
</ParamField>

<ParamField body="instructions" type="string">
  开发者或系统级指令。
</ParamField>

<ParamField body="previous_response_id" type="string">
  上一轮响应 ID。上游支持时可用于上下文续接。
</ParamField>

<ParamField body="tools" type="array<object>">
  工具列表。支持函数工具，也可转发上游兼容的内置工具。
</ParamField>

<ParamField body="tool_choice" type="string | object">
  工具选择策略。
</ParamField>

<ParamField body="max_output_tokens" type="integer">
  最大输出 token 数。显式传 `0` 会被保留并转发给支持的上游。
</ParamField>

<ParamField body="reasoning" type="object">
  推理配置，例如 `{ "effort": "medium", "summary": "auto" }`。
</ParamField>

<ParamField body="text" type="object">
  文本输出配置，常用于 JSON Schema 结构化输出。
</ParamField>

<ParamField body="stream" type="boolean">
  是否启用 SSE 流式输出。
</ParamField>

<ParamField body="stream_options.include_usage" type="boolean">
  流式响应中是否包含 token 用量。
</ParamField>

<ParamField body="store" type="boolean">
  控制上游是否存储请求和响应。该字段默认允许转发，可由渠道设置禁用。
</ParamField>

<ParamField body="metadata" type="object">
  业务侧附加元数据。
</ParamField>

<ParamField body="include" type="array<string>">
  请求响应中额外包含的字段，具体取值取决于上游实现。
</ParamField>

## 请求示例

<RequestExample>
  ```bash theme={null}
  curl -X POST https://octopusx.ai/v1/responses \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-4o",
      "instructions": "你是一个简洁的技术助手。",
      "input": "用三句话解释 Responses API 适合什么场景。"
    }'
  ```
</RequestExample>

### 多模态输入

```bash theme={null}
curl -X POST https://octopusx.ai/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "input": [
      {
        "role": "user",
        "content": [
          { "type": "input_text", "text": "提取这张截图中的异常指标。" },
          { "type": "input_image", "image_url": "https://.../dashboard.png", "detail": "high" }
        ]
      }
    ]
  }'
```

### 工具调用

```bash theme={null}
curl -X POST https://octopusx.ai/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "input": "北京今天适合户外跑步吗？",
    "tools": [
      {
        "type": "function",
        "name": "get_weather",
        "description": "获取城市天气",
        "parameters": {
          "type": "object",
          "properties": {
            "city": { "type": "string" }
          },
          "required": ["city"]
        }
      }
    ],
    "tool_choice": "auto"
  }'
```

### 流式输出

```bash theme={null}
curl -N -X POST https://octopusx.ai/v1/responses \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "input": "写一个 5 行以内的产品发布公告。",
    "stream": true,
    "stream_options": {
      "include_usage": true
    }
  }'
```

## 响应示例

<ResponseExample>
  ```json 200 - 非流式 theme={null}
  {
    "id": "resp_abc123",
    "object": "response",
    "created_at": 1735689600,
    "status": "completed",
    "model": "gpt-4o",
    "output": [
      {
        "type": "message",
        "id": "msg_abc123",
        "status": "completed",
        "role": "assistant",
        "content": [
          {
            "type": "output_text",
            "text": "Responses API 适合多模态输入、工具调用和需要上下文续接的任务。它把输出拆成结构化 item，便于程序读取。通过统一网关可以复用同一套认证、计费和渠道分发能力。",
            "annotations": []
          }
        ]
      }
    ],
    "usage": {
      "prompt_tokens": 26,
      "completion_tokens": 62,
      "total_tokens": 88
    }
  }
  ```

  ```text 200 - 流式 theme={null}
  data: {"type":"response.created","response":{"id":"resp_abc123","object":"response","status":"in_progress","model":"gpt-4o"}}

  data: {"type":"response.output_text.delta","delta":"Responses"}

  data: {"type":"response.output_text.delta","delta":" API"}

  data: {"type":"response.completed","response":{"id":"resp_abc123","status":"completed","usage":{"prompt_tokens":26,"completion_tokens":62,"total_tokens":88}}}

  data: [DONE]
  ```

  ```json 400 theme={null}
  {
    "error": {
      "message": "model is required",
      "type": "invalid_request_error",
      "param": "",
      "code": "invalid_request"
    }
  }
  ```

  ```json 401 theme={null}
  {
    "error": {
      "message": "Invalid API key provided",
      "type": "invalid_request_error",
      "param": "",
      "code": "invalid_api_key"
    }
  }
  ```

  ```json 402 theme={null}
  {
    "error": {
      "message": "用户额度不足",
      "type": "new_api_error",
      "param": "",
      "code": "insufficient_user_quota"
    }
  }
  ```

  ```json 429 theme={null}
  {
    "error": {
      "message": "当前请求频率过高，请稍后再试",
      "type": "new_api_error",
      "param": "",
      "code": "too_many_requests"
    }
  }
  ```

  ```json 500 theme={null}
  {
    "error": {
      "message": "bad response body",
      "type": "new_api_error",
      "param": "",
      "code": "bad_response_body"
    }
  }
  ```
</ResponseExample>

## 上下文压缩

```http theme={null}
POST /v1/responses/compact
```

用于把较长上下文压缩成适合后续继续对话的摘要。请求结构与 `/v1/responses` 接近，常用字段为 `model`、`input`、`instructions`、`previous_response_id`。

```bash theme={null}
curl -X POST https://octopusx.ai/v1/responses/compact \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "instructions": "压缩成后续对话可继续使用的上下文，保留决策、约束和待办。",
    "input": [
      { "role": "user", "content": "第一轮需求..." },
      { "role": "assistant", "content": "第一轮方案..." }
    ]
  }'
```

## 相关接口

* [通用对话接口（默认非流式）](./chat-completions-non-stream)
* [通用对话接口（默认流式）](./chat-completions-stream)