创建消息请求（Claude）

简介

Claude 原生的消息接口，适用于 Claude Code 等原生 Anthropic 客户端。该接口遵循 Anthropic 的 API 规范，提供完整的 Claude 模型功能支持，包括扩展思考（Extended Thinking）、工具调用等高级特性。

如果您使用 OpenAI 兼容的客户端（如 OpenAI SDK），建议使用 /v1/chat/completions 接口。

认证

Authorization

string

必填

Bearer Token，如 Bearer sk-xxxxxxxxxx

请求参数

model

string

必填

Claude 模型标识，支持的模型包括：

claude-opus-4-5-20251101 - Claude Opus 4.5（最新，最强推理能力）
claude-haiku-4-5-20251001 - Claude Haiku 4.5（最新，速度最快）
claude-sonnet-4-5-20250929 - Claude Sonnet 4.5（最新，平衡性能）
claude-opus-4-1-20250805 - Claude Opus 4.1
claude-sonnet-4-20250514 - Claude Sonnet 4
其他 Claude 系列模型

messages

array

必填

对话消息列表，每个元素包含 role（user/assistant）和 content。content 可以是字符串或媒体内容数组。

max_tokens

number

必填

最大生成 token 数，控制回复长度。必须大于 0。

system

string|array

系统提示词，可以是字符串或媒体内容数组。用于设定模型的行为和角色。

temperature

number

默认值:"1.0"

随机性控制，0-1，值越高回复越随机。使用扩展思考时建议设置为 1.0。

top_p

number

默认值:"1.0"

核采样参数，0-1，控制生成的多样性。使用扩展思考时建议设置为 0。

top_k

number

Top-K 采样参数，仅部分模型支持。

stream

boolean

默认值:"false"

是否启用流式输出，返回 SSE 格式的分片数据。使用扩展思考时建议启用。

stop_sequences

array

停止序列列表，当模型生成这些序列时停止生成。

tools

array

工具定义列表，支持函数工具和网页搜索工具。

tool_choice

object

工具选择策略，控制模型如何使用工具。

thinking

object

扩展思考配置，启用 Claude 的深度推理能力。

metadata

object

请求元数据，用于追踪和调试。

mcp_servers

array

MCP（Model Context Protocol）服务器配置。

context_management

object

上下文管理配置，控制对话上下文的处理方式。

Prompt Caching（提示词缓存）

Prompt Caching 允许缓存经常使用的上下文内容，显著降低成本并提升响应速度。支持在 system 和 messages 中使用 cache_control 参数。

缓存控制参数

cache_control

object

缓存控制配置，可用于 system 数组元素和 messages 的 content 数组元素。

type: 缓存类型
- "ephemeral": 5分钟缓存（默认，成本最优）
- "persistent": 1小时缓存（适用于长期稳定的上下文）

缓存机制

缓存位置：最后一个带 cache_control 标记的内容块会被缓存
缓存阈值：内容至少需要 1024 tokens（Claude Sonnet 4.5）或 2048 tokens（Claude 3 Haiku）
缓存时效：
- ephemeral: 5分钟内有效
- persistent: 1小时内有效
成本节省：缓存读取比普通输入便宜 90%

使用场景

长文档分析：将大型文档缓存在 system 中，多次提问
代码库理解：缓存代码上下文，进行多轮代码分析
知识库问答：缓存知识库内容，提供快速查询
多轮对话：缓存历史对话，保持上下文连贯性

基础示例

非流式请求
流式请求（SSE）
Python 示例（Anthropic SDK）

curl -X POST "https://llm.ai-nebula.com/v1/messages" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "claude-sonnet-4-5-20250929",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "请用中文简要介绍人工智能"}
    ]
  }'

curl -N -X POST "https://llm.ai-nebula.com/v1/messages" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "claude-sonnet-4-5-20250929",
    "max_tokens": 1024,
    "stream": true,
    "messages": [
      {"role": "user", "content": "请用中文简要介绍人工智能"}
    ]
  }'

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-xxxxxxxxxx",
    base_url="https://llm.ai-nebula.com"
)

# 非流式
message = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "请用中文简要介绍人工智能"}
    ]
)
print(message.content[0].text)

# 流式
with client.messages.stream(
    model="claude-sonnet-4-5-20250929",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "请用中文简要介绍人工智能"}
    ]
) as stream:
    for text_block in stream.text_stream:
        print(text_block, end="")

{
  "id": "msg_xxx",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "人工智能是研究、开发用于模拟、延伸和扩展人的智能的理论、方法、技术及应用系统的一门新的技术科学..."
    }
  ],
  "model": "claude-sonnet-4-5-20250929",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 25,
    "output_tokens": 100
  }
}

高级功能

系统提示词

系统提示词可以设置为字符串或媒体内容数组：

字符串格式
数组格式

curl -X POST "https://llm.ai-nebula.com/v1/messages" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "claude-sonnet-4-5-20250929",
    "max_tokens": 1024,
    "system": "你是一个有用的助手，擅长用中文回答问题。",
    "messages": [
      {"role": "user", "content": "什么是机器学习？"}
    ]
  }'

curl -X POST "https://llm.ai-nebula.com/v1/messages" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "claude-sonnet-4-5-20250929",
    "max_tokens": 1024,
    "system": [
      {"type": "text", "text": "你是一个有用的助手，擅长用中文回答问题。"}
    ],
    "messages": [
      {"role": "user", "content": "什么是机器学习？"}
    ]
  }'

扩展思考（Extended Thinking）

Claude 支持扩展思考功能，允许模型进行深度推理。启用后，模型会在生成最终答案前进行内部思考。

基础用法
Python 示例

curl -X POST "https://llm.ai-nebula.com/v1/messages" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "claude-sonnet-4-5-20250929",
    "max_tokens": 4096,
    "temperature": 1.0,
    "top_p": 0,
    "stream": true,
    "messages": [
      {"role": "user", "content": "给出一道中等难度的几何题并分步解析"}
    ]
  }'

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-xxxxxxxxxx",
    base_url="https://llm.ai-nebula.com"
)

with client.messages.stream(
    model="claude-sonnet-4-5-20250929",
    max_tokens=4096,
    thinking={
        "type": "enabled",
        "budget_tokens": 4096
    },
    temperature=1.0,
    top_p=0,
    messages=[
        {"role": "user", "content": "给出一道中等难度的几何题并分步解析"}
    ]
) as stream:
    for event in stream:
        if event.type == "content_block_delta":
            if hasattr(event.delta, "thinking"):
                # 思考过程
                print(f"[思考] {event.delta.thinking}", end="")
            elif hasattr(event.delta, "text"):
                # 最终答案
                print(event.delta.text, end="")

budget_tokens 必须大于 1024
使用扩展思考时，建议设置 temperature: 1.0 和 top_p: 0
必须启用流式输出（stream: true）才能看到思考过程

工具调用（Tools）

支持函数工具和网页搜索工具：

函数工具
Claude 官方网页搜索工具
工具调用完整流程

curl -X POST "https://llm.ai-nebula.com/v1/messages" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "claude-sonnet-4-5-20250929",
    "max_tokens": 1024,
    "tools": [
      {
        "name": "get_weather",
        "description": "根据城市获取天气信息",
        "input_schema": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string",
              "description": "城市名称"
            }
          },
          "required": ["city"]
        }
      }
    ],
    "tool_choice": {
      "type": "auto"
    },
    "messages": [
      {"role": "user", "content": "上海的天气怎么样？"}
    ]
  }'

Claude 支持官方的网页搜索工具 web_search_20250305，可以实时搜索网络信息并在响应中包含引用来源。基础用法：

curl -X POST "https://llm.ai-nebula.com/v1/messages" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "claude-sonnet-4-5-20250929",
    "max_tokens": 1024,
    "tools": [
      {
        "type": "web_search_20250305",
        "name": "web_search"
      }
    ],
    "messages": [
      {"role": "user", "content": "最近关于人工智能的新闻有哪些？"}
    ]
  }'

带搜索次数限制：

curl -X POST "https://llm.ai-nebula.com/v1/messages" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "claude-sonnet-4-5-20250929",
    "max_tokens": 1024,
    "tools": [
      {
        "type": "web_search_20250305",
        "name": "web_search",
        "max_uses": 5
      }
    ],
    "messages": [
      {"role": "user", "content": "搜索一下今天北京的天气"}
    ]
  }'

带位置信息（提升搜索准确性）：

curl -X POST "https://llm.ai-nebula.com/v1/messages" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "claude-sonnet-4-5-20250929",
    "max_tokens": 1024,
    "tools": [
      {
        "type": "web_search_20250305",
        "name": "web_search",
        "max_uses": 5,
        "user_location": {
          "type": "approximate",
          "timezone": "Asia/Shanghai",
          "country": "CN",
          "region": "Beijing",
          "city": "Beijing"
        }
      }
    ],
    "messages": [
      {"role": "user", "content": "上海今天的天气怎么样？"}
    ]
  }'

Python 示例：

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-xxxxxxxxxx",
    base_url="https://llm.ai-nebula.com"
)

message = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=1024,
    tools=[
        {
            "type": "web_search_20250305",
            "name": "web_search",
            "max_uses": 5
        }
    ],
    messages=[
        {"role": "user", "content": "最近关于人工智能的新闻有哪些？"}
    ]
)
print(message.content[0].text)

type 必须为 "web_search_20250305"
name 必须为 "web_search"
max_uses（可选）：单次对话中最多使用搜索的次数，建议值：2-10
user_location（可选）：用户位置信息，用于提升搜索结果的本地化准确性
搜索结果会在响应中自动包含引用来源
支持的模型包括 Claude Sonnet 4.5、Claude Opus 4.5、Claude Haiku 4.5 等

第一阶段：模型返回工具调用请求

{
  "id": "msg_xxx",
  "content": [
    {
      "type": "tool_use",
      "id": "toolu_xxx",
      "name": "get_weather",
      "input": {"city": "上海"}
    }
  ],
  "stop_reason": "tool_use"
}

第二阶段：返回工具执行结果

curl -X POST "https://llm.ai-nebula.com/v1/messages" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "claude-sonnet-4-5-20250929",
    "max_tokens": 1024,
    "tools": [...],
    "messages": [
      {"role": "user", "content": "上海的天气怎么样？"},
      {
        "role": "assistant",
        "content": [
          {
            "type": "tool_use",
            "id": "toolu_xxx",
            "name": "get_weather",
            "input": {"city": "上海"}
          }
        ]
      },
      {
        "role": "user",
        "content": [
          {
            "type": "tool_result",
            "tool_use_id": "toolu_xxx",
            "content": "{\"temp\":\"22°C\",\"condition\":\"多云\",\"aqi\":53}"
          }
        ]
      }
    ]
  }'

tool_choice 参数详解

tool_choice 控制模型如何使用工具：

值	说明
`{"type": "auto"}`	自动决定是否使用工具（默认）
`{"type": "any"}`	必须使用至少一个工具
`{"type": "none"}`	不使用任何工具
`{"type": "tool", "name": "tool_name"}`	必须使用指定的工具

示例：

{
  "tool_choice": {
    "type": "auto",
    "disable_parallel_tool_use": false
  }
}

多模态输入（图像）

支持在消息中包含图像：

curl -X POST "https://llm.ai-nebula.com/v1/messages" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "claude-sonnet-4-5-20250929",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "image",
            "source": {
              "type": "base64",
              "media_type": "image/png",
              "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
            }
          },
          {
            "type": "text",
            "text": "这张图片里有什么？"
          }
        ]
      }
    ]
  }'

Prompt Caching（提示词缓存）

通过缓存常用的上下文内容，可以显著降低成本和提升响应速度。

System 缓存（5分钟）
Messages 缓存（1小时）
Python SDK 示例

curl -X POST "https://llm.ai-nebula.com/v1/messages" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "claude-sonnet-4-5-20250929",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "你是一个专业的技术文档分析助手。以下是 AWS Lambda 的完整技术文档：\n\nAWS Lambda 是一项无服务器计算服务...[大量文档内容，至少1024个tokens]",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "messages": [
      {"role": "user", "content": "Lambda 的定价模型是什么？"}
    ]
  }'

首次请求响应：

{
  "usage": {
    "input_tokens": 50,
    "cache_creation_input_tokens": 1200,
    "cache_read_input_tokens": 0,
    "output_tokens": 150
  }
}

5分钟内再次请求（不同问题，相同 system）：

{
  "usage": {
    "input_tokens": 45,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 1200,
    "output_tokens": 100
  }
}

curl -X POST "https://llm.ai-nebula.com/v1/messages" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxx" \
  -d '{
    "model": "claude-sonnet-4-5-20250929",
    "max_tokens": 1024,
    "system": "你是一个 Python 编程助手",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "分析这段代码：\n```python\n[大量代码，至少1024个tokens]\n```",
            "cache_control": {"type": "persistent"}
          }
        ]
      },
      {
        "role": "assistant",
        "content": [
          {
            "type": "text",
            "text": "这段代码的主要功能是...[详细分析]",
            "cache_control": {"type": "persistent"}
          }
        ]
      },
      {
        "role": "user",
        "content": "如何优化这段代码的性能？"
      }
    ]
  }'

使用 persistent 缓存的优势：

1小时缓存时效，适合长时间会话
适用于代码审查、文档分析等场景
缓存命中后，后续请求速度更快

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-xxxxxxxxxx",
    base_url="https://llm.ai-nebula.com"
)

# 首次请求：创建缓存
message1 = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "你是专业的文档分析助手...[长文本内容]",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    messages=[
        {"role": "user", "content": "第一个问题"}
    ]
)

print(f"缓存创建: {message1.usage.cache_creation_input_tokens} tokens")
print(f"缓存读取: {message1.usage.cache_read_input_tokens} tokens")

# 5分钟内再次请求：使用缓存
message2 = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": "你是专业的文档分析助手...[相同的长文本]",
            "cache_control": {"type": "ephemeral"}
        }
    ],
    messages=[
        {"role": "user", "content": "第二个问题"}
    ]
)

print(f"缓存创建: {message2.usage.cache_creation_input_tokens} tokens")
print(f"缓存读取: {message2.usage.cache_read_input_tokens} tokens")

缓存要点：

内容必须 ≥ 1024 tokens（Claude Sonnet 4.5）才会触发缓存
ephemeral 缓存在 5分钟内有效
persistent 缓存在 1小时内有效
缓存读取成本比正常输入便宜 90%
最后一个带 cache_control 的块会被缓存
缓存基于内容完全匹配，任何改动都会导致缓存失效

最佳实践：

将不变的长上下文（文档、代码库等）放在 system 中并启用缓存
对于长期稳定的内容，使用 persistent 缓存（1小时）
对于频繁变化的内容，使用 ephemeral 缓存（5分钟）
多轮对话时，可以缓存历史对话内容
定期监控 cache_creation_input_tokens 和 cache_read_input_tokens 以优化成本

响应格式

非流式响应
流式响应

{
  "id": "msg_xxx",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "回复内容..."
    }
  ],
  "model": "claude-sonnet-4-5-20250929",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 25,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0,
    "output_tokens": 100
  }
}

使用缓存时的 usage 字段：

input_tokens: 当前请求的非缓存输入 tokens
cache_creation_input_tokens: 首次缓存创建的 tokens（仅首次请求时有值）
cache_read_input_tokens: 从缓存读取的 tokens（缓存命中时有值）
output_tokens: 生成的输出 tokens

流式响应以 SSE（Server-Sent Events）格式返回，包含以下事件类型：

message_start: 消息开始
content_block_start: 内容块开始
content_block_delta: 内容增量（包含 text 或 thinking）
content_block_stop: 内容块结束
message_delta: 消息增量（包含 usage 信息）
message_stop: 消息结束

event: message_start
data: {"type":"message_start","message":{"id":"msg_xxx","type":"message","role":"assistant","content":[],"model":"claude-sonnet-4-5-20250929","stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":25,"output_tokens":0}}}

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"回"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"复"}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{"output_tokens":100}}

event: message_stop
data: {"type":"message_stop"}

使用扩展思考时，content_block_delta 可能包含 thinking 字段：

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"thinking_delta","thinking":"让我思考一下这个问题..."}}

错误处理

系统会对上游 Claude API 的错误进行统一处理，返回标准化的错误响应格式。

错误类型	HTTP 状态码	说明
`invalid_request`	400	请求参数错误（如缺少必填字段）
`authentication_error`	401	API 密钥无效或未授权
`rate_limit_error`	429	请求频率超限
`upstream_error`	500	上游服务错误
`nebula_api_error`	500	系统内部错误

错误响应示例：

{
  "error": {
    "type": "invalid_request",
    "message": "field messages is required"
  }
}

与 /v1/chat/completions 的对比

特性	/v1/messages	/v1/chat/completions
认证方式	`Authorization: Bearer`	`Authorization: Bearer`
响应格式	Anthropic 原生格式	OpenAI 兼容格式
扩展思考	原生支持 `thinking` 参数	通过 `reasoning_effort` 或 `reasoning` 参数
工具调用	原生 `tools` 和 `tool_choice`	OpenAI 兼容格式
适用客户端	Anthropic SDK、Claude Code	OpenAI SDK、兼容客户端

如果您使用 Claude Code 或其他 Anthropic 原生客户端，建议使用 /v1/messages 接口
如果您使用 OpenAI SDK 或需要兼容 OpenAI 格式，建议使用 /v1/chat/completions 接口
两个接口的功能基本相同，主要区别在于请求/响应格式

注意事项

max_tokens 是必填参数，必须大于 0
messages 数组不能为空
使用扩展思考时，budget_tokens 必须大于 1024
扩展思考需要启用流式输出才能看到思考过程
工具调用需要多轮交互，第一轮返回工具调用请求，第二轮返回工具执行结果
图像输入需要使用 base64 编码

使用流式输出可以提升首字响应时间和交互体验
工具调用需要做好超时与重试机制，避免阻塞模型响应
扩展思考功能可以显著提升复杂问题的推理质量

对话接口（OpenAI 兼容）

查看 OpenAI 兼容的对话接口文档

模型列表

查看所有支持的模型信息

API 文档

文本系列

图像系列

视频系列

实时语音

简介

认证

请求参数

Prompt Caching（提示词缓存）

缓存控制参数

缓存机制

使用场景

基础示例

高级功能

系统提示词

扩展思考（Extended Thinking）

工具调用（Tools）

tool_choice 参数详解

多模态输入（图像）

Prompt Caching（提示词缓存）

响应格式

错误处理

与 /v1/chat/completions 的对比

注意事项

相关资源

对话接口（OpenAI 兼容）

模型列表

API 文档

文本系列

图像系列

视频系列

实时语音

​简介

​认证

​请求参数

​Prompt Caching（提示词缓存）

​缓存控制参数

​缓存机制

​使用场景

​基础示例

​高级功能

​系统提示词

​扩展思考（Extended Thinking）

​工具调用（Tools）

​tool_choice 参数详解

​多模态输入（图像）

​Prompt Caching（提示词缓存）

​响应格式

​错误处理

​与 /v1/chat/completions 的对比

​注意事项

​相关资源

对话接口（OpenAI 兼容）

模型列表

简介

认证

请求参数

Prompt Caching（提示词缓存）

缓存控制参数

缓存机制

使用场景

基础示例

高级功能

系统提示词

扩展思考（Extended Thinking）

工具调用（Tools）

tool_choice 参数详解

多模态输入（图像）

Prompt Caching（提示词缓存）

响应格式

错误处理

与 /v1/chat/completions 的对比

注意事项

相关资源