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

# Claude 格式

> 创建 Claude 消息，兼容 Anthropic Messages 协议，支持流式和非流式响应

此接口兼容 Anthropic Claude Messages 协议，用于创建对话消息。

## 功能特性

* 支持流式（SSE）和非流式两种响应模式
* 支持多模态内容（文本、图片等）
* 支持工具调用（Tool Use）
* 支持思考/推理模式配置
* 支持缓存控制优化

## 使用场景

适用于需要与 Claude 系列模型进行对话交互的场景，包括：

* 单轮或多轮对话
* 结构化输出（JSON Schema）
* 工具调用与函数执行
* 代码执行与容器复用

## 认证方式

在请求头中携带 `Authorization` 字段，格式为 `Bearer YOUR_API_KEY`。

<Note>
  Claude 格式接口还需要在请求头中指定 `anthropic-version`，例如 `2023-06-01`。
</Note>

## 快速示例

<CodeGroup>
  ```python Python theme={null}
  import requests

  url = "https://api.haitoken.ai/v1/messages"
  headers = {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
      "anthropic-version": "2023-06-01"
  }
  data = {
      "model": "claude-sonnet-4-0",
      "max_tokens": 1024,
      "messages": [
          {"role": "user", "content": "你好，请介绍一下自己"}
      ]
  }

  response = requests.post(url, json=data, headers=headers)
  print(response.json())
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.haitoken.ai/v1/messages', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
      'anthropic-version': '2023-06-01'
    },
    body: JSON.stringify({
      model: 'claude-sonnet-4-0',
      max_tokens: 1024,
      messages: [
        { role: 'user', content: '你好，请介绍一下自己' }
      ]
    })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```curl cURL theme={null}
  curl -X POST 'https://api.haitoken.ai/v1/messages' \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -H 'anthropic-version: 2023-06-01' \
    -d '{
      "model": "claude-sonnet-4-0",
      "max_tokens": 1024,
      "messages": [
        {"role": "user", "content": "你好，请介绍一下自己"}
      ]
    }'
  ```
</CodeGroup>


## OpenAPI

````yaml zh/api-reference/chat/claude/openapi.json POST /v1/messages
openapi: 3.0.1
info:
  title: 默认模块
  description: ''
  version: 1.0.0
servers: []
security: []
tags: []
paths:
  /v1/messages:
    post:
      tags: []
      summary: 创建 Message
      description: 支持流式（SSE）和非流式两种响应模式
      parameters:
        - name: anthropic-version
          in: header
          description: ''
          required: true
          schema:
            type: string
            example: '2023-06-01'
        - name: X-Api-Key
          in: header
          description: ''
          required: true
          schema:
            type: string
            example: YOUR_API_KEY
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClaudeMessageRequest'
              description: ''
            examples: {}
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClaudeMessageResponse'
                description: |-
                  Claude Messages API 非流式响应
                  参考：https://platform.claude.com/docs/en/api/messages/create
          headers: {}
      deprecated: false
      security: []
components:
  schemas:
    ClaudeMessageRequest:
      type: object
      properties:
        max_tokens:
          type: integer
          description: 最大输出 token 数（必填）
        top_p:
          type: number
          description: 核采样，0-1
        top_k:
          type: integer
          description: Top-K 采样
        stop_sequences:
          type: array
          items:
            type: string
          description: 停止序列
        tool_choice:
          type: object
          properties: {}
          description: 工具选择配置，可以是 String 或 ClaudeToolChoice 对象
        cache_control:
          $ref: '#/components/schemas/ClaudeCacheControl'
          description: |-
            顶层缓存控制配置
            自动对请求中最后一个可缓存块应用 cache_control 标记
        inference_geo:
          type: string
          description: |-
            推理地理区域
            指定推理处理的地理区域。如未指定，使用工作区的 default_inference_geo
        output_config:
          $ref: '#/components/schemas/ClaudeOutputConfig'
          description: |-
            输出配置
            配置模型输出的格式选项，如 effort 级别和结构化输出格式
        service_tier:
          type: string
          description: |-
            服务层级
            决定使用优先容量（如可用）还是标准容量
            可选值: "auto" / "standard_only"
        model:
          type: string
          description: 模型名称，如 claude-sonnet-4-0、claude-opus-4-0 等
        messages:
          type: array
          items:
            $ref: '#/components/schemas/ClaudeMessage'
            description: |-
              Claude 消息对象
              content 字段可以是 String 或 List (多模态内容块)
          description: 消息列表
        system:
          type: object
          properties: {}
          description: 系统指令，可以是 String 或 List<ClaudeSystemBlock>
        temperature:
          type: number
          description: 采样温度，0.0-1.0
        stream:
          type: boolean
          description: 是否启用流式输出
        thinking:
          $ref: '#/components/schemas/ClaudeThinkingConfig'
          description: 思考/推理模式配置
        tools:
          type: array
          items:
            $ref: '#/components/schemas/ClaudeTool'
            description: |-
              Claude 工具定义 (Tool / ToolUnion)
              使用 input_schema 而非 OpenAI 的 function.parameters
              参考：https://platform.claude.com/docs/en/api/messages/create
          description: 工具定义列表
        metadata:
          $ref: '#/components/schemas/ClaudeMetadata'
          description: 元数据
        container:
          type: string
          description: 容器标识符，用于跨请求复用容器（代码执行工具）
      required:
        - max_tokens
        - model
        - messages
    ClaudeMessageResponse:
      type: object
      properties:
        stop_reason:
          type: string
          description: >-
            停止原因: end_turn / max_tokens / stop_sequence / tool_use / pause_turn
            / refusal

            message_start 事件中始终输出（即使为 null）
        stop_sequence:
          type: string
          description: |-
            命中的停止序列 (可为 null)
            message_start 事件中始终输出（即使为 null）
        stop_details:
          $ref: '#/components/schemas/ClaudeStopDetails'
          description: |-
            拒绝停止详情
            当模型因安全策略拒绝时返回的结构化信息
        id:
          type: string
          description: 消息 ID (msg_ 前缀)
        type:
          type: string
          description: 对象类型，始终 "message"
        role:
          type: string
          description: 角色，始终 "assistant"
        content:
          type: array
          items:
            $ref: '#/components/schemas/ClaudeContentBlock'
            description: |-
              Claude 响应多态内容块
              使用 Jackson @JsonTypeInfo 按 type 字段区分子类型
          description: 响应内容块列表
        model:
          type: string
          description: 模型名称(实际完成任务的模型名称)
        container:
          $ref: '#/components/schemas/ClaudeContainer'
          description: |-
            容器信息
            代码执行工具的容器标识，用于跨请求复用
        usage:
          $ref: '#/components/schemas/ClaudeUsage'
          description: 用量统计
    ClaudeCacheControl:
      type: object
      properties:
        type:
          type: string
          description: 缓存类型，始终 "ephemeral"
        ttl:
          type: string
          description: |-
            缓存生存时间 (TTL)
            可选值: "5m" (5分钟) 或 "1h" (1小时)
            默认值: "5m"
    ClaudeOutputConfig:
      type: object
      properties:
        effort:
          type: string
          description: |-
            推理努力程度
            可选值: "low" / "medium" / "high" / "xhigh" / "max"
        format:
          $ref: '#/components/schemas/JsonOutputFormat'
          description: |-
            JSON 输出格式配置 (结构化输出)
            用于指定 Claude 输出的 JSON Schema
    ClaudeMessage:
      type: object
      properties:
        role:
          type: string
          description: '消息角色: "user"、"assistant" 或 "system"'
          enum:
            - USER
            - ASSISTANT
            - SYSTEM
        content:
          type: object
          properties: {}
          description: 消息内容，可以是 String 或 List 多态内容块
    ClaudeThinkingConfig:
      type: object
      properties:
        budget_tokens:
          type: integer
          description: 思考预算 token 数 (仅 type="enabled" 时必填)
        type:
          type: string
          description: '思考模式类型: enabled / disabled / adaptive'
        display:
          type: string
          description: >-
            控制思考内容在响应中的显示方式:"summarized" or "omitted"

            当设置为summarized时，思维恢复正常。当设置为omitted时，思想内容被编辑，但返回一个签名以进行多回合连续性。默认为summarized。
    ClaudeTool:
      type: object
      properties:
        input_schema:
          type: array
          items:
            type: array
            items:
              type: array
              items:
                type: object
                properties: {}
          description: JSON Schema 格式的工具输入参数定义
        allowed_callers:
          type: array
          items:
            type: string
          description: >-
            允许的调用者列表

            可选值: "direct" / "code_execution_20250825" /
            "code_execution_20260120"
        cache_control:
          $ref: '#/components/schemas/ClaudeCacheControl'
          description: 缓存控制配置
        defer_loading:
          type: boolean
          description: |-
            是否延迟加载
            设为 true 时，工具不会包含在初始系统提示中，
            仅当通过 tool_search 返回 tool_reference 时才加载
        eager_input_streaming:
          type: boolean
          description: |-
            是否启用急切输入流式传输
            为 true 时，工具输入参数将增量流式传输，类型将动态推断
            为 false 时，即使启用了细粒度工具流式传输，也会缓冲完整 JSON 输出
            为 null（默认）时，使用基于 beta 头的默认行为
        input_examples:
          type: array
          items:
            $ref: '#/components/schemas/MapObject'
          description: |-
            工具输入示例列表
            帮助模型理解工具的使用方式
        name:
          type: string
          description: 工具名称
        description:
          type: string
          description: 工具描述
        type:
          type: string
          description: |-
            工具类型，仅客户端工具需要设置为 "custom"
            服务端工具有各自的类型标识（如 "bash_20250124", "web_search_20250305" 等）
        strict:
          type: boolean
          description: |-
            严格模式
            设为 true 时，保证工具名称和输入的 Schema 验证
    ClaudeMetadata:
      type: object
      properties:
        user_id:
          type: string
          description: ''
    ClaudeStopDetails:
      type: object
      properties:
        type:
          type: string
          description: 对象类型，始终 "refusal"
        category:
          type: string
          description: |-
            触发拒绝的策略类别
            可选值: "cyber" / "bio" / "reasoning_extraction"
            当拒绝不对应命名类别时为 null
        explanation:
          type: string
          description: |-
            拒绝的人类可读解释
            此文本不保证稳定性。当类别没有可用解释时为 null
    ClaudeContentBlock:
      type: object
      properties: {}
    ClaudeContainer:
      type: object
      properties:
        expires_at:
          type: string
          description: 容器过期时间 (ISO 8601 格式)
        id:
          type: string
          description: 容器标识符
    ClaudeUsage:
      type: object
      properties:
        input_tokens:
          type: integer
          description: ''
        output_tokens:
          type: integer
          description: ''
        cache_creation_input_tokens:
          type: integer
          description: ''
        cache_read_input_tokens:
          type: integer
          description: ''
        cache_creation:
          $ref: '#/components/schemas/ClaudeCacheCreation'
          description: 缓存创建明细，按 TTL 分类
        inference_geo:
          type: string
          description: 推理地理区域
        output_tokens_details:
          $ref: '#/components/schemas/ClaudeOutputTokensDetails'
          description: 输出 token 明细，按类别分解（只读，用于可观测性）
        server_tool_use:
          $ref: '#/components/schemas/ClaudeServerToolUsage'
          description: 服务端工具使用统计
        service_tier:
          type: string
          description: |-
            服务层级
            可选值: "standard" / "priority" / "batch"
    JsonOutputFormat:
      type: object
      properties:
        schema:
          type: array
          items:
            type: array
            items:
              type: array
              items:
                type: object
                properties: {}
          description: JSON Schema 定义
        type:
          type: string
          description: 格式类型，始终 "json_schema"
    MapObject:
      type: object
      properties:
        key:
          $ref: '#/components/schemas/key'
    ClaudeCacheCreation:
      type: object
      properties:
        ephemeral_5m_input_tokens:
          type: integer
          description: 创建 5 分钟缓存条目的输入 token 数
        ephemeral_1h_input_tokens:
          type: integer
          description: 创建 1 小时缓存条目的输入 token 数
    ClaudeOutputTokensDetails:
      type: object
      properties:
        thinking_tokens:
          type: integer
          description: |-
            模型作为内部推理生成的输出 token 数
            包括思考块分隔符 token
            始终 ≤ output_tokens；output_tokens - thinking_tokens ≈ 非推理输出
    ClaudeServerToolUsage:
      type: object
      properties:
        web_search_requests:
          type: integer
          description: Web 搜索工具请求次数
        web_fetch_requests:
          type: integer
          description: Web 抓取工具请求次数
    key:
      type: object
      properties: {}

````