Responses API 适合 Codex、Agent、工具调用和新一代 GPT 工作流。Codex CLI 通过自定义 Provider 接入 ZCloudAPI 时，底层主要使用这个接口。

开始前准备

1. 在 https://console.zcloudapi.com 创建一条有 GPT 模型权限的 API Key。
2. 确认账户有可用余额。
3. 把 Key 放进当前终端。

macOS / Linux：

export ZHICLOUD_API_KEY="sk-你的-ZCloudAPI-Key"

Windows PowerShell：

$env:ZHICLOUD_API_KEY="sk-你的-ZCloudAPI-Key"

第一步：确认 GPT 模型

curl "https://api.zcloudapi.com/v1/models" \
  -H "Authorization: Bearer $ZHICLOUD_API_KEY"

从 data[].id 中选择 GPT 模型。下面使用 gpt-5.6-terra；如果它不在你的列表里，请改成实际返回的 GPT 模型。

第二步：发送最小 Responses 请求

macOS / Linux：

curl -i "https://api.zcloudapi.com/v1/responses" \
  -H "Authorization: Bearer $ZHICLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra",
    "input": "只回复：Responses 连接成功",
    "max_output_tokens": 128,
    "stream": false
  }'

Windows PowerShell：

$body = @{
  model = "gpt-5.6-terra"
  input = "只回复：Responses 连接成功"
  max_output_tokens = 128
  stream = $false
} | ConvertTo-Json -Depth 5

curl.exe -i "https://api.zcloudapi.com/v1/responses" `
  -H "Authorization: Bearer $env:ZHICLOUD_API_KEY" `
  -H "Content-Type: application/json" `
  -d $body

先确认状态码为 200，再解析正文。

第三步：读取响应结构

典型响应：

{
  "status": "completed",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Responses 连接成功"
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 20,
    "output_tokens": 8,
    "total_tokens": 28
  }
}

解析时按下面顺序处理：

1. 检查顶层 status 是否为 completed。
2. 遍历 output，按每一项的 type 区分消息和工具调用。
3. 对 type: message 的项继续遍历 content。
4. 读取 type: output_text 的 text。
5. 从 usage 读取输入、输出和总 Token。

不要假设 output[0].content[0] 永远是文本。Agent 请求可能先返回推理项、工具调用或其他结构。

第四步：使用 Python SDK

1. 安装或升级 SDK：

python -m pip install --upgrade openai

2. 新建 responses_demo.py：

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ZHICLOUD_API_KEY"],
    base_url="https://api.zcloudapi.com/v1",
    timeout=90.0,
    max_retries=2,
)

response = client.responses.create(
    model="gpt-5.6-terra",
    input="只回复：Responses 连接成功",
    max_output_tokens=128,
)

print(response.output_text)
print(response.usage)

3. 在同一个终端运行：

python responses_demo.py

第五步：使用 Node.js SDK

1. 安装 SDK：

npm install openai

2. 新建 responses-demo.mjs：

import OpenAI from 'openai'

const client = new OpenAI({
  apiKey: process.env.ZHICLOUD_API_KEY,
  baseURL: 'https://api.zcloudapi.com/v1',
  timeout: 90_000,
  maxRetries: 2,
})

const response = await client.responses.create({
  model: 'gpt-5.6-terra',
  input: '只回复：Responses 连接成功',
  max_output_tokens: 128,
})

console.log(response.output_text)
console.log(response.usage)

3. 运行：

node responses-demo.mjs

第六步：从简单输入升级到多段输入

简单任务可以直接传字符串。需要区分角色或加入多段内容时，可以使用结构化 input：

{
  "model": "gpt-5.6-terra",
  "input": [
    {
      "role": "user",
      "content": [
        {"type": "input_text", "text": "检查下面需求并列出三项风险。"}
      ]
    }
  ],
  "max_output_tokens": 256,
  "stream": false
}

先让结构化文本请求成功，再按 SDK 和目标模型能力增加图片、工具或其他输入类型。

第七步：验证 Codex 所需链路

如果你的最终目标是 Codex：

1. 使用本页 curl 确认 /v1/responses 返回 200。
2. 确认模型出现在 /v1/models。
3. 到控制台「使用日志」核对该模型和用量。
4. 再按「配置 Codex」写入 config.toml。
5. 最后运行 codex exec --skip-git-repo-check "只回复 OK"。

curl 都没有成功之前，不要先排查 Codex 配置。

与 Chat Completions 的区别

项目	Chat Completions	Responses API
输入字段	messages	input
文本位置	choices[0].message.content	output 中的 output_text
常见用途	普通对话、兼容客户端	Codex、Agent、工具调用
Codex CLI	不使用	使用

完成检查

• /v1/responses 返回 200。
• status 为 completed。
• SDK 的 output_text 能读取正文。
• usage 有输入和输出 Token。
• 控制台使用日志出现同一次请求。

常见错误

现象	处理步骤
model not found	从 /v1/models 复制准确的 GPT 模型名
按 choices 读取不到正文	Responses 使用 output，不是 Chat Completions 的 choices
Codex 跳转 OpenAI 登录	自定义 Provider 不要设置 requires_openai_auth = true
结构化输入返回 400	先退回字符串 input，再逐项检查内容类型
流式请求失败	先用 stream: false 验证，再检查客户端事件解析
响应中出现非文本项	按 type 遍历 output，不要固定读取数组第一项