Anthropic Claude API 使用手册

一、概述

Anthropic Claude API 提供 Claude 系列模型的访问，以长上下文、高质量输出和安全对齐著称。API 同时支持 OpenAI 兼容格式和原生 Anthropic 格式。

二、认证

x-api-key: sk-ant-xxxxxxxxxxxxxxxx
anthropic-version: 2023-06-01

API Key 在 console.anthropic.com 创建。

三、Base URL

原生格式：https://api.anthropic.com/v1
OpenAI兼容：https://api.anthropic.com/v1/openai

四、模型列表

五、Messages API

请求

POST /v1/messages

{
  "model": "claude-sonnet-4-20250514",
  "max_tokens": 4096,
  "system": "You are a helpful assistant.",
  "messages": [
    {"role": "user", "content": "Hello!"}
  ],
  "temperature": 0.7,
  "top_p": 1,
  "top_k": 0,
  "stream": false
}

参数说明

响应

{
  "id": "msg_xxx",
  "type": "message",
  "role": "assistant",
  "content": [
    {"type": "text", "text": "Hello! How can I help you?"}
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 10,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0
  }
}

六、多模态输入

图像（Base64）

"messages": [{
  "role": "user",
  "content": [
    {
      "type": "image",
      "source": {
        "type": "base64",
        "media_type": "image/png",
        "data": "iVBORw0KGgo..."
      }
    },
    {"type": "text", "text": "描述这张图片"}
  ]
}]

图像（URL）

"content": [
  {
    "type": "image",
    "source": {
      "type": "url",
      "url": "https://example.com/photo.jpg"
    }
  },
  {"type": "text", "text": "分析这张图"}
]

PDF文档

"content": [
  {
    "type": "document",
    "source": {
      "type": "base64",
      "media_type": "application/pdf",
      "data": "JVBERi0xLjQ..."
    }
  },
  {"type": "text", "text": "总结文档要点"}
]

七、Tool Use（工具调用）

定义工具

"tools": [{
  "name": "calculator",
  "description": "执行数学计算",
  "input_schema": {
    "type": "object",
    "properties": {
      "expression": {"type": "string", "description": "数学表达式"}
    },
    "required": ["expression"]
  }
}]

处理工具调用

// 模型返回 tool_use block
if (response.stop_reason === "tool_use") {
  const toolBlock = response.content.find(b => b.type === "tool_use");
  
  // 执行函数并返回结果
  const result = await calculator(toolBlock.input.expression);
  
  const followUp = await client.messages.create({
    model: "claude-sonnet-4-20250514",
    max_tokens: 4096,
    tools: tools,
    messages: [
      {"role": "user", "content": "计算 2+2"},
      {"role": "assistant", "content": response.content},
      {
        "role": "user",
        "content": [{
          "type": "tool_result",
          "tool_use_id": toolBlock.id,
          "content": result.toString()
        }]
      }
    ]
  });
}

八、扩展思考（Extended Thinking）

{
  "model": "claude-sonnet-4-20250514",
  "max_tokens": 16000,
  "thinking": {
    "type": "enabled",
    "budget_tokens": 10000
  },
  "messages": [
    {"role": "user", "content": "证明费马大定理的特殊情况n=4"}
  ]
}

响应中会包含 thinking 类型的 content block，展示推理过程。

九、流式输出

const stream = client.messages.stream({
  model: "claude-sonnet-4-20250514",
  max_tokens: 1024,
  messages: [{"role": "user", "content": "Hello!"}]
});

stream.on("text", (text) => {
  process.stdout.write(text);
});

十、Prompt Caching（提示缓存）

标记可缓存的内容块，减少重复计费：

"system": [{
  "type": "text",
  "text": "很长的系统指令...",
  "cache_control": {"type": "ephemeral"}
}]

缓存命中的 token 价格降低 90%。

十一、速率限制

十二、错误码