Responses（联网搜索） - 数字先锋API文档

# Responses API（联网搜索）

## 1. 接口说明

部分模型仅支持 `Responses` 格式调用，不支持 `/v1/chat/completions`。
当需要使用联网能力（Web Search）时，请使用：

```http
POST /v1/responses
```

Base URL（示例）：
```text
https://api.cxsee.com
```

完整地址：
```text
https://api.cxsee.com/v1/responses
```

---

## 2. 适用模型（示例）

以下模型通常使用 Responses 格式：

- `o3-pro`
- `gpt-4o-mini-search-preview`
- `net-gpt-4`
- `codex-mini-latest`
- `o3-deep-research-2025-06-26`（示例）

> 具体可用模型请以控制台模型列表为准。

---

## 3. 认证方式

请求头：

```http
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

---

## 4. 请求参数

| 参数 | 类型 | 必填 | 说明 |
|---|---|---:|---|
| `model` | string | 是 | 模型名称（Responses 兼容模型） |
| `input` | array/string | 是 | 输入内容，推荐消息数组格式 |
| `tools` | array | 否 | 工具列表；联网搜索需配置 `web_search_preview` |
| `stream` | boolean | 否 | 是否流式返回 |
| `temperature` | number | 否 | 采样温度（模型支持时生效） |
| `max_output_tokens` | integer | 否 | 最大输出 token（模型支持时生效） |

---

## 5. 联网搜索请求示例（cURL）

```bash
curl --location --request POST 'https://api.cxsee.com/v1/responses' \
--header 'Authorization: Bearer {{YOUR_API_KEY}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "model": "o3-deep-research-2025-06-26",
  "input": [
    {
      "role": "user",
      "content": "hi"
    }
  ],
  "tools": [
    {
      "type": "web_search_preview"
    }
  ]
}'
```

---

## 6. 成功响应示例（示意）

```json
{
  "id": "resp_123",
  "object": "response",
  "created_at": 1774039000,
  "model": "o3-deep-research-2025-06-26",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Hello! I can search the web if you want latest information."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 12,
    "output_tokens": 25,
    "total_tokens": 37
  }
}
```

---

## 7. 返回内容读取方式

优先从：

- `output[]` 中 `type=message` 的内容读取
- 文本通常位于 `content[]` -> `type=output_text` -> `text`

---

## 8. 常见错误码

- `400` 参数错误（如 tools 格式错误）
- `401` API Key 无效或缺失
- `403` 模型无权限
- `404` 模型不存在或不可用
- `429` 请求频率超限
- `500/502/503` 服务异常

---

## 9. 最佳实践

1. **先确认模型是否仅支持 `/v1/responses`**，避免接口选错。
2. 开启联网时显式传入：
   ```json
   "tools": [{"type":"web_search_preview"}]
   ```
3. 对生产环境增加超时、重试、限流与审计日志。
4. 若需可追溯结果，建议在提示词中要求“给出来源摘要/引用链接”。

---

上一篇：Gemini 官方格式下一篇：多模型同屏对比体验（同步输出）