当前位置： 首页 > news >正文

032_API参考文档

news 2025/7/16 7:54:01

032_API参考文档

概述

本文档提供Claude API的完整技术参考，包括所有端点、参数、响应格式、错误代码等详细规范。

基础信息

API 基础URL

https://api.anthropic.com

版本控制

当前API版本：2023-06-01

认证方式

所有API请求都需要在Header中包含API密钥：

x-api-key: your-api-key-here
anthropic-version: 2023-06-01
content-type: application/json

Messages API

端点

POST /v1/messages

请求参数

必需参数
参数类型描述
modelstring要使用的模型名称
max_tokensinteger生成的最大token数量
messagesarray对话消息数组
可选参数
参数类型默认值描述
systemstringnull系统提示，定义AI的行为
temperaturenumber1.0控制输出随机性 (0.0-1.0)
top_pnumbernull核采样参数 (0.0-1.0)
top_kintegernull限制每步考虑的token数
stop_sequencesarraynull停止生成的序列
streambooleanfalse是否启用流式响应
toolsarraynull可用工具列表
tool_choiceobjectnull工具选择策略

消息格式

基本消息结构
{"role": "user|assistant|system","content": "文本内容"
}
多模态消息结构
{"role": "user","content": [{"type": "text","text": "请分析这张图片"},{"type": "image","source": {"type": "base64","media_type": "image/jpeg","data": "base64编码的图片数据"}}]
}

工具使用

工具定义格式
{"name": "function_name","description": "函数功能描述","input_schema": {"type": "object","properties": {"parameter_name": {"type": "string","description": "参数描述"}},"required": ["parameter_name"]}
}
工具选择策略
{"type": "auto|any|tool","name": "specific_tool_name"  // 当type为"tool"时必需
}

完整请求示例

基础文本对话
{"model": "claude-3-5-sonnet-20241022","max_tokens": 1000,"temperature": 0.7,"system": "你是一个有用的AI助手。","messages": [{"role": "user","content": "你好，请介绍一下自己。"}]
}
多模态输入
{"model": "claude-3-5-sonnet-20241022","max_tokens": 1000,"messages": [{"role": "user","content": [{"type": "text","text": "这张图片显示了什么？"},{"type": "image","source": {"type": "base64","media_type": "image/jpeg","data": "/9j/4AAQSkZJRgABAQEAYABgAAD..."}}]}]
}
工具使用示例
{"model": "claude-3-5-sonnet-20241022","max_tokens": 1000,"tools": [{"name": "get_weather","description": "获取指定城市的天气信息","input_schema": {"type": "object","properties": {"city": {"type": "string","description": "城市名称"},"unit": {"type": "string","enum": ["celsius", "fahrenheit"],"description": "温度单位"}},"required": ["city"]}}],"tool_choice": {"type": "auto"},"messages": [{"role": "user","content": "北京今天天气怎么样？"}]
}

响应格式

标准响应
{"id": "msg_01ABC123","type": "message","role": "assistant","content": [{"type": "text","text": "你好！我是Claude，一个由Anthropic开发的AI助手..."}],"model": "claude-3-5-sonnet-20241022","stop_reason": "end_turn","stop_sequence": null,"usage": {"input_tokens": 12,"output_tokens": 25}
}
工具调用响应
{"id": "msg_01ABC123","type": "message","role": "assistant","content": [{"type": "text","text": "我来为您查询北京的天气信息。"},{"type": "tool_use","id": "toolu_01234567","name": "get_weather","input": {"city": "北京","unit": "celsius"}}],"model": "claude-3-5-sonnet-20241022","stop_reason": "tool_use","usage": {"input_tokens": 100,"output_tokens": 50}
}
工具结果处理
{"role": "user","content": [{"type": "tool_result","tool_use_id": "toolu_01234567","content": "北京今天晴朗，温度25°C，湿度60%"}]
}

流式响应

开启流式响应
{"model": "claude-3-5-sonnet-20241022","max_tokens": 1000,"stream": true,"messages": [{"role": "user","content": "写一篇关于AI的文章"}]
}
流式响应事件类型
message_start
{"type": "message_start","message": {"id": "msg_01ABC123","type": "message","role": "assistant","content": [],"model": "claude-3-5-sonnet-20241022","stop_reason": null,"stop_sequence": null,"usage": {"input_tokens": 25,"output_tokens": 0}}
}
content_block_start
{"type": "content_block_start","index": 0,"content_block": {"type": "text","text": ""}
}
content_block_delta
{"type": "content_block_delta","index": 0,"delta": {"type": "text_delta","text": "人工智能"}
}
content_block_stop
{"type": "content_block_stop","index": 0
}
message_delta
{"type": "message_delta","delta": {"stop_reason": "end_turn","stop_sequence": null},"usage": {"output_tokens": 150}
}
message_stop
{"type": "message_stop"
}

模型列表

可用模型

模型名称描述上下文窗口输入价格/1K tokens输出价格/1K tokens
claude-3-5-sonnet-20241022最新Sonnet模型，平衡性能和成本200,000$0.003$0.015
claude-3-opus-20240229最强性能模型200,000$0.015$0.075
claude-3-haiku-20240307最快速模型200,000$0.00025$0.00125

模型选择指南

model_selection_guide = {"claude-3-5-sonnet-20241022": {"best_for": ["通用对话和问答","代码生成和分析", "内容创作","数据分析","复杂推理任务"],"characteristics": ["平衡的性能和成本","快速响应","高质量输出"]},"claude-3-opus-20240229": {"best_for": ["最复杂的推理任务","创意写作和文学分析","高级数学和科学问题","复杂的代码项目","深度分析和研究"],"characteristics": ["最高的智能水平","卓越的推理能力","高成本，适合重要任务"]},"claude-3-haiku-20240307": {"best_for": ["简单的问答","文本分类和标注","基础的内容生成","快速原型开发","大量简单任务"],"characteristics": ["极快的响应速度","最低的成本","适合简单任务"]}
}

错误处理

HTTP状态码

状态码错误类型描述
400invalid_request_error请求格式错误或参数无效
401authentication_errorAPI密钥无效或缺失
403permission_errorAPI密钥权限不足
404not_found_error请求的资源不存在
429rate_limit_error请求频率超过限制
500api_error服务器内部错误
529overloaded_error服务器过载

错误响应格式

{"type": "error","error": {"type": "rate_limit_error","message": "您的请求频率过高，请稍后重试"}
}

常见错误及解决方案

认证错误 (401)
{"type": "error","error": {"type": "authentication_error","message": "无效的API密钥"}
}

解决方案:

  • 检查API密钥是否正确
  • 确认Header格式：x-api-key: your-api-key
  • 验证API密钥是否仍然有效
速率限制错误 (429)
{"type": "error","error": {"type": "rate_limit_error","message": "请求频率过高"}
}

解决方案:

  • 实现指数退避重试
  • 降低请求频率
  • 升级账户获得更高限额
请求参数错误 (400)
{"type": "error","error": {"type": "invalid_request_error","message": "max_tokens必须是正整数"}
}

解决方案:

  • 检查所有必需参数
  • 验证参数类型和取值范围
  • 查看详细错误信息

错误处理最佳实践

import time
import random
from anthropic import (Anthropic, APIError, RateLimitError, APIConnectionError,AuthenticationError
)class RobustClaudeClient:def __init__(self, api_key: str):self.client = Anthropic(api_key=api_key)self.max_retries = 3self.base_delay = 1.0def create_message_with_retry(self, **kwargs):"""带重试的消息创建"""last_exception = Nonefor attempt in range(self.max_retries):try:return self.client.messages.create(**kwargs)except RateLimitError as e:last_exception = eif attempt == self.max_retries - 1:raise# 指数退避 + 随机抖动delay = self.base_delay * (2 ** attempt) + random.uniform(0, 1)print(f"速率限制，等待 {delay:.2f} 秒后重试...")time.sleep(delay)except APIConnectionError as e:last_exception = eif attempt == self.max_retries - 1:raisedelay = self.base_delay * (attempt + 1)print(f"连接错误，等待 {delay:.2f} 秒后重试...")time.sleep(delay)except AuthenticationError as e:# 认证错误不重试print(f"认证错误: {e}")raiseexcept APIError as e:# 其他API错误print(f"API错误: {e}")if attempt == self.max_retries - 1:raisetime.sleep(self.base_delay)# 如果所有重试都失败raise last_exception

速率限制

限制规则

账户类型请求/分钟tokens/分钟并发请求
免费层6060,0005
付费层级11,0001,000,00050
付费层级25,0005,000,000100
企业版自定义自定义自定义

速率限制Headers

响应中包含以下Header：

anthropic-ratelimit-requests-limit: 1000
anthropic-ratelimit-requests-remaining: 999
anthropic-ratelimit-requests-reset: 2024-01-01T00:01:00Z
anthropic-ratelimit-tokens-limit: 1000000
anthropic-ratelimit-tokens-remaining: 999500
anthropic-ratelimit-tokens-reset: 2024-01-01T00:01:00Z

速率限制处理

def check_rate_limits(response_headers):"""检查速率限制状态"""requests_remaining = int(response_headers.get('anthropic-ratelimit-requests-remaining', 0))tokens_remaining = int(response_headers.get('anthropic-ratelimit-tokens-remaining', 0))if requests_remaining < 10:print("警告：请求次数接近限制")if tokens_remaining < 10000:print("警告：token数量接近限制")return {'requests_remaining': requests_remaining,'tokens_remaining': tokens_remaining,'should_throttle': requests_remaining < 10 or tokens_remaining < 10000}

使用限制

内容长度限制

限制项最大值
单次请求总tokens200,000
系统提示长度无硬性限制，建议<10,000字符
单条消息长度无硬性限制，受总token限制
图片大小最大5MB
图片格式JPEG, PNG, GIF, WebP

支持的媒体类型

supported_media_types = {"image/jpeg": {"max_size": "5MB", "description": "JPEG图片"},"image/png": {"max_size": "5MB", "description": "PNG图片"},"image/gif": {"max_size": "5MB", "description": "GIF图片"},"image/webp": {"max_size": "5MB", "description": "WebP图片"}
}

并发限制

  • 免费账户：最多5个并发请求
  • 付费账户：最多50-100个并发请求
  • 企业账户：可自定义并发限制

请求追踪

请求ID

每个API响应都包含唯一的请求ID：

request-id: req_01ABC123DEF456

使用请求ID进行调试

def make_traced_request(client, **kwargs):"""发送可追踪的请求"""try:response = client.messages.create(**kwargs)request_id = response.response.headers.get('request-id')print(f"请求成功，ID: {request_id}")return responseexcept Exception as e:# 从异常中获取请求ID（如果可用）request_id = getattr(e, 'request_id', 'unknown')print(f"请求失败，ID: {request_id}, 错误: {e}")raise

完整示例

生产级API客户端

import anthropic
import logging
import time
from typing import Optional, Dict, Any
from dataclasses import dataclass@dataclass
class APIResponse:content: strusage: Dict[str, int]request_id: strmodel: strsuccess: boolerror: Optional[str] = Noneclass ProductionClaudeClient:def __init__(self, api_key: str, log_level=logging.INFO):self.client = anthropic.Anthropic(api_key=api_key)self.logger = self._setup_logging(log_level)# 配置self.max_retries = 3self.base_delay = 1.0self.timeout = 60.0# 统计self.stats = {'total_requests': 0,'successful_requests': 0,'failed_requests': 0,'total_tokens': 0,'total_cost': 0.0}def _setup_logging(self, level) -> logging.Logger:"""设置日志"""logger = logging.getLogger('claude_client')logger.setLevel(level)if not logger.handlers:handler = logging.StreamHandler()formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')handler.setFormatter(formatter)logger.addHandler(handler)return loggerdef create_message(self,messages: list,model: str = "claude-3-5-sonnet-20241022",max_tokens: int = 1000,**kwargs) -> APIResponse:"""创建消息（生产级）"""self.stats['total_requests'] += 1request_params = {'model': model,'max_tokens': max_tokens,'messages': messages,**kwargs}self.logger.info(f"发送请求 - 模型: {model}, 消息数: {len(messages)}")start_time = time.time()try:response = self._execute_with_retry(request_params)duration = time.time() - start_timerequest_id = response.response.headers.get('request-id', 'unknown')# 更新统计self.stats['successful_requests'] += 1self.stats['total_tokens'] += response.usage.input_tokens + response.usage.output_tokensself.logger.info(f"请求成功 - ID: {request_id}, "f"用时: {duration:.2f}s, "f"tokens: {response.usage.input_tokens + response.usage.output_tokens}")return APIResponse(content=response.content[0].text,usage={'input_tokens': response.usage.input_tokens,'output_tokens': response.usage.output_tokens,'total_tokens': response.usage.input_tokens + response.usage.output_tokens},request_id=request_id,model=model,success=True)except Exception as e:self.stats['failed_requests'] += 1error_msg = str(e)self.logger.error(f"请求失败: {error_msg}")return APIResponse(content="",usage={'input_tokens': 0, 'output_tokens': 0, 'total_tokens': 0},request_id="",model=model,success=False,error=error_msg)def _execute_with_retry(self, params: Dict[str, Any]):"""带重试的执行"""last_exception = Nonefor attempt in range(self.max_retries):try:return self.client.messages.create(**params)except anthropic.RateLimitError as e:last_exception = eif attempt == self.max_retries - 1:raisedelay = self.base_delay * (2 ** attempt)self.logger.warning(f"速率限制，重试 {attempt + 1}/{self.max_retries}，等待 {delay}s")time.sleep(delay)except anthropic.APIConnectionError as e:last_exception = eif attempt == self.max_retries - 1:raisedelay = self.base_delay * (attempt + 1)self.logger.warning(f"连接错误，重试 {attempt + 1}/{self.max_retries}，等待 {delay}s")time.sleep(delay)except Exception as e:# 其他错误直接抛出raiseraise last_exceptiondef get_stats(self) -> Dict[str, Any]:"""获取使用统计"""success_rate = (self.stats['successful_requests'] / self.stats['total_requests']if self.stats['total_requests'] > 0 else 0)return {**self.stats,'success_rate': success_rate}# 使用示例
if __name__ == "__main__":client = ProductionClaudeClient("your-api-key")response = client.create_message(messages=[{"role": "user", "content": "你好，Claude！"}])if response.success:print(f"回复: {response.content}")print(f"Token使用: {response.usage}")else:print(f"请求失败: {response.error}")# 查看统计信息print(f"使用统计: {client.get_stats()}")

这个API参考文档提供了完整的技术规范和最佳实践，帮助开发者高效、可靠地使用Claude API。

http://www.lryc.cn/news/588969.html

相关文章：

  • 前端面试专栏-工程化：25.项目亮点与技术难点梳理
  • 区块链的三种共识机制——PoW、PoS和DPoS原理
  • 数据库第二次作业
  • 【Python练习】044. 编写一个函数，实现快速排序算法
  • 本地电脑安装Dify|内网穿透到公网
  • 开源AI应用开发平台Dify系列（一）
  • YOLO融合CFFormer中的FeatureCorrection_s2c模块
  • 多租户SaaS系统中设计安全便捷的跨租户流程共享
  • 遥感数据与作物生长模型同化及在作物长势监测与估产中的应用
  • 弗兰肯斯坦式的人工智能与GTM策略的崩溃
  • 运维效率提升利器：grep、sed、awk详解与实战练习指南
  • (LeetCode 面试经典 150 题) 383. 赎金信 （哈希表）
  • AR眼镜：重塑医学教育，开启智能教学新时代
  • 配置使用SSH与VScode进行连接
  • dockerfile 最佳实践
  • 如何解决服务器频繁重启的问题？
  • 流媒体直播分发服务器
  • 基于深度学习的LSTM、GRU对大数据交通流量分析与预测的研究
  • Python初学者笔记第十二期 -- （集合与字典编程练习题）
  • 信息学奥赛一本通 1552：【例 1】点的距离
  • 短剧小程序的「技术革命」：从「粗放生长」到「精准运营」
  • MySQL中的“引擎“是什么意思
  • 【算法-BFS 解决最短路问题】探索BFS在图论中的应用：最短路径问题的高效解法
  • UnitTest测试框架的基本使用方法（详细介绍）
  • Ubuntu24 辅助系统-屏幕键盘的back按键在网页文本框删除不正常的问题解决方法
  • 博客项目 laravel vue mysql 第六章 文章功能
  • WPF中的ListBox详解
  • QTableView鼠标双击先触发单击信号
  • 3. ArrayList与LinkedList的区别
  • Redis的下载安装+基础操作+redis客户端的安装