> ## Documentation Index
> Fetch the complete documentation index at: https://docs.inb.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# 创建 Claude 消息

> 以 Anthropic Claude Messages 原生格式创建消息响应，支持工具调用与扩展思考

## 可填写的模型

| 模型 ID                        | 说明                     |
| ---------------------------- | ---------------------- |
| `claude-3-opus-20240229`     | Claude 3 旗舰，顶级推理与理解能力  |
| `claude-3-5-sonnet-20241022` | Claude 3.5 Sonnet，均衡性能 |
| `claude-3-5-haiku-20241022`  | Claude 3.5 Haiku，快速轻量  |

完整列表见 [`GET /v1/models`](/zh/api-reference/models/list-models)。

## 版本头

每次请求必须携带 `anthropic-version: 2023-06-01`（或更新版本）。

## 系统提示

`system` 字段可以是纯文本字符串，也可以是包含缓存控制块的对象数组，
用于精细控制提示缓存行为。

## 工具调用

在 `tools` 中定义函数，使用 JSON Schema 描述 `input_schema`。
模型会在 `content` 中返回 `tool_use` 类型的块；
将工具执行结果以 `tool_result` 类型回填到下一轮请求中。

## 扩展思考（Extended Thinking）

设置 `thinking.type: enabled` 并指定 `thinking.budget_tokens`
可启用扩展思考模式，模型会在响应中返回 `thinking` 类型的内容块。

## 流式输出

设置 `stream: true` 后，响应以 Server-Sent Events 形式返回，
事件类型包括 `message_start`、`content_block_delta`、`message_stop` 等。


## OpenAPI

````yaml /openapi/chat.zh.yaml post /v1/messages
openapi: 3.1.0
info:
  title: InfinityBlue API — 聊天（Chat）
  version: 1.0.0
  summary: 统一的 AI 模型 API 网关 — 聊天接口
  description: |
    InfinityBlue 是一个统一的 AI 模型 API 网关，以 **OpenAI、Google Gemini、
    Anthropic Claude 等原生格式** 对外提供兼容接口，背后聚合了 OpenAI、
    Google、DeepSeek、字节豆包（Seedance）、快手可灵（Kling）等厂商的模型。

    你无需为每家厂商单独接入——只要把 base URL 指向 InfinityBlue，
    沿用你熟悉的官方 SDK 即可调用全部模型。

    ## 认证

    所有请求都需要在请求头中携带 API Key：

    ```
    Authorization: Bearer YOUR_API_KEY
    ```

    在 [控制台](https://api.getinfinityblue.com/console) 创建和管理你的 API Key。

    ## 接口格式约定

    | 路径前缀 | 兼容格式 |
    | --- | --- |
    | `/v1/*` | OpenAI（Chat Completions、Responses、Images 等） |
    | `/v1/messages` | Anthropic Claude Messages |
    | `/v1beta/models/*` | Google Gemini 原生 |

    ## 模型选择

    在 `model` 参数中传入任意模型 ID 即可。完整可用列表见
    [`GET /v1/models`](/zh/api-reference/models/list-models)
    或 [模型价格页](https://api.getinfinityblue.com/pricing)。
  contact:
    name: InfinityBlue
    url: https://getinfinityblue.com
servers:
  - url: https://api.getinfinityblue.com
    description: 生产环境
security:
  - bearerAuth: []
tags:
  - name: 聊天（Chat）
    description: |
      文本对话、视觉理解、工具调用、流式输出与推理模型，
      通过统一的对话接口提供。
paths:
  /v1/messages:
    post:
      tags:
        - 聊天（Chat）
      summary: 创建 Claude 消息
      description: |
        使用 Anthropic Claude Messages API 原生格式创建消息响应。
        需要在请求头中携带 `anthropic-version`。
        同时支持通过 `Authorization: Bearer` 或 `x-api-key` 传递凭证。
      operationId: createClaudeMessage
      parameters:
        - name: anthropic-version
          in: header
          description: Anthropic API 版本号，当前推荐值为 `2023-06-01`。
          required: true
          schema:
            type: string
            examples:
              - '2023-06-01'
        - name: x-api-key
          in: header
          description: |
            Anthropic API Key（可选）。也可使用标准的
            `Authorization: Bearer YOUR_KEY` 头，二者任选其一。
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClaudeMessageRequest'
            examples:
              simple:
                summary: 基础文本对话
                value:
                  model: claude-3-opus-20240229
                  max_tokens: 1024
                  messages:
                    - role: user
                      content: 用一句话介绍你自己。
              with_system:
                summary: 携带系统提示
                value:
                  model: claude-3-opus-20240229
                  max_tokens: 2048
                  system: 你是一个专业的技术文档写作助手，回答请使用中文。
                  messages:
                    - role: user
                      content: 帮我写一段关于 REST API 设计原则的简介。
              tool_calling:
                summary: 工具调用
                value:
                  model: claude-3-opus-20240229
                  max_tokens: 1024
                  tools:
                    - name: get_weather
                      description: 查询指定城市的当前天气
                      input_schema:
                        type: object
                        properties:
                          city:
                            type: string
                            description: 城市名称
                        required:
                          - city
                  messages:
                    - role: user
                      content: 北京现在天气怎么样？
              extended_thinking:
                summary: 扩展思考模式
                value:
                  model: claude-3-opus-20240229
                  max_tokens: 16000
                  thinking:
                    type: enabled
                    budget_tokens: 10000
                  messages:
                    - role: user
                      content: 分析量子计算对现代密码学的潜在影响。
              streaming:
                summary: 流式输出
                value:
                  model: claude-3-opus-20240229
                  max_tokens: 1024
                  stream: true
                  messages:
                    - role: user
                      content: 写一首关于深海的短诗。
      responses:
        '200':
          description: 成功创建消息
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClaudeMessageResponse'
            text/event-stream:
              schema:
                type: string
                description: |
                  当 `stream=true` 时返回 Server-Sent Events 流。
                  事件类型包括 `message_start`、`content_block_start`、
                  `content_block_delta`、`content_block_stop`、`message_delta`、
                  `message_stop`。
        '400':
          description: 请求参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: API Key 无效或缺失
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: 请求频率超限
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: 服务器内部错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ClaudeMessageRequest:
      type: object
      required:
        - model
        - messages
        - max_tokens
      description: Anthropic Claude Messages API 请求体。
      properties:
        model:
          type: string
          description: 模型 ID，例如 `claude-3-opus-20240229`。完整列表见 `GET /v1/models`。
          examples:
            - claude-3-opus-20240229
        messages:
          type: array
          description: 对话消息列表，`role` 必须在 `user` 和 `assistant` 之间交替。
          items:
            $ref: '#/components/schemas/ClaudeMessage'
        system:
          description: |
            系统提示，可以是纯文本字符串，也可以是包含缓存控制块的对象数组。
          oneOf:
            - type: string
            - type: array
              items:
                type: object
        max_tokens:
          type: integer
          minimum: 1
          description: 模型在本次响应中可生成的最大 token 数，必须指定。
        temperature:
          type: number
          minimum: 0
          maximum: 1
          description: 采样温度，取值 0–1，控制输出随机性。
        top_p:
          type: number
          description: 核采样概率阈值，与 `temperature` 二选一调整。
        top_k:
          type: integer
          description: Top-K 采样参数，仅考虑概率最高的 K 个 token。
        stream:
          type: boolean
          description: 是否以 Server-Sent Events 流式返回。
        stop_sequences:
          type: array
          description: 停止序列列表，模型生成到其中任一序列时停止。
          items:
            type: string
        tools:
          type: array
          description: 模型可调用的工具列表，每个工具需提供 `name`、`description` 和 `input_schema`。
          items:
            type: object
            properties:
              name:
                type: string
                description: 工具名称。
              description:
                type: string
                description: 工具功能描述，帮助模型判断何时调用。
              input_schema:
                type: object
                description: JSON Schema 格式的输入参数定义。
        tool_choice:
          description: |
            工具调用策略。`auto` 由模型自行决定，`any` 强制至少调用一个工具，
            `tool` 强制调用指定工具（需同时提供 `name`）。
          oneOf:
            - type: object
              properties:
                type:
                  type: string
                  enum:
                    - auto
                    - any
                    - tool
                  description: 策略类型。
                name:
                  type: string
                  description: 当 `type=tool` 时，指定要调用的工具名称。
        thinking:
          type: object
          description: 扩展思考（Extended Thinking）配置，仅对支持该功能的模型生效。
          properties:
            type:
              type: string
              enum:
                - enabled
                - disabled
              description: 是否启用扩展思考。
            budget_tokens:
              type: integer
              description: |
                思考过程允许消耗的最大 token 预算。必须大于 0，
                建议至少设置为 1000 以获得有效的思考输出。
        metadata:
          type: object
          description: 请求附加元数据。
          properties:
            user_id:
              type: string
              description: 代表终端用户的唯一标识，可用于滥用监测。
    ClaudeMessageResponse:
      type: object
      description: Anthropic Claude Messages API 响应体。
      properties:
        id:
          type: string
          description: 本次消息的唯一标识。
        type:
          type: string
          description: 对象类型，值为 `message`。
          examples:
            - message
        role:
          type: string
          description: 响应角色，值为 `assistant`。
          examples:
            - assistant
        content:
          type: array
          description: 响应内容块列表，可包含文本、工具调用或思考块。
          items:
            type: object
            properties:
              type:
                type: string
                description: 内容块类型，例如 `text`、`tool_use`、`thinking`。
              text:
                type: string
                description: 文本内容，`type=text` 时存在。
        model:
          type: string
          description: 实际处理请求的模型。
        stop_reason:
          type: string
          enum:
            - end_turn
            - max_tokens
            - stop_sequence
            - tool_use
          description: 生成结束原因。
        usage:
          type: object
          description: Token 用量统计。
          properties:
            input_tokens:
              type: integer
              description: 输入消耗的 token 数。
            output_tokens:
              type: integer
              description: 输出消耗的 token 数。
            cache_creation_input_tokens:
              type: integer
              description: 写入缓存的 token 数（提示缓存功能）。
            cache_read_input_tokens:
              type: integer
              description: 从缓存读取的 token 数（提示缓存功能）。
    ErrorResponse:
      type: object
      description: 标准错误响应。
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              description: 错误信息。
              examples:
                - 无效的时长。支持的范围为 4 到 15 秒。
            type:
              type: string
              description: 错误类型。
              examples:
                - invalid_request_error
            param:
              type:
                - string
                - 'null'
              description: 相关参数。
              examples:
                - seconds
            code:
              type:
                - string
                - 'null'
              description: 错误代码。
              examples:
                - invalid_duration
    ClaudeMessage:
      type: object
      required:
        - role
        - content
      description: Claude 对话消息。
      properties:
        role:
          type: string
          enum:
            - user
            - assistant
          description: 消息角色，必须在 `user` 和 `assistant` 之间交替。
        content:
          description: |
            消息内容，可以是纯文本字符串，或包含多种类型内容块的数组
            （文本、图片、工具调用、工具结果等）。
          oneOf:
            - type: string
            - type: array
              items:
                type: object
                properties:
                  type:
                    type: string
                    enum:
                      - text
                      - image
                      - tool_use
                      - tool_result
                    description: 内容块类型。
                  text:
                    type: string
                    description: 文本内容，`type=text` 时使用。
                  source:
                    type: object
                    description: 图片来源，`type=image` 时使用。
                    properties:
                      type:
                        type: string
                        enum:
                          - base64
                          - url
                        description: 来源类型。
                      media_type:
                        type: string
                        description: >-
                          图片 MIME 类型，例如
                          `image/jpeg`、`image/png`、`image/webp`、`image/gif`。
                      data:
                        type: string
                        description: Base64 编码的图片数据，`type=base64` 时使用。
                      url:
                        type: string
                        description: 图片 URL，`type=url` 时使用。
                  id:
                    type: string
                    description: 工具调用 ID，`type=tool_use` 时使用。
                  name:
                    type: string
                    description: 工具名称，`type=tool_use` 时使用。
                  input:
                    type: object
                    description: 工具输入参数，`type=tool_use` 时使用。
                  tool_use_id:
                    type: string
                    description: 关联的工具调用 ID，`type=tool_result` 时使用。
                  content:
                    type: string
                    description: 工具执行结果，`type=tool_result` 时使用。
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: |
        使用 Bearer Token 认证，格式：`Authorization: Bearer sk-xxxxxx`。
        在 [控制台](https://api.getinfinityblue.com/console) 获取 API Key。

````