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

# Kimi 全模型接口 - Messages 完整参数

> 对外路径 POST /v1/messages。思考档位放在 output_config.effort；顶层 cache_control 控制 5m/1h 写入（仅 K3.1 系列）。完整保留 thinking、signature、tool_use 和服务端搜索结果块。

> [!NOTE]
>
> **BaseURL 说明**：默认 BaseURL 为 `https://direct.evolink.ai`，对文本模型支持更好，支持长连接；`https://api.evolink.ai` 是多模态主力地址，对文本模型作为备用地址使用。


## OpenAPI

````yaml cn/api-manual/language-series/kimi/messages/messages-reference.json POST /v1/messages
openapi: 3.1.0
info:
  title: Kimi 全模型接口 - Messages 完整参数
  description: >-
    通过 Anthropic Messages 协议调用 Kimi 系列文本模型，用 `model` 参数选择
    `kimi-k3.1-pro`、`kimi-k3.1-pro-highspeed` 或 `kimi-k3`。上下文窗口均为 1,048,576
    tokens，支持多轮对话、流式输出、工具调用、联网搜索和图片输入。


    三个模型始终开启思考，通过 `output_config.effort` 调节强度。结构化输出、停用词和缓存写入时长仅 K3.1 系列支持，见
    `model` 字段说明。多轮对话时请原样回传完整 assistant 内容块，包括 thinking、signature 与 tool_use。
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://direct.evolink.ai
    description: 生产环境（推荐）
  - url: https://api.evolink.ai
    description: 备用地址
security:
  - bearerAuth: []
tags:
  - name: Messages
    description: Anthropic Messages 兼容接口
paths:
  /v1/messages:
    post:
      tags:
        - Messages
      summary: Kimi Messages 接口（全模型，Anthropic 兼容）
      description: >-
        对外路径 POST /v1/messages。思考档位放在 output_config.effort；顶层 cache_control 控制
        5m/1h 写入（仅 K3.1 系列）。完整保留 thinking、signature、tool_use 和服务端搜索结果块。
      operationId: createMessageKimi
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMessageRequest'
            examples:
              simple:
                summary: Pro 最小请求
                value:
                  model: kimi-k3.1-pro
                  max_tokens: 1024
                  output_config:
                    effort: low
                  messages:
                    - role: user
                      content: Reply with OK.
              highspeed:
                summary: Highspeed 最小请求
                value:
                  model: kimi-k3.1-pro-highspeed
                  max_tokens: 1024
                  output_config:
                    effort: low
                  messages:
                    - role: user
                      content: Reply with OK.
              k3:
                summary: Kimi K3 最小请求
                value:
                  model: kimi-k3
                  max_tokens: 1024
                  messages:
                    - role: user
                      content: Reply with OK.
              system_prompt:
                summary: system 提示词
                value:
                  model: kimi-k3.1-pro
                  max_tokens: 2048
                  output_config:
                    effort: low
                  system: 你是一名严谨的中文技术编辑。
                  messages:
                    - role: user
                      content: 解释什么是上下文缓存。
              streaming:
                summary: Anthropic SSE 流式输出
                value:
                  model: kimi-k3.1-pro
                  max_tokens: 1024
                  output_config:
                    effort: low
                  messages:
                    - role: user
                      content: Reply with OK.
                  stream: true
              multimodal:
                summary: 图片输入
                value:
                  model: kimi-k3.1-pro
                  max_tokens: 1024
                  output_config:
                    effort: low
                  messages:
                    - role: user
                      content:
                        - type: image
                          source:
                            type: base64
                            media_type: image/jpeg
                            data: /9j/4AAQSkZJRgABAQAA...
                        - type: text
                          text: 请描述这张图片。
              tool_use:
                summary: 工具调用
                value:
                  model: kimi-k3.1-pro
                  max_tokens: 2048
                  output_config:
                    effort: low
                  messages:
                    - role: user
                      content: 查询北京今天的天气。
                  tools:
                    - name: get_weather
                      description: 查询指定城市的天气
                      input_schema:
                        type: object
                        properties:
                          city:
                            type: string
                            description: 城市名称
                        required:
                          - city
                  tool_choice:
                    type: auto
              web_search:
                summary: 服务端联网搜索
                value:
                  model: kimi-k3.1-pro
                  max_tokens: 1024
                  output_config:
                    effort: low
                  messages:
                    - role: user
                      content: Use web search to find the official Kimi homepage URL.
                  tools:
                    - type: web_search_20250305
                      name: web_search
                      max_uses: 1
              structured_output:
                summary: 严格结构化输出（仅 K3.1 系列）
                value:
                  model: kimi-k3.1-pro
                  max_tokens: 1024
                  output_config:
                    effort: low
                    format:
                      type: json_schema
                      schema:
                        type: object
                        properties:
                          result:
                            type: string
                        required:
                          - result
                        additionalProperties: false
                  messages:
                    - role: user
                      content: Return a JSON object with result equal to OK.
              cache_1h:
                summary: 顶层 1h 缓存（仅 K3.1 系列）
                value:
                  model: kimi-k3.1-pro
                  max_tokens: 1024
                  output_config:
                    effort: low
                  messages:
                    - role: user
                      content: Reply with OK.
                  cache_control:
                    type: ephemeral
                    ttl: 1h
      responses:
        '200':
          description: Message 响应；流式请求返回 Anthropic SSE 事件流
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
            text/event-stream:
              schema:
                type: string
                description: >-
                  事件顺序通常为
                  message_start、content_block_*、message_delta、message_stop。
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    CreateMessageRequest:
      type: object
      required:
        - model
        - max_tokens
        - messages
      properties:
        model:
          type: string
          enum:
            - kimi-k3.1-pro
            - kimi-k3.1-pro-highspeed
            - kimi-k3
          default: kimi-k3.1-pro
          description: >-
            要调用的模型：


            | 模型 ID | 定位 | 思考强度 |

            |---|---|---|

            | `kimi-k3.1-pro` | 最新一代模型（推荐） | `low` / `high` / `max`，默认 `max` |

            | `kimi-k3.1-pro-highspeed` | 与 Pro 参数相同，生成速度更快 | 同 `kimi-k3.1-pro`
            |

            | `kimi-k3` | 上一代模型 | 仅支持 `max` |


            三个模型的上下文窗口均为 1,048,576 tokens，均始终开启思考。


            结构化输出（`output_config.format`）、停用词（`stop_sequences`）和缓存写入时长（`cache_control`）仅
            K3.1 系列支持，`kimi-k3` 不支持。`kimi-k3` 的响应可能只包含 `text` 块，不返回 `thinking`
            块。
        max_tokens:
          type: integer
          minimum: 1
          description: 本次生成允许使用的最大 Token 数，包含 thinking 与最终文本。
          maximum: 1048576
        messages:
          type: array
          minItems: 1
          description: Anthropic Messages 消息列表。多轮对话需原样回传完整 assistant 内容块。
          items:
            $ref: '#/components/schemas/Message'
        system:
          oneOf:
            - type: string
            - type: array
              items:
                $ref: '#/components/schemas/MessagesTextBlockParam'
          description: 系统提示，可为字符串或 text 块数组
        stream:
          type: boolean
          default: false
          description: 是否使用 Anthropic SSE 事件流返回。
        tools:
          type: array
          description: >-
            自定义函数或服务端联网搜索。内置搜索使用
            type=web_search_20250305、name=web_search；实际调用按次收费。
          items:
            oneOf:
              - $ref: '#/components/schemas/Tool'
              - $ref: '#/components/schemas/WebSearchTool'
        tool_choice:
          $ref: '#/components/schemas/ToolChoice'
        stop_sequences:
          type: array
          items:
            type: string
          maxItems: 5
          description: >-
            停用词，完全匹配时停止输出，匹配到的词本身不会被输出。最多 5 个，每个不超过 32 字节。命中时 `stop_reason` 返回
            `end_turn`，`stop_sequence` 为 `null`。


            仅 `kimi-k3.1-pro` / `kimi-k3.1-pro-highspeed` 支持，`kimi-k3` 不支持。
        cache_control:
          type: object
          description: >-
            顶层缓存写入选项，仅 `kimi-k3.1-pro` / `kimi-k3.1-pro-highspeed` 支持，`kimi-k3`
            不支持此参数。只有顶层 cache_control 控制写入 TTL，消息块内的缓存标记不能代替此字段。省略时默认为 5m。
          properties:
            type:
              type: string
              enum:
                - ephemeral
              description: 缓存类型，固定为 ephemeral
            ttl:
              type: string
              enum:
                - 5m
                - 1h
              default: 5m
              description: 缓存有效期，可选 5m 或 1h，默认 5m。
          required:
            - type
        output_config:
          type: object
          description: 输出配置：推理强度与结构化输出
          properties:
            effort:
              type: string
              enum:
                - low
                - high
                - max
                - medium
                - xhigh
                - minimal
                - none
              default: max
              description: >-
                思考强度。模型始终思考，传入 `thinking.type: "disabled"` 也不会关闭思考。


                - `kimi-k3.1-pro` / `kimi-k3.1-pro-highspeed`：推荐 `low` / `high`
                / `max`，默认 `max`。兼容通用客户端：`medium` 按 `high`，`xhigh` 按
                `max`，`minimal` / `none` 按 `low` 处理；`none` 不会关闭思考。

                - `kimi-k3`：仅支持 `max`（默认）。


                提高强度通常增加推理 Token 和延迟，思考 Token 计入输出。
            format:
              type: object
              description: >-
                结构化输出：设置后模型输出严格遵循给定 JSON Schema 的 JSON。仅 `kimi-k3.1-pro` /
                `kimi-k3.1-pro-highspeed` 支持，`kimi-k3` 不支持。如需 `kimi-k3`
                输出结构化结果，请使用 Chat Completions 接口的 `response_format`。
              properties:
                type:
                  type: string
                  enum:
                    - json_schema
                schema:
                  type: object
                  description: 输出需遵循的 JSON Schema
                  additionalProperties: true
              required:
                - type
                - schema
        temperature:
          type: number
          default: 1
          description: >-
            采样温度，由模型固定为 `1`，无需传入。`kimi-k3.1-pro` / `kimi-k3.1-pro-highspeed`
            会自动忽略此字段；`kimi-k3` 传入不支持的取值将返回错误。
        top_p:
          type: number
          default: 0.95
          description: >-
            核采样阈值，由模型固定为 `0.95`，无需传入。`kimi-k3.1-pro` / `kimi-k3.1-pro-highspeed`
            会自动忽略此字段；`kimi-k3` 传入不支持的取值将返回错误。
    MessageResponse:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          enum:
            - message
        role:
          type: string
          enum:
            - assistant
        model:
          type: string
          example: kimi-k3.1-pro
        content:
          type: array
          items:
            $ref: '#/components/schemas/ContentBlock'
        stop_reason:
          type:
            - string
            - 'null'
          enum:
            - end_turn
            - max_tokens
            - tool_use
            - refusal
            - null
        stop_sequence:
          type:
            - string
            - 'null'
        usage:
          $ref: '#/components/schemas/MessageUsage'
    Message:
      type: object
      required:
        - role
        - content
      properties:
        role:
          type: string
          description: 消息角色，仅支持 user 或 assistant。
          enum:
            - user
            - assistant
        content:
          description: 消息内容，可以是纯文本字符串或 Anthropic 内容块数组。
          oneOf:
            - type: string
            - type: array
              items:
                $ref: '#/components/schemas/ContentBlock'
    MessagesTextBlockParam:
      type: object
      properties:
        type:
          type: string
          enum:
            - text
        text:
          type: string
      required:
        - type
        - text
    Tool:
      type: object
      required:
        - name
        - input_schema
      properties:
        name:
          type: string
          description: 工具名称。
        description:
          type: string
          description: 工具用途说明，帮助模型判断何时调用。
        input_schema:
          type: object
          additionalProperties: true
          description: JSON Schema 格式的工具参数定义。
    WebSearchTool:
      type: object
      required:
        - type
        - name
      properties:
        type:
          type: string
          enum:
            - web_search_20250305
        name:
          type: string
          enum:
            - web_search
        max_uses:
          type: integer
          minimum: 1
          description: 本次响应允许的最大搜索次数。
    ToolChoice:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          description: 工具选择策略：auto 由模型决定，any 强制调用任一工具，none 禁止调用工具。
          enum:
            - auto
            - any
            - none
          default: auto
    ContentBlock:
      description: Anthropic 内容块，可用于文本、图片、推理、工具调用或工具结果。
      oneOf:
        - $ref: '#/components/schemas/TextBlock'
        - $ref: '#/components/schemas/ImageBlock'
        - $ref: '#/components/schemas/ThinkingBlock'
        - $ref: '#/components/schemas/ToolUseBlock'
        - $ref: '#/components/schemas/ToolResultBlock'
        - $ref: '#/components/schemas/ServerToolUseBlock'
        - $ref: '#/components/schemas/WebSearchResultBlock'
    MessageUsage:
      type: object
      properties:
        input_tokens:
          type: integer
          description: 普通输入 Token，已经排除缓存读取和缓存写入；三段输入互斥，不再减去缓存。
        cache_creation_input_tokens:
          type: integer
          description: 缓存写入 Token。
        cache_read_input_tokens:
          type: integer
          description: 缓存命中的输入 Token。
        output_tokens:
          type: integer
          description: 输出 Token，包含 thinking Token。
        output_tokens_details:
          type: object
          properties:
            thinking_tokens:
              type: integer
        cache_creation:
          type: object
          properties:
            ephemeral_5m_input_tokens:
              type: integer
              minimum: 0
            ephemeral_1h_input_tokens:
              type: integer
              minimum: 0
          description: cache_creation_input_tokens 的两档写入子项，K3.1 系列按实际 TTL 分别计费。
        server_tool_use:
          type: object
          properties:
            web_search_requests:
              type: integer
              minimum: 0
          description: 本次响应的搜索用量统计。
    ErrorResponse:
      type: object
      properties:
        type:
          type: string
          enum:
            - error
        error:
          type: object
          properties:
            type:
              type: string
            message:
              type: string
        request_id:
          type: string
    TextBlock:
      type: object
      required:
        - type
        - text
      properties:
        type:
          type: string
          description: 内容块类型，固定为 text。
          enum:
            - text
        text:
          type: string
          description: 文本内容。
    ImageBlock:
      type: object
      required:
        - type
        - source
      description: 图片内容块（多模态输入）。
      properties:
        type:
          type: string
          enum:
            - image
          description: 内容块类型，固定为 image。
        source:
          type: object
          required:
            - type
          description: 图片来源。
          properties:
            type:
              type: string
              enum:
                - base64
                - url
              description: 图片来源：base64 为内联编码，url 为文件引用。
            media_type:
              type: string
              enum:
                - image/jpeg
                - image/png
                - image/gif
                - image/webp
              description: '`type=base64` 时的图片 MIME 类型。'
            data:
              type: string
              description: '`type=base64` 时的图片 Base64 数据（不含 `data:` 前缀）。'
            url:
              type: string
              description: 图片文件引用地址，仅在 type=url 时使用。
    ThinkingBlock:
      type: object
      required:
        - type
        - thinking
      properties:
        type:
          type: string
          description: 内容块类型，固定为 thinking。
          enum:
            - thinking
        thinking:
          type: string
          description: 模型的推理内容。多轮对话时应与 signature 一起原样回传。
        signature:
          type: string
          description: 多轮对话时必须与 thinking block 一起原样回传。
    ToolUseBlock:
      type: object
      required:
        - type
        - id
        - name
        - input
      properties:
        type:
          type: string
          description: 内容块类型，固定为 tool_use。
          enum:
            - tool_use
        id:
          type: string
          description: 工具调用 ID，返回工具结果时通过 tool_use_id 关联。
        name:
          type: string
          description: 模型请求调用的工具名称。
        input:
          type: object
          additionalProperties: true
          description: 模型为工具生成的参数对象。
    ToolResultBlock:
      type: object
      required:
        - type
        - tool_use_id
        - content
      properties:
        type:
          type: string
          description: 内容块类型，固定为 tool_result。
          enum:
            - tool_result
        tool_use_id:
          type: string
          description: 对应的 tool_use 内容块 ID。
        content:
          description: 工具执行结果，可为字符串或文本、图片内容块数组。
          oneOf:
            - type: string
            - type: array
              items:
                oneOf:
                  - $ref: '#/components/schemas/TextBlock'
                  - $ref: '#/components/schemas/ImageBlock'
        is_error:
          type: boolean
          default: false
          description: 工具执行是否失败。
    ServerToolUseBlock:
      type: object
      required:
        - type
        - id
        - name
        - input
      properties:
        type:
          type: string
          enum:
            - server_tool_use
        id:
          type: string
        name:
          type: string
        input:
          type: object
          additionalProperties: true
    WebSearchResultBlock:
      type: object
      required:
        - type
        - tool_use_id
        - content
      properties:
        type:
          type: string
          enum:
            - web_search_tool_result
        tool_use_id:
          type: string
        content:
          oneOf:
            - type: array
              items:
                type: object
                additionalProperties: true
            - type: object
              additionalProperties: true
              description: 搜索错误对象，type=web_search_tool_result_error。
  responses:
    BadRequest:
      description: 请求参数错误
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: API Key 无效或缺失
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimited:
      description: 请求过于频繁或额度不足
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalError:
      description: 服务内部错误
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |-
        ##所有接口均需要使用 Bearer Token 进行认证##

        **获取 API Key**：

        访问 [API Key 管理页面](https://evolink.ai/dashboard/keys) 获取您的 API Key

        **使用时在请求头中添加**：
        ```
        Authorization: Bearer YOUR_API_KEY
        ```

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.