Anthropic Messages API#

通过 UniGateway 调用 Anthropic Messages API，使用 Claude 的原生扩展能力。

前置条件#

• 已获取 UniGateway API Key，保存在环境变量 UNIGATEWAY_API_KEY 中
• 已通过 GET /v1/models 确认目标 Claude 模型在当前账号中可用

概述#

• 端点：POST /v1/messages
• Base URL：https://api.unigateway.ai/v1
• 请求头：
  • Authorization: Bearer <YOUR_UNIGATEWAY_API_KEY>
  • Content-Type: application/json
  • anthropic-version: 2023-06-01

UniGateway 在 POST /v1/messages 上代理 Anthropic Messages 协议。以下 Claude 特有扩展能力通过该接口可用：

• thinking 扩展推理块
• cache_control 提示缓存
• 细粒度的 stop_reason
• PDF / 图像 / 引用 / 工具调用

请求#

基本请求#

curl https://api.unigateway.ai/v1/messages \
  -H "Authorization: Bearer $UNIGATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "用一段话解释量子计算。"}
    ]
  }'

参数#

Messages 格式#

单条文本消息：

{
  "role": "user",
  "content": "用一段话解释量子计算。"
}

多模态 content 使用数组：

{
  "role": "user",
  "content": [
    {"type": "text", "text": "描述这张图片。"},
    {
      "type": "image",
      "source": {
        "type": "base64",
        "media_type": "image/jpeg",
        "data": "/9j/4AAQSkZJRg..."
      }
    }
  ]
}

支持的 content source 类型：

PDF 通过 document 类型传入：

{
  "type": "document",
  "source": {
    "type": "base64",
    "media_type": "application/pdf",
    "data": "JVBERi0xLjQK..."
  }
}

扩展推理（Thinking）#

启用 Claude 的扩展推理：

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 4096,
  "thinking": {
    "type": "enabled",
    "budget_tokens": 2048
  },
  "messages": [
    {"role": "user", "content": "证明 sqrt(2) 是无理数。"}
  ]
}

启用 thinking 后，响应中包含 thinking content block。max_tokens 必须大于 budget_tokens。

提示缓存（Prompt Caching）#

在消息或工具定义上添加 cache_control 以减少重复输入成本：

{
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": "长文档或系统提示内容...",
      "cache_control": {"type": "ephemeral"}
    }
  ]
}

cache_control.type 当前仅支持 ephemeral。命中缓存会在响应 usage 中显示 cache_read_input_tokens 和 cache_creation_input_tokens。

工具调用#

定义工具：

{
  "tools": [
    {
      "name": "get_weather",
      "description": "获取某地当前天气",
      "input_schema": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "城市名称"
          }
        },
        "required": ["location"]
      }
    }
  ]
}

工具选择策略：

{
  "tool_choice": {"type": "auto"}
}

返回工具结果时，在 messages 中添加 role: user 的 tool_result 块：

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01T1x1fJ34qAmk2tNTrN7Up6",
      "content": "22°C, 晴"
    }
  ]
}

响应#

{
  "id": "msg_01XgYfV9UTi2PJN",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-4-6",
  "content": [
    {
      "type": "text",
      "text": "量子计算利用叠加态..."
    }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 14,
    "output_tokens": 128
  }
}

响应字段#

流式输出#

设置 stream: true 开启 SSE：

curl https://api.unigateway.ai/v1/messages \
  -H "Authorization: Bearer $UNIGATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "你好"}],
    "stream": true
  }'

SSE 事件类型包括 message_start、content_block_start、content_block_delta、content_block_stop、message_delta、message_stop。

错误处理#