Skip to main content
POST
两套 API 不要混用/v1/* 为推理 API(本文档,上游原样透传、无包装);/api/* 为管理 API(查余额/日志等,响应为 {success, message, data})。若看到某处写 /v1/messages 返回 {code, data},以本文档为准。

Authorizations

鉴权支持两种方式,任选其一
string
Anthropic 风格鉴权头访问 API Key 管理页面 获取您的 API Key
string
Bearer Token 鉴权(与 x-api-key 二选一)
string
API 版本号(可选,不传也能正常返回)为便于日后迁移到 Anthropic 官方端点,建议照常带上:示例:2025-10-01

Body

string
默认值:"claude-sonnet-4-6"
必填
模型名称
  • claude-opus-4-8 - Claude Opus 4.8 旗舰模型
  • claude-opus-4-7 - Claude Opus 4.7 旗舰模型
  • claude-opus-4-6 - Claude Opus 4.6 旗舰模型
  • claude-sonnet-4-6 - Claude Sonnet 4.6 平衡版本
  • claude-opus-4-5-20251101 - Claude Opus 4.5 模型
array
必填
消息列表消息数组,模型会基于这些消息生成下一条回复。每条消息包含 rolecontent 两个字段。💡 快速填写(Try it 区域):
  1. 点击 ”+ Add an item” 添加一条消息
  2. role 输入:user(用户消息)或 assistant(AI回复,用于多轮对话)
  3. content 输入:你想说的话
单条用户消息示例:
多轮对话示例:
预填充助手回复:
integer
必填
最大生成 token 数(必填,与 Anthropic 官方一致)生成停止前的最大 token 数量。模型可能会在达到此限制前停止。不同模型有不同的最大值,请参考模型文档。最小值:1
object
Extended thinking 配置开启后响应 content 中可能包含 thinking 块。推荐使用标准模型名 + 本参数,而不是依赖平台侧的 -thinking 模型别名,便于无改代码迁移到官方端点。多轮对话若需回传 thinking 块,必须原样带回 signature,否则上游会拒绝。
string | array
系统提示词系统提示词用于设置Claude的角色、个性、目标和指令。字符串格式:
结构化格式:
number
温度参数,范围 0-1控制输出的随机性:
  • 低值(如0.2):更确定、更保守
  • 高值(如0.8):更随机、更有创意
默认值:1.0
number
核采样参数,范围 0-1使用nucleus sampling。建议使用 temperaturetop_p 其中之一,不要同时使用。默认值:1.0
integer
Top-K采样只从概率最高的K个选项中采样,用于移除”长尾”低概率响应。建议仅在高级用例中使用。
boolean
是否启用流式输出设置为 true 时,使用服务器发送事件(SSE)流式返回响应。默认值:false
array
停止序列自定义文本序列,遇到这些序列时模型将停止生成。最多4个序列。示例:["\n\nHuman:", "\n\nAssistant:"]
object
元数据用于请求的元数据对象。包含:
  • user_id: 用户标识符
array
工具定义工具列表,模型可以调用这些工具来完成任务。函数工具示例:
支持的工具类型:
  • 自定义函数工具
  • 计算机使用工具(computer_20241022)
  • 文本编辑器工具(text_editor_20241022)
  • Bash工具(bash_20241022)
object
工具选择策略控制模型如何使用工具:
  • {"type": "auto"}: 自动决定(默认)
  • {"type": "any"}: 必须使用工具
  • {"type": "tool", "name": "tool_name"}: 使用指定工具

Response

string
唯一消息标识符示例:"msg_013Zva2CMHLNnXjNJJKqJ2EF"
string
对象类型固定为 "message"
string
角色固定为 "assistant"
array
内容块数组contenttype 区分块类型。一次响应可能包含多个块(例如开启 thinking 时是 thinking + text 两块)。text 块:
tool_use 块:
caller 是上游新增字段,官方文档尚未收录,解析时忽略即可。
thinking 块(请求体带 thinking 参数时出现):
多轮对话回传 thinking 块时,必须原样带回 signature,否则上游会拒绝。
不要假设 content[0] 就是文本。 开启 thinking 时 content[0] 可能是 thinking 块。应遍历筛选:
string
处理请求的模型示例:"claude-sonnet-4-6"
string
停止原因可能的值:
  • end_turn: 自然结束
  • max_tokens: 达到最大 token 数
  • stop_sequence: 遇到停止序列
  • tool_use: 调用了工具
string | null
触发的停止序列如果因停止序列而停止,则为该序列内容;否则为 null
object | null
Anthropic 较新字段,常规请求为 null
object
Token 使用统计(非流式完整结构)

使用示例

基础对话

多轮对话

使用系统提示词

流式响应

工具使用

视觉理解

Base64图像

最佳实践

1. 提示词工程

清晰的角色定义:
结构化输出:

2. 错误处理

3. Token优化

4. 预填充响应

流式响应处理

Python流式示例

JavaScript流式示例

平台差异与对接注意

响应无包装

POST /v1/messages 成功时直接返回 Anthropic message 对象,没有 {code, data} 外层。官方 SDK、Claude Code、Cline 等才能 1:1 兼容。

错误格式(与官方唯一实质差异)

相对 Anthropic 官方:顶层缺少 "type": "error"error.type 固定为 apimart_error,而非 invalid_request_error 等语义化类型。 对接建议:不要依赖 error.type 做重试分支,改用 HTTP 状态码 + error.code 报障请提供:error.message 末尾的 request id,以及响应头 x-oneapi-request-id

流式 SSE

请求加 "stream": true。事件序列与官方一致: message_startcontent_block_startpingcontent_block_delta(多次)→ content_block_stopmessage_deltamessage_stop ⚠️ 流式与非流式的 usage 结构不同message_delta.usage 通常只有 4 个 token 字段,没有 cache_creationservice_tierinference_geo。请分开解析或全部设为可选。

未实现接口

POST /v1/messages/count_tokens 未实现,返回 404。官方 SDK 的 client.messages.count_tokens() 会失败。需要预估 token 时请在本地估算,或读取响应中的 usage.input_tokens

必须忽略未知字段

本接口对上游透传,Anthropic 可能随时新增字段(如 stop_detailsinference_geocalleroutput_tokens_details)。请勿开启严格 schema:
  • Go:不要用 DisallowUnknownFields()
  • Pydantic:不要 extra="forbid"
  • TypeScript / Zod:用 .passthrough() 而非 .strict()

模型名建议

-thinking 后缀的同名模型是平台扩展别名。推荐用不带后缀的标准模型名 + 请求体 thinking 参数,便于迁移官方端点。 请求体其它字段与官方一致:modelmessagesmax_tokens(必填)、systemtemperaturetop_ptop_kstop_sequencesstreamtoolstool_choicethinkingmetadata。语义以 Anthropic Messages API 为准。

注意事项

  1. API 密钥安全
    • 使用环境变量存储 API 密钥
    • 不要在代码中硬编码密钥
    • 定期轮换密钥
  2. 速率限制
    • 注意 API 的速率限制
    • 实现重试机制(按 HTTP 状态码)
    • 使用指数退避策略
  3. Token 管理
    • 监控 token 使用量(读 usage
    • 优化提示词长度
    • 使用适当的 max_tokens
    • 开启 thinking 时 output_tokens 已含 thinking,勿重复计费
  4. 模型选择
    • Opus: 复杂任务、需要深度思考
    • Sonnet: 平衡性能和成本
    • Haiku: 快速响应、简单任务
  5. 内容解析
    • 遍历 contenttype == "text",不要写死 content[0].text
    • 模型若返回 Markdown 代码块包裹的 JSON,属模型输出而非接口包装(见下方 FAQ)
  6. 内容过滤
    • 验证用户输入
    • 过滤敏感信息
    • 实现内容审核机制

FAQ

响应里 content 的 text 是 ```json ... ``` 代码块,怎么去掉?

这不是接口结构问题。text 字段装的是模型生成的原始内容:模型判断你想要 JSON,就用 Markdown 代码块包起来了。接口不会也不应该改写模型输出。 想拿到干净的结构化数据,有三种正确做法(推荐程度从高到低):
  1. 用 tools 强制结构化输出——最可靠,input 字段直接就是解析好的对象:
  1. prefill 助手消息,让模型从 { 接着写:
  1. 在 system prompt 里明确要求「只输出 JSON,不要加 Markdown 代码块」。
不推荐用正则去剥 code fence——模型偶尔不加围栏时会解析失败。