API 快速入门：第一次 API 调用

从这篇文章开始，我们进入 Claude 的开发者世界。通过 API，你可以把 Claude 的能力集成到任何应用中——聊天机器人、内容生成工具、数据分析平台、自动化工作流。本文带你完成第一次 API 调用，从零到能跑通。

你将学到什么

• 注册 Anthropic 开发者账号并获取 API Key
• 用 Python 和 TypeScript 两种语言调用 Claude API
• 理解 Messages API 的基本结构
• 处理 API 响应和常见错误

获取 API Key

1. 访问 console.anthropic.com 并注册账号
2. 进入 API Keys 页面
3. 点击 Create Key，给它一个名字（如 "my-first-key"）
4. 复制生成的 Key（以 sk-ant- 开头），保存到安全的地方

Warning: API Key 是你的密钥，不要提交到 Git 仓库或分享给他人。使用环境变量来管理。

Python 快速开始

安装 SDK

pip install anthropic

第一次调用

import anthropic

client = anthropic.Anthropic(
    api_key="your-api-key-here"  # 或设置 ANTHROPIC_API_KEY 环境变量
)

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "用一句话介绍你自己"}
    ]
)

print(message.content[0].text)

使用环境变量（推荐）

export ANTHROPIC_API_KEY="sk-ant-your-key-here"

# SDK 自动读取 ANTHROPIC_API_KEY 环境变量
client = anthropic.Anthropic()

TypeScript 快速开始

安装 SDK

npm install @anthropic-ai/sdk

第一次调用

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

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

async function main() {
  const message = await client.messages.create({
    model: "claude-sonnet-4-6",
    max_tokens: 1024,
    messages: [
      { role: "user", content: "用一句话介绍你自己" }
    ],
  });

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

main();

理解 API 请求结构

每次调用 Messages API，你需要提供：

必填参数：

• model：选择模型（claude-opus-4-6、claude-sonnet-4-6、claude-haiku-4-5）
• max_tokens：最大输出 token 数
• messages：对话消息数组

常用可选参数：

• system：系统提示词，设定 Claude 的行为规则
• temperature：控制随机性（0-1，默认 1）
• stop_sequences：自定义停止标记

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=2048,
    system="你是一位专业的技术文档编写者，回答简洁准确。",
    temperature=0.3,
    messages=[
        {"role": "user", "content": "解释什么是 REST API"}
    ]
)

理解 API 响应结构

API 返回的响应包含：

# message 对象的关键字段
message.id          # 消息唯一 ID
message.model       # 使用的模型
message.role        # "assistant"
message.content     # 内容数组
message.stop_reason # 停止原因：end_turn / max_tokens / stop_sequence
message.usage       # Token 用量统计

# 获取文本内容
text = message.content[0].text

# 查看 token 用量
print(f"输入: {message.usage.input_tokens} tokens")
print(f"输出: {message.usage.output_tokens} tokens")

stop_reason 含义：

• end_turn：Claude 正常完成回答
• max_tokens：达到 max_tokens 限制，回答被截断
• stop_sequence：遇到你设置的停止标记

Tip: 如果 stop_reason 是 max_tokens，说明回答被截断了。增大 max_tokens 或让 Claude 更简洁。

不用 SDK 的直接调用（cURL）

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

常见错误处理

import anthropic

try:
    message = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=1024,
        messages=[{"role": "user", "content": "Hello"}]
    )
except anthropic.AuthenticationError:
    print("API Key 无效，请检查")
except anthropic.RateLimitError:
    print("请求太频繁，请稍后重试")
except anthropic.APIError as e:
    print(f"API 错误: {e.message}")

实战练习

Tip: 动手写出你的第一个 API 调用。

1. 注册 Anthropic 账号，获取 API Key
2. 用 Python 或 TypeScript 调用 Claude，让它翻译一段文字
3. 尝试修改 system prompt 和 temperature，观察回答的变化
4. 查看响应中的 token 用量，计算一次调用的大概费用

关键要点

Note: 本文核心总结

• API Key 通过 console.anthropic.com 获取，用环境变量管理
• Messages API 的核心参数：model、max_tokens、messages
• Python 和 TypeScript SDK 都支持，用法几乎相同
• 关注 stop_reason 和 usage 来监控调用质量和成本

延伸阅读

• 下一篇：Messages API 深入：多轮对话