Anthropic Messages

兼容 Anthropic 官方 POST /v1/messages 接口，用于调用 Claude 系列模型，支持流式、多轮对话、工具调用、多模态输入、扩展思考（thinking）等。

WARNING

建议使用官方原生接口。本接口为 Anthropic 原生格式，是调用 Claude 系列模型的推荐方式。若通过本接口调用非 Claude 模型，由代理侧进行格式转换，可能存在参数缺失或行为差异等问题。具体支持范围请咨询 FreeAPI。

请求

Endpoint

POST https://www.free-api.ai/api/v1/messages

请求头

名称	必填	说明
Authorization	是*	Bearer your-api-key
x-api-key	是*	your-api-key，与 Authorization 二选一
anthropic-version	是	Anthropic API 版本，例如 2023-06-01
Content-Type	是	application/json

* Authorization 与 x-api-key 至少提供一个。

请求参数

字段	类型	必填	说明
model	string	是	模型 ID，例如 claude-sonnet-4-5、claude-opus-4-5
messages	array	是	消息数组，role 为 user 或 assistant
max_tokens	integer	是	最大生成 Token 数，必须 ≥ 1
system	string | array	否	系统提示词，可为字符串或带缓存控制的块数组
temperature	number	否	采样温度，范围 [0, 1]
top_p	number	否	核采样参数
top_k	integer	否	Top-K 采样
stream	boolean	否	是否流式响应
stop_sequences	string[]	否	停止序列
tools	array	否	工具定义，包含 name、description、input_schema
tool_choice	object	否	工具选择策略，type 可为 auto / any / tool / none
thinking	object	否	扩展思考配置，例如 { "type": "enabled", "budget_tokens": 8000 }
metadata	object	否	元数据，例如 { "user_id": "..." }
service_tier	string	否	服务层级，auto 或 standard_only

消息结构

{
  "role": "user | assistant",
  "content": "字符串 或 内容块数组"
}

内容块支持的 type：text、image、tool_use、tool_result。图像块的 source 支持 base64 和 url 两种方式：

{
  "type": "image",
  "source": {
    "type": "base64",
    "media_type": "image/jpeg",
    "data": "..."
  }
}

请求示例

cURL

curl https://www.free-api.ai/api/v1/messages \
  -H "Authorization: Bearer your-api-key" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "system": "你是一个资深软件工程师，回复简洁、专业。",
    "messages": [
      { "role": "user", "content": "如何用一句话概括函数式编程？" }
    ]
  }'

Python (anthropic SDK)

from anthropic import Anthropic

client = Anthropic(
    api_key="your-api-key",
    base_url="https://www.free-api.ai/api",
)

msg = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    system="你是一个资深软件工程师，回复简洁、专业。",
    messages=[
        {"role": "user", "content": "如何用一句话概括函数式编程？"}
    ],
)
print(msg.content[0].text)

启用扩展思考

{
  "model": "claude-sonnet-4-5",
  "max_tokens": 4096,
  "thinking": {
    "type": "enabled",
    "budget_tokens": 8000
  },
  "messages": [
    { "role": "user", "content": "证明勾股定理的几何方法有哪些？" }
  ]
}

响应示例

非流式

{
  "id": "msg_xxxxxxxx",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-4-5",
  "content": [
    {
      "type": "text",
      "text": "以不可变数据和纯函数组合构建程序。"
    }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 45,
    "output_tokens": 14,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0
  }
}

流式 (stream: true)

流式响应以 SSE 事件形式返回：

event: message_start
data: {"type":"message_start","message":{ ... }}

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"以不可变"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"数据"}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":14}}

event: message_stop
data: {"type":"message_stop"}

stop_reason 取值

值	含义
end_turn	模型自然结束
max_tokens	达到最大 Token 限制
stop_sequence	命中停止序列
tool_use	模型发起工具调用

常见错误

HTTP 状态	说明
400	请求参数错误
401	鉴权失败
429	请求频率限制
5xx	上游服务异常