Anthropic Claude

Anthropic 的 Claude 系列模型，擅长复杂推理和长文本处理。

基本信息

官方 API：/v1/messages
统一网关格式：/api/openai/v1/chat/completions
鉴权头：x-api-key
版本头：anthropic-version: 2023-06-01

创建消息

方法：POST
官方路径：/v1/messages
统一路径：/api/openai/v1/chat/completions

请求头

名称	必填	说明
`x-api-key`	是	用于身份验证的 API 密钥
`anthropic-version`	是	要使用的 Anthropic API 版本
`content-type`	是	请求内容类型，固定为 `application/json`

请求体

字段	类型	必填	说明
`model`	`string`	是	例如 `claude-3-5-sonnet-20241022`
`messages`	`array`	是	输入消息数组
`max_tokens`	`integer`	是	最大输出 token 数
`stream`	`boolean`	否	是否启用 SSE 流式
`temperature`	`number`	否	范围 `0.0` 到 `1.0`
`system`	`string`	否	系统提示
`top_p`	`number`	否	nucleus 采样参数
`top_k`	`integer`	否	前 K 采样参数

请求示例

官方格式

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-3-5-sonnet-20241022",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Hello, Claude!"}
    ]
  }'

统一格式

curl https://your-domain.com/api/openai/v1/chat/completions \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-3-5-sonnet-20241022",
    "messages": [
      {"role": "user", "content": "Hello, Claude!"}
    ]
  }'

TypeScript

import Anthropic from '@anthropic-ai/sdk'

const client = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
})

const message = await client.messages.create({
  model: 'claude-3-5-sonnet-20241022',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Hello, Claude!' }],
})

console.log(message.content)

Python

from anthropic import Anthropic
import os

client = Anthropic(api_key=os.environ.get("ANTHROPIC_API_KEY"))

message = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude!"}],
)

print(message.content)

成功响应

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello! How can I help you today?"
    }
  ],
  "model": "claude-3-5-sonnet-20241022",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 12,
    "output_tokens": 8
  }
}

速率限制

每分钟请求数：50
每分钟 token 数：100000
说明：速率限制因模型和使用层级而异，请结合响应头确认当前限制
相关响应头：
- anthropic-ratelimit-requests-limit
- anthropic-ratelimit-requests-remaining
- anthropic-ratelimit-requests-reset

流式响应

协议：SSE
事件类型：message_start、content_block_start、content_block_delta、content_block_stop、message_delta、message_stop

TypeScript 流式示例

const stream = await client.messages.stream({
  model: 'claude-3-5-sonnet-20241022',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Write a haiku about coding' }],
})

for await (const event of stream) {
  if (event.type === 'content_block_delta') {
    process.stdout.write(event.delta.text)
  }
}

Tool Use / 函数调用

Claude 支持通过 Tool Use 格式进行结构化工具调用。

const response = await client.messages.create({
  model: 'claude-3-5-sonnet-20241022',
  max_tokens: 1024,
  tools: [{
    name: 'get_weather',
    description: 'Get the current weather in a given location',
    input_schema: {
      type: 'object',
      properties: {
        location: { type: 'string' }
      },
      required: ['location']
    }
  }],
  messages: [{
    role: 'user',
    content: "What's the weather like in San Francisco?"
  }]
})

Prompt Caching

支持缓存写入和缓存读取统计
usage 中会返回 cache_creation_input_tokens
命中缓存后会返回 cache_read_input_tokens
仅对标记 cache_control 的前缀生效

模型

模型	上下文窗口	最大输出	价格（输入 / 输出，USD / 1M）	能力
Claude 3.5 Sonnet	`200000`	`8192`	`3 / 15`	流式、工具调用、视觉
Claude 3 Opus	`200000`	`4096`	`15 / 75`	流式、工具调用、视觉
Claude 3 Sonnet	`200000`	`4096`	`3 / 15`	流式、工具调用、视觉
Claude 3 Haiku	`200000`	`4096`	`0.25 / 1.25`	流式、工具调用、视觉

SDK

语言	包名	安装命令	仓库
TypeScript	`@anthropic-ai/sdk`	`npm install @anthropic-ai/sdk`	`https://github.com/anthropics/anthropic-sdk-typescript`
Python	`anthropic`	`pip install anthropic`	`https://github.com/anthropics/anthropic-sdk-python`

常见错误码

代码	HTTP 状态	含义	处理建议
`invalid_request_error`	`400`	请求无效	检查请求格式和缺失字段
`authentication_error`	`401`	身份验证失败	检查 API 密钥
`permission_error`	`403`	权限不足	检查 key 权限
`not_found_error`	`404`	未找到资源	检查路径和参数
`rate_limit_error`	`429`	超出速率限制	结合 `retry-after` 退避重试
`overloaded_error`	`529`	服务暂时过载	使用指数退避重试

最佳实践

使用系统提示设置上下文和指令
为速率限制错误实现指数退避
流式传输响应以获得更好的用户体验
为可复用前缀添加 cache_control 以启用 Prompt Caching
监控 token 使用以优化成本
利用工具调用实现结构化输出