Claude Messages

Claude Messages 适合已经使用 Anthropic SDK 或需要 Claude 原生消息结构的项目。请求中必须带上 anthropic-version。

接口概览

项目	说明
方法	`POST`
路径	`/v1/messages`
Base URL	`https://cdn.12ai.org`
请求格式	`application/json`
认证	`x-api-key: $API_KEY`
版本头	`anthropic-version: 2023-06-01`

认证写法

Anthropic 官方 Messages API 使用 x-api-key。如果你的客户端只能发送 OpenAI 风格 Header，12API 也兼容 Authorization: Bearer $API_KEY。

请求体

参数	类型	必填	说明
`model`	string	是	Claude 模型名称
`messages`	array	是	对话消息数组
`max_tokens`	integer	是	最大输出 token 数
`system`	string \| array	否	系统提示词；Claude 不使用 `system` 角色消息
`stream`	boolean	否	是否流式返回
`temperature`	number	否	随机性，范围通常为 `0` 到 `1`
`tools`	array	否	工具定义
`tool_choice`	object	否	工具选择策略
`thinking`	object	否	Extended Thinking 配置
`metadata`	object	否	元数据
`stop_sequences`	array	否	停止序列

messages

参数	类型	必填	说明
`role`	string	是	`user` 或 `assistant`
`content`	string \| array	是	文本，或由文本、图片等组成的内容块

工具定义

Claude 工具的参数 schema 字段名为 input_schema，不是 OpenAI 的 parameters。

{
  "tools": [
    {
      "name": "get_weather",
      "description": "查询天气",
      "input_schema": {
        "type": "object",
        "properties": {
          "city": {"type": "string"}
        },
        "required": ["city"]
      }
    }
  ]
}

请求示例

curl https://cdn.12ai.org/v1/messages \
  -H "x-api-key: $API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5-20250929",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "用一句话解释 Claude Messages API"}
    ]
  }'

import anthropic

client = anthropic.Anthropic(
    api_key="sk-xxx",
    base_url="https://cdn.12ai.org",
)

message = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "用一句话解释 Claude Messages API"}
    ],
)

print(message.content[0].text)

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  apiKey: "sk-xxx",
  baseURL: "https://cdn.12ai.org",
});

const message = await client.messages.create({
  model: "claude-sonnet-4-5-20250929",
  max_tokens: 1024,
  messages: [
    { role: "user", content: "用一句话解释 Claude Messages API" },
  ],
});

console.log(message.content[0].text);

import anthropic

client = anthropic.Anthropic(
    api_key="sk-xxx",
    base_url="https://cdn.12ai.org",
)

with client.messages.stream(
    model="claude-sonnet-4-5-20250929",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "写一段很短的中文欢迎语"}
    ],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

响应结构

字段	类型	说明
`id`	string	消息 ID
`type`	string	固定为 `message`
`role`	string	固定为 `assistant`
`content`	array	输出内容块
`model`	string	实际调用的模型
`stop_reason`	string	停止原因
`usage`	object	token 用量统计

响应示例

{
  "id": "msg_xxx",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Claude Messages API 是 Anthropic 的原生对话接口。"
    }
  ],
  "model": "claude-sonnet-4-5-20250929",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 18,
    "output_tokens": 16
  }
}

图片输入

Claude 原生格式的图片输入使用 content 数组。图片可以放在 source 中，并用 base64 传入。

import base64
import anthropic

client = anthropic.Anthropic(
    api_key="sk-xxx",
    base_url="https://cdn.12ai.org",
)

with open("image.jpg", "rb") as f:
    image_data = base64.b64encode(f.read()).decode("utf-8")

message = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": "image/jpeg",
                        "data": image_data,
                    },
                },
                {"type": "text", "text": "描述这张图片"},
            ],
        }
    ],
)

print(message.content[0].text)

Extended Thinking

需要深度推理时，可以开启 thinking。开启后应给足 max_tokens，并设置合理的 budget_tokens。

{
  "model": "claude-sonnet-4-5-20250929",
  "max_tokens": 16000,
  "thinking": {
    "type": "enabled",
    "budget_tokens": 10000
  },
  "messages": [
    {"role": "user", "content": "解释一个复杂系统的设计取舍"}
  ]
}

max_tokens 仍然必填

Claude Messages 官方接口要求 max_tokens。即使只想让模型短回答，也需要显式传入该字段。

常用模型

模型	说明
`claude-opus-4-5-20251101`	更强推理与复杂任务
`claude-sonnet-4-5-20250929`	通用任务首选
`claude-haiku-4-5-20251001`	轻量、低延迟任务

更多参数细节可参考 Anthropic Messages API。

Claude Messages

On this page