model 选择此入口发布的模型,客户端沿用同一套 Messages 数据结构。
本文介绍 Messages API 的申请、调用和响应处理方式。
GPT-6.1 Terra
使用model: "gpt-6.1-terra" 可通过此接口调用该模型。请求仍使用 Messages 格式的 messages 和 max_tokens,返回的文本与用量也遵循本接口结构。切换型号时请核对当前价格及账号可用性;单独报告的缓存读取和创建 token 分别结算。
申请流程
要使用 Claude Messages API,首先到 Ace Data Cloud 控制台 获取您的 API Token,留作备用。
如果你尚未登录或注册,会自动跳转到登录页面邀请你注册和登录,完成后会自动返回当前页面。
一个 API Token 即可调用平台所有服务,无需为每个服务单独申请。 首次申请会赠送免费额度,可免费体验;额度不足时可在 控制台 充值通用余额。
📘 完整文档:Claude Messages API →
基本使用
Claude Messages API 的请求路径为/v1/messages,与 Anthropic 官方 API 保持一致。平台接受的兼容模型请求按该模型的输入、输出及缓存用量计费;Messages 的输入 token 不包含单独报告的缓存读取和创建 token,这些维度分别结算。费用以控制台当前模型价格和响应 usage.cost 为准。
我们至少需要提供三个必填参数:
model:填写本接口模型清单中的完整模型 ID。切换模型时继续使用 Messages 的请求字段和响应结构;模型清单、上下文上限和价格见对应模型的 API 与定价页面。messages:输入的消息数组,每条消息包含role(角色)和content(内容),其中role支持user和assistant。max_tokens:最大输出 token 数,用于限制单次回复的长度。
system:系统提示词,用于设定模型的行为和角色。temperature:生成随机性,0-1 之间,值越大回复越发散。stream:是否使用流式响应,设为true可实现逐字返回效果。stop_sequences:自定义停止序列,模型遇到这些文本时会停止生成。top_p:核采样参数,与 temperature 配合控制生成的随机性。top_k:仅从概率最高的 K 个选项中采样。tools:工具定义,用于让模型调用外部函数。tool_choice:控制模型如何使用提供的工具。cache_control:在请求的最后一个可缓存内容块处自动创建缓存断点;也可写在具体内容块上。
tools[].input_schema、tool_choice、tool_use 和 tool_result;tool_choice.disable_parallel_tool_use: true 禁止同轮并行工具调用。思考控制使用 thinking 与 output_config.effort,结构化输出使用 output_config.format。max_tokens 是本次输出预算,不会被平台自动提高;思考与正文共同占用该预算。
这些字段按所选协议传递或映射到对应的生成参数。参数取值和功能限制以接口及模型说明为准;处理参数错误时,请读取具体错误字段和原因。
cURL 示例
结构化输出
使用output_config.format 指定 JSON Schema,响应仍采用 Messages 的 content 内容块:
Python 示例
id:本次消息的唯一标识符。type:始终为message。role:始终为assistant。content:回复内容数组,每个元素包含type(如text)和对应的内容。model:处理请求的模型名称。stop_reason:停止原因。稳定取值包括end_turn、max_tokens、stop_sequence、tool_use、pause_turn(可把当前 assistant 内容原样回传以继续)、refusal和model_context_window_exceeded。stop_sequence:如果因自定义停止序列而停止,显示匹配的停止序列文本。stop_details:当stop_reason为refusal时,可能包含拒绝类别和说明。usage:token 使用统计。input_tokens是未缓存输入;cache_creation_input_tokens和cache_read_input_tokens分别是缓存写入与读取;output_tokens是全部输出 token 数。若返回output_tokens_details.thinking_tokens,该值是output_tokens的子集,计算总量或费用时不要再次相加。该明细没有权威计数时可能为null或省略。usage.cache_creation:可选的缓存写入 TTL 明细,包含ephemeral_5m_input_tokens与ephemeral_1h_input_tokens。对象存在时,两项之和等于cache_creation_input_tokens;字段为null或省略表示当前响应没有可用的 TTL 拆分,不能按0解读。usage.cost:非流式响应可能包含 Ace Data Cloud 记录的额度消耗对象,其中amount是本次实际消耗、currency是计量单位,list_amount是折扣前金额(如有)。Fable 5.1 的官方缓存读取基价为 $0.25/百万 Token,5 分钟与 1 小时缓存写入基价分别为 $12.50 和 $20/百万 Token;平台实际价格按套餐折扣换算。
系统提示词
Claude Messages API 支持通过system 字段设定系统提示词,用于定义模型的行为、角色和上下文。
Python 示例
system 提示词,可以精确地控制 Claude 的角色和行为方式。
流式响应
该接口也支持流式响应,将stream 参数设为 true 即可获得逐步返回的效果,非常适合在网页中实现逐字显示。
Python 示例
event: 和 data: 为前缀。流式事件类型包括:
message_start:消息开始,包含消息的基本信息和模型名称。content_block_start:内容块开始。content_block_delta:内容块增量更新,包含新生成的文本片段。content_block_stop:内容块结束。message_delta:消息级别的增量更新,包含stop_reason和最终的usage信息。output_tokens_details.thinking_tokens的权威值只应从最后一个message_delta.usage读取,不要跨事件累加。message_stop:消息结束。
content_block_delta 事件包含了逐步生成的文本内容,通过拼接所有 text_delta 即可获得完整回复。
JavaScript 示例
多轮对话
如果您想要对接多轮对话功能,需要在messages 数组中交替排列 user 和 assistant 角色的消息,将之前的对话历史一并传入。
Python 示例
messages 中传递完整的对话历史,Claude 可以结合上下文进行准确的回答。
深度思考模型
Claude 的 thinking 与 thinking summary 是两个不同概念:模型可以进行内部推理,但 API 不会返回原始思维链。需要展示推理过程时,API 返回的是经过处理的摘要。 当前模型建议使用 adaptive thinking,并通过output_config.effort 控制总体推理投入:
display: "summarized"返回可读的思考摘要;它不是原始思维链。display: "omitted"返回thinking: "",但仍保留 opaquesignature以支持后续对话。display: "updates"是 Anthropic 的 beta 模式,需携带anthropic-beta: thinking-display-updates-2026-08-18。官方定义是隐藏推理正文、显示工具调用之间的简短进度更新。平台按原值传递该参数和 beta 请求头,不会强制改写为summarized;实际输出内容取决于所选模型的支持情况。- Messages 请求统一使用
thinking、output_config和采样参数;同协议传递原始字段,跨协议按字段语义映射。平台不按型号编写参数例外;所选模型返回的具体参数错误会传回客户端。 - Fable 5.1、Fable 5、Opus 5、Sonnet 5、Opus 4.8 和 Opus 4.7 的 display 默认值为
omitted;Opus 4.6、Sonnet 4.6 及更早支持 thinking 的模型默认使用summarized。 - Display 只影响返回内容和流式延迟,不关闭推理,也不减少 thinking token 的计费。
- 是否默认启用 thinking 与 display 默认值是两个独立问题。Opus 5、Sonnet 5 默认启用 adaptive thinking;对 Opus 5,省略
thinking等同于 adaptive,省略output_config.effort等同于high。Opus 4.8、4.7 和 4.6 需要显式启用。 - Thinking 与最终正文共同占用
max_tokens输出预算。预算过小时,thinking 可能占用大部分额度,使正文为空或被截断;请提高max_tokens,或使用low/mediumeffort 控制推理投入。 - 对允许关闭 thinking 的模型,可传
thinking: {"type":"disabled"}。between_tools等新增模式以及 effort 组合取决于所选模型;平台不依据旧的型号规则提前拒绝。 - 固定思考预算可通过
budget_tokens传递;新模型通常使用thinking.type=adaptive和output_config.effort。是否支持固定预算或关闭思考,以所选模型的当前能力为准。 - 多轮对话和工具调用时,应将 assistant 返回的完整 thinking 块及 signature 原样传回;不要修改或自行生成 signature。
- 参数透传不代表每个模型都支持所有功能。跨协议调用仍需转换,
redacted_thinking等内容的支持范围和错误由实际处理请求的模型服务决定。
summarized 会产生 thinking_delta;omitted 不产生 thinking_delta,只保留 thinking 块生命周期和 signature_delta。
视觉模型
Claude 支持多模态输入,可以同时处理文本和图像。在 Messages API 中,通过将content 设为数组格式,并传入图像内容块即可使用视觉能力。
使用 Base64 编码图像
使用 URL 图像
cURL 示例
image/jpeg、image/png、image/gif、image/webp。
文档与 PDF
PDF 使用document 内容块,支持 Base64 与 URL 两种稳定来源。Base64 来源必须使用 application/pdf:
{"type":"url","url":"https://example.com/report.pdf"}。document 还支持 text/plain 与由 text/image 块组成的 content 来源;可选字段包括 title、context 和 citations。Files API 的 file_id 来源属于独立 beta 功能,不在本接口的稳定契约内。
提示缓存
顶层cache_control 会自动把缓存断点放在最后一个可缓存块上:
cache_control 写在 text、image、document、tool_use、tool_result 内容块或工具定义上。ttl 支持 5m(默认)与 1h;请通过 usage.cache_creation_input_tokens 和 usage.cache_read_input_tokens 判断缓存写入与命中。
当响应提供 usage.cache_creation 时,ephemeral_5m_input_tokens + ephemeral_1h_input_tokens = cache_creation_input_tokens。若 cache_creation 为 null 或省略,表示只有缓存写入总量、没有权威 TTL 拆分;此时不要将任一 bucket 当作已知的 0,计费和总量仍以 aggregate 字段为准。
返回结果示例:
工具调用(Tool Use)
Claude Messages API 原生支持工具调用功能,允许模型在需要时调用您预定义的工具/函数。Python 示例
content 会包含 tool_use 类型的内容块:
stop_reason 为 tool_use,表示模型需要调用工具。收到该结果后,您需要执行工具函数并将结果以 tool_result 的形式回传给模型:
与 Chat Completion API 的区别
Ace Data Cloud 同时提供两种 Claude API 格式,两者的主要区别如下: Messages API 的usage.input_tokens 仅表示未缓存输入,cache_read_input_tokens 与 cache_creation_input_tokens 是独立计费分桶;三者会分别按对应价格计算。
如果您的系统已经对接了 OpenAI 格式的 API,可以使用 Chat Completion API 来无缝切换。如果您需要使用 Claude 的全部原生能力,建议使用 Messages API。
错误处理
公开接口的错误响应使用 Ace Data Cloud 平台 envelope:error.code 是稳定错误码,error.message 是说明,trace_id 用于排查请求。常见 HTTP 状态包括:
400:请求参数或协议内容无效。401:授权令牌无效、缺失或过期。403:禁止访问、余额不足或配额受限。404:API 或模型不存在。413:请求体过大。429:请求过多。500/503/504:服务错误、暂时不可用或处理超时。
错误响应示例
error.code 处理。

