Skip to main content
POST
使用 POST /v1/messages 以 Anthropic 消息格式发送 Claude 请求。 这些示例使用 CometAPI 基础 URL 配置官方 Anthropic SDK,并 从 $COMETAPI_KEY 读取您的 API 密钥。
有关字段定义和模型特定选项,请参阅官方 Messages API 参考. 对于 OpenAI 兼容请求,请参阅 聊天补全.
使用 x-api-keyAuthorization: Bearer 进行身份验证。Anthropic SDK 使用 x-api-key。HTTP 示例包含 anthropic-version: 2023-06-01

快速开始

以下示例请求三个搜索查询。请设置 $COMETAPI_KEY 后再 运行这些示例。对于 Python,请安装 anthropic;对于 JavaScript,请安装 @anthropic-ai/sdk
响应包含一个 content 数组。读取 typetext 的块; 思考和工具块可能出现在文本之前。

控制自适应思考

thinking.type 设置为 adaptive,并选择一个 output_config.effort 值。 以下示例使用 xhigh,并从流中读取完成的消息:
思考会占用 max_tokens 输出上限。请为最终 答案和思考预留空间。响应可以包含文本,而不带可见的 思考块。请在对话 历史记录中原样保留任何返回的思考块。 有关特定模型的思考配置,请参阅 思考. 这些示例省略了 temperaturetop_ptop_k;在添加采样控制参数之前,请查阅所选 模型的参数文档。

缓存 Prompt

为在请求之间重复使用的参考资料设置缓存断点。 在运行此示例之前,将参考资料保存为 UTF-8 reference.txt 文件。 使用符合所选模型 最小可缓存长度:
使用相同的模型、参考文本和思考设置再次运行请求。 检查用量计数器,以确定请求是否复用了某个前缀:
  • cache_creation_input_tokens 统计写入缓存的 Token 数。
  • cache_read_input_tokens 统计从缓存读取的 Token 数。
  • input_tokens 统计在这些缓存计数器之外处理的输入。
在重复请求中,cache_read_input_tokens 会报告有多少输入 Token 是从缓存中读取的。OpenAPI Prompt 缓存 示例包含一份完整的虚构参考资料,你可以将其保存为 reference.txt 以试用该示例。

流式传输响应

stream: true 设置为使用 Server-Sent Events。SDK 会在文本片段 到达时将其公开:
消息流包含 message_start、内容块事件、message_delta, 以及 message_stop。内容块可以包含文本、思考或工具活动。 对于文本块,content_block_delta 包含一个 text_delta。读取最终用量 以及来自 message_delta 的停止原因。

控制推理强度

设置 output_config.effort 以引导推理量。本示例使用 low 来获取简短说明,并等待流式消息完成:
使用官方 effort 参考文档 来选择强度级别。单独设置 max_tokens 以限制输出长度。

使用服务器工具

服务器工具会在 API 请求期间执行,并与 Claude 的回答一同返回结果块。
获取一篇论文,并要求 Claude 在回答中使用检索到的文档。 此示例以流式方式返回响应,并检查最终文本和 web_fetch_tool_result 块:
响应会将一个 server_tool_use 块与一个 web_fetch_tool_result 块配对,后者 包含获取的文档或工具错误。

返回客户端工具结果

对于客户端工具,Claude 会返回一个 tool_use 块。运行您的应用函数 并在包含匹配 tool_resulttool_use_id 块中发送其结果。 在两次请求之间保留完整的 assistant 内容。 此示例提供了一个虚构的订单结果,并要求 Claude 使用该结果:

响应示例

非流式请求会返回一个消息对象。以下示例展示了其 text 和 usage 字段,并使用了示例消息标识符:
停止原因描述下一步操作。end_turn 表示回答已完成, max_tokens 表示输出已达到限制,而 tool_use 请求客户端工具 结果。对于返回 pause_turn 的服务器工具轮次,请继续使用 原样返回的 assistant 内容。

授权

x-api-key
string
header
必填

Your CometAPI key passed via the x-api-key header. Authorization: Bearer $COMETAPI_KEY is also supported.

请求头

anthropic-version
string
默认值:2023-06-01

The Anthropic API version to use. Defaults to 2023-06-01.

示例:

"2023-06-01"

anthropic-beta
string

Comma-separated feature identifiers required by a specific beta API feature. Omit this header for the examples on this page.

请求体

application/json
model
string
默认值:claude-opus-5
必填

The Claude model to use. See the Models page for available Claude model IDs.

示例:

"claude-opus-5"

messages
object[]
必填

Conversation history. Use user and assistant messages with text strings or content-block arrays. Return complete assistant content blocks when continuing a tool call.

max_tokens
integer
必填

The maximum number of tokens to generate. The model may stop before reaching this limit. When using thinking, the thinking tokens count towards this limit.

必填范围: x >= 1
示例:

1024

system

System prompt providing context and instructions to Claude. Can be a plain string or an array of content blocks (useful for prompt caching).

temperature
number

Sampling temperature. The examples omit sampling overrides.

必填范围: 0 <= x <= 1
top_p
number

Nucleus sampling threshold. The examples omit sampling overrides.

必填范围: 0 <= x <= 1
top_k
integer

Limits sampling to the k most likely tokens. The examples omit sampling overrides.

必填范围: x >= 0
stream
boolean
默认值:false

If true, stream the response incrementally using Server-Sent Events (SSE). Events include message_start, content_block_start, content_block_delta, content_block_stop, message_delta, and message_stop.

stop_sequences
string[]

Custom strings that cause the model to stop generating when encountered. The stop sequence is not included in the response.

thinking
object

Thinking configuration. The adaptive example uses type adaptive and sets output_config.effort separately.

tools
object[]

Client tools define a name and input_schema. Server tools use a versioned type and name, such as the web_fetch and web_search examples on this page.

tool_choice
object

Controls how the model uses tools.

metadata
object

Request metadata for tracking and analytics.

output_config
object

Configuration for reasoning effort and structured output.

service_tier
enum<string>

The service tier to use. auto tries priority capacity first, standard_only uses only standard capacity.

可用选项:
auto,
standard_only

响应

Successful response. When stream is true, the response is a stream of SSE events.

id
string

Message identifier returned by the API.

type
enum<string>

Always message.

可用选项:
message
role
enum<string>

Always assistant.

可用选项:
assistant
content
object[]

The response content blocks. May include text, thinking, tool_use, and other block types.

model
string

Model ID reported by the response.

stop_reason
enum<string>

Why the model stopped generating. refusal can be returned as a successful HTTP response when the model declines a request.

可用选项:
end_turn,
max_tokens,
stop_sequence,
tool_use,
pause_turn,
refusal
stop_sequence
string | null

The stop sequence that caused the model to stop, if applicable.

usage
object

Token usage statistics.

最后修改于 2026年9月8日