创建消息

授权

X-Api-Key

string

header

默认值:sk-ant-local-default

必填

OMA 工作区 API 密钥。

请求头

anthropic-beta

string

用于指定要使用的 beta 版本的可选请求头。

要使用多个 beta，请使用逗号分隔的列表（如 beta1,beta2），或为每个 beta 分别指定该请求头。

anthropic-version

string

你想使用的 OMA API 版本。

在此处阅读更多关于版本控制和我们版本历史的信息。

anthropic-user-profile-id

string

用于归属此请求的用户资料 ID。在代表你的组织以外的当事方行事时使用。需要 user-profiles Beta 请求头。

查询参数

beta

enum<boolean>

必填

为此接口启用 Beta API 合同，必须为 true。

可用选项:

true

请求体

application/json

model

必填

将完成你的提示的模型。

更多详情和选项请参阅模型列表。

messages

InputMessage · object[]

必填

输入消息。

我们的模型经过训练，会在交替的 user 和 assistant 对话轮次上进行工作。创建新的 Message 时，你通过 messages 参数指定先前的对话轮次，模型随后会生成对话中的下一个 Message。请求中连续的 user 或 assistant 轮次会被合并为一个轮次。

每条输入消息都必须是一个包含 role 和 content 的对象。你可以指定一条 user 角色的消息，也可以包含多条 user 和 assistant 消息。

如果最后一条消息使用 assistant 角色，响应内容将从该消息的内容直接继续。这可用于约束模型响应的部分内容。

单条 user 消息示例：

[{"role": "user", "content": "Hello, the model"}]

多个对话轮次示例：

[
  {"role": "user", "content": "Hello there."},
  {"role": "assistant", "content": "Hi, I'm the model. How can I help you?"},
  {"role": "user", "content": "Can you explain LLMs in plain English?"},
]

模型部分填写的响应示例：

[
  {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"},
  {"role": "assistant", "content": "The best answer is ("},
]

每条输入消息的 content 可以是单个 string，也可以是内容块数组，其中每个块都有特定的 type。对 content 使用 string 是包含一个 "text" 类型内容块的数组的简写形式。以下输入消息是等价的：

{"role": "user", "content": "Hello, the model"}

{"role": "user", "content": [{"type": "text", "text": "Hello, the model"}]}

参见输入示例。

请注意，如果你想包含系统提示词，可以使用顶层的 system 参数——消息 API 的输入消息中没有 "system" 角色。

单个请求最多允许 100,000 条消息。

Show child attributes

max_tokens

integer

必填

停止前最多生成的令牌数。

请注意，模型可能在达到该上限_之前_停止。此参数只指定要生成的令牌的绝对上限。

设为 0 可在不生成响应的情况下填充提示缓存。

不同模型的此参数最大值不同。请参阅模型列表。

必填范围: x >= 0

示例:

1024

cache_control

CacheControlEphemeral · object | null

顶层缓存控制会自动将 cache_control 标记应用于请求中最后一个可缓存的块。

Show child attributes

container

包含要加载的技能的容器参数。

Show child attributes

context_management

ContextManagementConfig · object | null

上下文管理配置。

它允许你控制模型如何在多个请求之间管理上下文，例如是否清除函数结果。

Show child attributes

diagnostics

DiagnosticsParam · object | null

请求级诊断信息。提供 previous_message_id 后，响应将包含 diagnostics.cache_miss_reason，说明提示缓存与该先前请求之间的任何差异。

Show child attributes

fallback_credit_token

来自先前拒绝的 stop_details 中的 fallback_credit_token。

当前序请求被拒绝并返回了 fallback_credit_token 时，在重试中通过此处传入该代码，使重试中针对被拒绝模型上已预热前缀的缓存创建令牌按缓存读取费率计费。必须由相同的组织和工作区使用相同的请求正文兑换（可选地追加一条 assistant 消息进行扩展，其内容为部分文本——最终 text 块末尾的空白已被去除——以及拒绝前流式输出的配对 server-tool 块；设置了 output_format 或强制 tool_choice 的请求不能使用追加助手的形式），在符合条件的 fallback 模型上、在相同的 platform 上、且在拒绝发生 5 分钟内完成；不匹配则为 400。在 server-tool 循环中途签发且其部分内容可续写的令牌，只能以追加助手的形式兑换——如果完全同正文的重试被 400 拒绝并提示必须通过继续部分响应来兑换该令牌，则改用追加助手的形式重试。

当在通常禁止助手回合 prefill 的模型上使用追加助手的形式时，该令牌还会授权该次 prefill。

Required string length: 1 - 2048

fallbacks

可选启用的服务端重试：当所请求的模型出于策略原因拒绝时，改用一个或多个替代模型重试。按顺序尝试：如果第一个条目也被拒绝，则尝试第二个，依此类推。字符串 "default" 表示请求使用所请求模型的服务端定义的默认回退配置。

Required array length: 1 - 3 elements

Show child attributes

inference_geo

string | null

指定推理处理所使用的地理区域。未指定时，使用工作区的 default_inference_geo。

mcp_servers

RequestMCPServerURLDefinition · object[]

本次请求中要使用的 MCP 服务器

Maximum array length: 20

Show child attributes

metadata

Metadata · object

描述请求元数据的对象。

Show child attributes

output_config

OutputConfig · object

模型输出的配置选项，例如输出格式。

Show child attributes

output_format

JsonOutputFormat · object | null

已弃用

已弃用：请改用 output_config.format。参见结构化输出。

用于指定模型响应的输出格式架构。该参数将在未来版本中移除。

Show child attributes

service_tier

enum<string>

决定该请求使用优先容量（如可用）还是标准容量。

OMA 为你的 API 请求提供不同级别的服务。详见 service-tiers。

可用选项:

auto,

standard_only

speed

enum<string> | null

此请求的推理速度模式。"fast" 启用每秒高输出令牌数的推理。

可用选项:

standard,

fast

stop_sequences

string[]

会使模型停止生成的自定义文本序列。

我们的模型通常会在自然完成回合时停止，此时响应的 stop_reason 为 "end_turn"。

如果你希望模型在遇到自定义文本序列时停止生成，可以使用 stop_sequences 参数。如果模型遇到其中一个自定义序列，响应的 stop_reason 值将为 "stop_sequence"，响应的 stop_sequence 值将包含匹配到的停止序列。

stream

boolean

是否使用服务器发送事件增量流式返回响应。

详情请参阅 streaming。

示例:

false

system

系统提示词。

系统提示词用于向模型提供上下文和指令，例如指定特定的目标或角色。请参阅我们的系统提示词指南。

示例:

[
  {
    "text": "Today's date is 2024-06-01.",
    "type": "text"
  }
]

temperature

number

已弃用

注入到响应中的随机程度。

默认为 1.0。取值范围为 0.0 到 1.0。分析 / 多选类任务建议使用更接近 0.0 的 temperature，创意和生成类任务建议使用更接近 1.0 的值。

请注意，即使 temperature 为 0.0，结果也不会完全确定。

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

示例:

1

thinking

ThinkingConfigEnabled · object

用于启用模型扩展思考的配置。

启用后，响应中会包含 thinking 内容块，展示模型在给出最终答案之前的思考过程。至少需要 1,024 个令牌的预算，并计入你的 max_tokens 限制。

详见扩展思考。

ThinkingConfigEnabled
ThinkingConfigDisabled
ThinkingConfigAdaptive

Show child attributes

示例:

{ "type": "adaptive" }

tool_choice

ToolChoiceAuto · object

模型将自动决定是否使用工具。

ToolChoiceAuto
ToolChoiceAny
ToolChoiceTool
ToolChoiceNone

Show child attributes

tools

模型可以使用的工具的定义。

如果你在 API 请求中包含 tools，模型可能会返回表示模型使用这些工具的 tool_use 内容块。你可以使用模型生成的工具输入来运行这些工具，然后可以选择通过 tool_result 内容块将结果返回给模型。

工具有两种类型：客户端工具和服务器工具。下面描述的行为适用于客户端工具。服务器工具请参见各自的文档，因为每种工具都有自己的行为（例如 web 搜索工具）。

每个工具定义包含：

name：工具的名称。
description：可选但强烈建议提供的工具描述。
input_schema：模型将在 tool_use 输出内容块中生成的工具 input 结构的 JSON 架构。

例如，如果你将 tools 定义为：

[
  {
    "name": "get_stock_price",
    "description": "Get the current stock price for a given ticker symbol.",
    "input_schema": {
      "type": "object",
      "properties": {
        "ticker": {
          "type": "string",
          "description": "The stock ticker symbol, e.g. AAPL for Apple Inc."
        }
      },
      "required": ["ticker"]
    }
  }
]

然后询问模型 "What's the S&P 500 at today?"，模型可能会在响应中生成如下 tool_use 内容块：

[
  {
    "type": "tool_use",
    "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV",
    "name": "get_stock_price",
    "input": { "ticker": "^GSPC" }
  }
]

随后你可以使用 {"ticker": "^GSPC"} 作为输入来运行你的 get_stock_price 工具，并在后续的 user 消息中将以下内容返回给模型：

[
  {
    "type": "tool_result",
    "tool_use_id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV",
    "content": "259.75 USD"
  }
]

工具可用于包含运行客户端工具和函数的工作流，或者更普遍地说，每当你希望模型生成特定 JSON 结构的输出时都可以使用。

Show child attributes

示例:

{
  "description": "获取给定位置的当前天气",
  "input_schema": {
    "properties": {
      "location": {
        "description": "城市与州，例如 San Francisco, CA",
        "type": "string"
      },
      "unit": {
        "description": "输出的单位 - (celsius, fahrenheit) 之一",
        "type": "string"
      }
    },
    "required": ["location"],
    "type": "object"
  },
  "name": "get_weather"
}

top_k

integer

已弃用

对每个后续令牌仅从概率最高的 K 个选项中采样。

用于消除"长尾"低概率响应。在此了解更多技术细节。

仅建议高级用例使用。

必填范围: x >= 0

示例:

5

top_p

number

已弃用

使用核采样。

在核采样中，我们按概率从高到低对每个后续令牌的所有选项计算累积分布，并在达到由 top_p 指定的特定概率时截断。

仅建议高级用例使用。

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

示例:

0.7

响应

消息对象。

string

必填

唯一的对象标识符。

ID 的格式和长度可能会随时间变化。

示例:

"msg_013Zva2CMHLNnXjNJJKqJ2EF"

type

string

默认值:message

必填

对象类型。

对于消息，此值始终为 "message"。

Allowed value: "message"

role

string

默认值:assistant

必填

所生成消息的对话角色。

该值始终为 "assistant"。

Allowed value: "assistant"

content

必填

模型生成的内容。

这是一个内容块数组，每个块都有一个决定其结构的 type。

示例：

[{"type": "text", "text": "Hi, I'm the model."}]

如果请求输入的 messages 以一个 assistant 回合结尾，则响应的 content 会直接从最后一个回合继续。你可以利用这一点来约束模型的输出。

例如，如果输入的 messages 为：

[
  {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"},
  {"role": "assistant", "content": "The best answer is ("}
]

那么响应的 content 可能为：

[{"type": "text", "text": "B)"}]

ResponseTextBlock
ResponseThinkingBlock
ResponseRedactedThinkingBlock
ResponseToolUseBlock
ResponseServerToolUseBlock
ResponseWebSearchToolResultBlock
ResponseWebFetchToolResultBlock
ResponseAdvisorToolResultBlock
ResponseCodeExecutionToolResultBlock
ResponseBashCodeExecutionToolResultBlock
ResponseTextEditorCodeExecutionToolResultBlock
ResponseToolSearchToolResultBlock
ResponseMCPToolUseBlock
ResponseMCPToolResultBlock
ResponseContainerUploadBlock
ResponseCompactionBlock
ResponseFallbackBlock

Show child attributes

示例:

[
  {
    "citations": null,
    "text": "你好！我是你的智能助手。",
    "type": "text"
  }
]

model

必填

将完成你的提示的模型。

更多详情和选项请参阅模型列表。

stop_reason

enum<string> | null

必填

停止的原因。

这可能是以下值之一：

"end_turn"：模型到达了自然停止点
"max_tokens"：超出了请求的 max_tokens 或模型的最大值
"stop_sequence"：生成了你提供的某个自定义 stop_sequences
"tool_use"：模型调用了一个或多个工具
"pause_turn"：我们暂停了一个长时间运行的回合。你可以在后续请求中原样提供该响应，让模型继续。
"refusal"：流式分类器介入以处理潜在的违反政策行为时
"model_context_window_exceeded"：超出了模型的上下文窗口

在非流式模式下，该值始终非 null。在流式模式下，它在 message_start 事件中为 null，其他情况下非 null。

可用选项:

end_turn,

max_tokens,

stop_sequence,

tool_use,

pause_turn,

compaction,

refusal,

model_context_window_exceeded

stop_sequence

string | null

必填

若有自定义停止序列被生成，指明是哪一个。

如果生成了你的某个自定义停止序列，该值将为非 null 字符串。

stop_details

RefusalStopDetails · object | null

必填

关于模型输出为何停止的结构化信息。

当 stop_reason 没有更多细节可报告时，该值为 null。

Show child attributes

usage

Usage · object

必填

计费与速率限制用量。

OMA API 按令牌数量计费和限速，因为令牌代表了系统的底层成本。

在底层，API 会将请求转换为适合模型的格式。模型的输出随后会经过解析阶段，再成为 API 响应。因此，usage 中的令牌数与 API 请求或响应的可见内容不会一一对应。

例如，即使模型的响应是空字符串，output_tokens 也不会为零。

请求的输入令牌总数是 input_tokens、cache_creation_input_tokens 与 cache_read_input_tokens 之和。

Show child attributes

示例:

{
  "input_tokens": 2095,
  "output_tokens": 503
}

diagnostics

Diagnostics · object | null

必填

请求级诊断信息。仅当请求中提供了 diagnostics 时才会返回；未检测到提示缓存差异时为 null。

Show child attributes

context_management

ResponseContextManagement · object | null

必填

上下文管理响应。

关于请求期间所应用的上下文管理策略的信息。

Show child attributes

container

Container · object | null

必填

本次请求中所用容器的信息。

如果使用了容器工具（例如代码执行），则该字段非 null。

Show child attributes

开始使用

核心 API

托管智能体

Webhook

授权

请求头

查询参数

请求体

响应