Claude API 中转接入：Messages 请求与 Python 示例

Claude API 接入首先要分清原生 Messages 协议与 OpenAI SDK compatibility：它们的 Base URL 边界、请求头、消息结构和功能覆盖不同。

说到“Claude API 中转”，要先讲清是原生 Claude Messages API 还是 OpenAI 兼容层；本文以 Claude API Key、ANTHROPIC_BASE_URL 和可核验事件为边界，不用一个“兼容”标签代替协议说明。

export GPTZZZ_API_KEY="YOUR_GPTZZZ_API_KEY"
export CLAUDE_MODEL="claude-sonnet-5"

curl --fail-with-body -sS -D /tmp/claude-headers.txt \
  "https://gptzzz.ai/v1/messages" \
  -H "x-api-key: $GPTZZZ_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d "{\"model\":\"$CLAUDE_MODEL\",\"max_tokens\":256,\"messages\":[{\"role\":\"user\",\"content\":\"只回复 CLAUDE_OK\"}]}"

$env:GPTZZZ_API_KEY = "YOUR_GPTZZZ_API_KEY"
$env:CLAUDE_MODEL = "claude-sonnet-5"

$body = @{
  model = $env:CLAUDE_MODEL
  max_tokens = 256
  messages = @(@{ role = "user"; content = "只回复 CLAUDE_OK" })
} | ConvertTo-Json -Depth 5
Invoke-RestMethod -Method Post -Uri "https://gptzzz.ai/v1/messages" `
  -Headers @{ "x-api-key" = $env:GPTZZZ_API_KEY; "anthropic-version" = "2023-06-01" } `
  -ContentType "application/json; charset=utf-8" `
  -Body ([System.Text.Encoding]::UTF8.GetBytes($body))

Claude Base URL 与密钥位置

原生 SDK 会读取 ANTHROPIC_API_KEY 与 ANTHROPIC_BASE_URL。CLAUDE_MODEL、ANTHROPIC_MODEL 和 ANTHROPIC_VERSION 都不是 Python SDK 自动读取的模型/版本环境变量；SDK 会管理必要的 API 版本请求头。下面的 GPTZZZ 示例把 GPTZZZ_API_KEY 和 base_url 显式传给客户端，避免和官方 Key 混用。

Claude Python SDK 与完整响应验证

python -m pip install -U anthropic

import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ["GPTZZZ_API_KEY"],
    base_url="https://gptzzz.ai",  # 只填主机根，不写 /v1/messages
    timeout=90.0,
    max_retries=2,
)
message = client.messages.create(
    model=os.environ["CLAUDE_MODEL"],
    max_tokens=256,
    messages=[{"role": "user", "content": "只回复 CLAUDE_OK"}],
)

texts = [block.text for block in message.content if block.type == "text"]
if message.type != "message" or message.role != "assistant" or not texts:
    raise RuntimeError(f"unexpected response: {message.to_json()}")
if message.stop_reason != "end_turn":
    raise RuntimeError(f"unexpected stop_reason={message.stop_reason!r}")

print("".join(texts))
print({
    "request_id": message._request_id,
    "input_tokens": message.usage.input_tokens,
    "output_tokens": message.usage.output_tokens,
})

对这条“只回复固定文本”的探针，end_turn 是预期；真实应用还要分别处理 max_tokens、tool_use、pause_turn、refusal 等有业务含义的结束原因。

Claude 流式输出与 message_stop

with client.messages.stream(
    model=os.environ["CLAUDE_MODEL"],
    max_tokens=512,
    messages=[{"role": "user", "content": "分三点解释 API 网关"}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
    final_message = stream.get_final_message()
    request_id = stream.request_id

print()
print(final_message.stop_reason)
print(final_message.usage.output_tokens)
print(request_id)

Raw SSE 正常链路包含 message_start、内容块事件、message_delta 与 message_stop；可夹有 ping。错误也可能在 HTTP 200 后以 error 事件到达，解析器还应忽略它暂时不认识的新事件类型。

Claude 的 OpenAI 兼容层能做什么

Anthropic 官方将 OpenAI SDK compatibility 定位为测试和比较模型能力的便捷层，而不是多数场景的长期生产方案。需要 PDF、citations、完整 thinking、prompt caching 或原生内容块时，使用 Messages API。

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ANTHROPIC_API_KEY"],
    base_url="https://api.anthropic.com/v1/",
)
response = client.chat.completions.create(
    model="claude-opus-5-5",  # Anthropic 官方模型 ID，不是 GPTZZZ 的 ID
    messages=[{"role": "user", "content": "只回复 CLAUDE_OK"}],
)
print(response.choices[0].message.content)

兼容层会忽略或降级部分字段：工具调用的 strict 不生效，audio 会被丢弃，prompt caching 不支持，多个 system/developer 消息会被合并，n 必须为 1。不要把无报错当成字段已生效。

错误类型与重试边界

Claude Code 的环境变量接入见 Claude Code 中转站配置；内容块、工具与 SSE 用 流式与工具兼容性矩阵验证；密钥隔离参考 API Key 安全指南；退避与幂等边界见 重试与回退设计。

Claude API 验证指标与回滚

对固定探针记录 HTTP 状态、首个 content_block_delta 时间、message_stop 完成率、总耗时、stop_reason、输入/输出 Token、重试次数和 request-id。工具用例另算完整闭环率（成功回传 tool_result 的任务数 ÷ 工具任务总数）。

1. 终止在途消息与工具任务，保存最后事件和未执行的 tool_use ID。
2. 恢复原 ANTHROPIC_BASE_URL、Key 来源和模型 ID，关闭旧连接。
3. 在新进程运行相同 curl、Python 与流式探针。
4. 确认内容块、结束原因、用量和工具闭环恢复后，再清理中转配置。

官方资料

• Anthropic API Overview
• Anthropic Messages API
• Anthropic Python SDK
• Anthropic Streaming
• Anthropic Errors
• Anthropic OpenAI SDK compatibility