> ## 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.

# Qwen3.8-Max-Preview - 完整参数文档

> > 🚧 **该模型暂未开放，敬请期待**

- 使用 OpenAI Chat Completions 协议调用 Qwen3.8-Max-Preview
- **多轮对话**：支持单轮或多轮上下文对话
- **系统提示词**：通过 `role=system` 消息设定 AI 角色与行为
- **多模态输入**：`content` 传 content part 数组，支持 `text` / `image_url` / `input_audio` / `video_url`
- **上下文缓存**：在 content part 上加 `cache_control` 声明显式缓存；命中情况见响应 `usage.prompt_tokens_details`
- **思考模式**：`enable_thinking=true` 开启，思考内容通过 `reasoning_content` 返回
- **流式输出**：`stream=true` 时通过 SSE 逐块返回

<Note>
  **BaseURL 说明**：默认 BaseURL 为 `https://direct.evolink.ai`，对文本模型支持更好，支持长连接；`https://api.evolink.ai` 是多模态主力地址，含图像 / 音频 / 视频输入时请使用该地址。
</Note>


## OpenAPI

````yaml cn/api-manual/language-series/qwen3.8-max-preview/qwen3.8-max-preview-chat.json POST /v1/chat/completions
openapi: 3.1.0
info:
  title: Qwen3.8-Max-Preview 完整参数文档 (OpenAI 兼容)
  description: |-
    通义千问 Qwen3.8-Max-Preview 对话接口的 API 参考（OpenAI Chat Completions 兼容）。

    **模型能力**：
    - 上下文长度：**1,000,000 tokens**（1M）
    - 思考模式：通过 `enable_thinking` 开启，思考内容通过 `reasoning_content` 返回
    - 多模态输入：`content` 支持文本 + 图像 / 音频 / 视频混排
    - 上下文缓存：支持显式缓存（`cache_control`）与隐式缓存，命中大幅降低成本
    - 工具调用：支持 Function Calling
    - 流式输出：支持 SSE 流式返回
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://direct.evolink.ai
    description: 生产环境（推荐，文本模型长连接支持更好）
  - url: https://api.evolink.ai
    description: 多模态主力地址（含图像 / 音频 / 视频输入时使用）
security:
  - bearerAuth: []
tags: []
paths:
  /v1/chat/completions:
    post:
      summary: Qwen3.8-Max-Preview 对话接口（OpenAI 兼容）
      description: >-
        > 🚧 **该模型暂未开放，敬请期待**


        - 使用 OpenAI Chat Completions 协议调用 Qwen3.8-Max-Preview

        - **多轮对话**：支持单轮或多轮上下文对话

        - **系统提示词**：通过 `role=system` 消息设定 AI 角色与行为

        - **多模态输入**：`content` 传 content part 数组，支持 `text` / `image_url` /
        `input_audio` / `video_url`

        - **上下文缓存**：在 content part 上加 `cache_control` 声明显式缓存；命中情况见响应
        `usage.prompt_tokens_details`

        - **思考模式**：`enable_thinking=true` 开启，思考内容通过 `reasoning_content` 返回

        - **流式输出**：`stream=true` 时通过 SSE 逐块返回
      operationId: createChatCompletionQwen38MaxPreview
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
            examples:
              basic:
                summary: 基础文本对话
                value:
                  model: qwen3.8-max-preview
                  messages:
                    - role: system
                      content: You are a helpful assistant.
                    - role: user
                      content: 你好，介绍一下你自己
              multimodal:
                summary: 多模态输入（图像）
                value:
                  model: qwen3.8-max-preview
                  messages:
                    - role: user
                      content:
                        - type: text
                          text: 描述这张图片的内容
                        - type: image_url
                          image_url:
                            url: https://example.com/image.jpg
              explicit_cache:
                summary: 显式缓存（cache_control）
                value:
                  model: qwen3.8-max-preview
                  messages:
                    - role: system
                      content:
                        - type: text
                          text: <超过 1024 token 的稳定系统提示词……>
                          cache_control:
                            type: ephemeral
                    - role: user
                      content: 基于以上背景回答问题
      responses:
        '200':
          description: 对话生成成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionResponse'
        '400':
          description: 请求参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 400
                  message: Invalid request parameters
                  type: invalid_request_error
        '401':
          description: 未认证、Token 无效或过期
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 401
                  message: Invalid or expired token
                  type: authentication_error
        '402':
          description: 余额不足
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 402
                  message: Insufficient credits
                  type: insufficient_quota
        '429':
          description: 请求过于频繁（限流）
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 429
                  message: Rate limit exceeded
                  type: rate_limit_error
        '500':
          description: 服务器内部错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 500
                  message: Internal server error
                  type: server_error
components:
  schemas:
    ChatCompletionRequest:
      type: object
      required:
        - model
        - messages
      properties:
        model:
          type: string
          description: 对话模型名称
          enum:
            - qwen3.8-max-preview
          example: qwen3.8-max-preview
        messages:
          type: array
          description: >-
            对话消息列表，支持多轮对话。不同角色（system / user / assistant /
            tool）的消息字段结构不同，请选择对应角色查看。
          items:
            oneOf:
              - $ref: '#/components/schemas/SystemMessage'
              - $ref: '#/components/schemas/UserMessage'
              - $ref: '#/components/schemas/AssistantRequestMessage'
              - $ref: '#/components/schemas/ToolMessage'
        enable_thinking:
          type: boolean
          description: |-
            是否开启深度思考

            - `true`：模型输出思考过程，通过 `reasoning_content` 返回
            - `false`（默认）：不输出思考过程

            > 注：部分模型在非流式调用下需显式设置为 `true` 才返回思考内容。
          default: false
        temperature:
          type: number
          description: >-
            采样温度，控制输出随机性。较低值更确定、较高值更多样。取值范围 `[0, 2]`。建议 temperature 与 top_p
            不要同时调整。
          minimum: 0
          maximum: 2
        top_p:
          type: number
          description: >-
            核采样（Nucleus Sampling）参数，从累积概率前若干 token 中采样。取值范围 `(0, 1]`。建议不要同时调整
            temperature 和 top_p。
          minimum: 0
          maximum: 1
        max_completion_tokens:
          type: integer
          description: >-
            生成内容长度上限（Token 数），**包含思维链和回答**。思考类模型推荐使用该参数。默认值与最大值均为模型最大输出长度；超出后以
            `finish_reason=length` 提前停止。
        max_tokens:
          type: integer
          description: |-
            旧版生成长度限制参数。

            > **已弃用**：新接入请改用 `max_completion_tokens`。该参数仅限制回答部分（不含思维链）。
        stream:
          type: boolean
          description: |-
            是否以流式方式返回响应。

            - `true`：通过 SSE（Server-Sent Events）逐块返回
            - `false`（默认）：一次性返回完整响应
          default: false
        stream_options:
          type: object
          description: 流式响应选项，仅在 `stream=true` 时有效。
          properties:
            include_usage:
              type: boolean
              description: 为 `true` 时，在流式结束前额外返回一个仅含 `usage` 的数据块。
        tools:
          type: array
          description: 工具定义列表，用于 Function Calling。每个工具需定义名称、描述与参数 schema。
          items:
            $ref: '#/components/schemas/Tool'
    ChatCompletionResponse:
      type: object
      properties:
        id:
          type: string
          description: 本次对话的唯一标识
          example: chatcmpl-xxxxxxxx
        object:
          type: string
          example: chat.completion
        created:
          type: integer
          description: 创建时间（Unix 秒）
          example: 1735120033
        model:
          type: string
          example: qwen3.8-max-preview
        choices:
          type: array
          items:
            $ref: '#/components/schemas/Choice'
        usage:
          $ref: '#/components/schemas/Usage'
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: integer
              description: HTTP 状态错误代码
            message:
              type: string
              description: 错误描述信息
            type:
              type: string
              description: 错误类型
            param:
              type: string
              description: 相关参数名称
    SystemMessage:
      type: object
      title: System Message
      required:
        - role
        - content
      properties:
        role:
          type: string
          enum:
            - system
          description: 消息角色，固定为 `system`
        content:
          description: 系统指令。纯文本时传字符串；需声明显式缓存时传 content part 数组。
          oneOf:
            - type: string
            - type: array
              items:
                $ref: '#/components/schemas/ContentPart'
    UserMessage:
      type: object
      title: User Message
      required:
        - role
        - content
      properties:
        role:
          type: string
          enum:
            - user
          description: 消息角色，固定为 `user`
        content:
          description: >-
            用户消息内容。


            - 纯文本时直接传字符串

            - 多模态或需显式缓存时，传 content part 数组，支持 `text` / `image_url` /
            `input_audio` / `video_url`
          oneOf:
            - type: string
            - type: array
              items:
                $ref: '#/components/schemas/ContentPart'
    AssistantRequestMessage:
      type: object
      title: Assistant Message
      required:
        - role
      properties:
        role:
          type: string
          enum:
            - assistant
          description: 消息角色，固定为 `assistant`
        content:
          description: 助手历史回复内容。可为字符串或 content part 数组。
          oneOf:
            - type: string
            - type: array
              items:
                $ref: '#/components/schemas/ContentPart'
        tool_calls:
          type: array
          description: 上一轮助手发起的工具调用列表（用于回填 Function Calling 历史）。
          items:
            type: object
    ToolMessage:
      type: object
      title: Tool Message
      required:
        - role
        - content
        - tool_call_id
      properties:
        role:
          type: string
          enum:
            - tool
          description: 消息角色，固定为 `tool`（工具执行结果）
        content:
          description: 工具执行结果内容。可为字符串或 content part 数组。
          oneOf:
            - type: string
            - type: array
              items:
                $ref: '#/components/schemas/ContentPart'
        tool_call_id:
          type: string
          description: 对应的工具调用 ID
    Tool:
      type: object
      description: Function Calling 工具定义。
      required:
        - type
        - function
      properties:
        type:
          type: string
          enum:
            - function
          description: 工具类型，固定为 `function`
        function:
          type: object
          required:
            - name
          properties:
            name:
              type: string
              description: 函数名称
            description:
              type: string
              description: 函数用途描述
            parameters:
              type: object
              description: 函数参数的 JSON Schema
    Choice:
      type: object
      properties:
        index:
          type: integer
          example: 0
        message:
          $ref: '#/components/schemas/AssistantMessage'
        finish_reason:
          type: string
          description: |-
            停止原因

            - `stop`：正常结束
            - `length`：达到 `max_completion_tokens` 上限
            - `tool_calls`：需要调用工具
          example: stop
    Usage:
      type: object
      description: Token 使用统计信息。
      properties:
        prompt_tokens:
          type: integer
          description: 输入 token 数
          example: 3019
        completion_tokens:
          type: integer
          description: 输出 token 数（含思考）
          example: 104
        total_tokens:
          type: integer
          description: 总 token 数
          example: 3123
        completion_tokens_details:
          type: object
          description: 输出 token 分项
          properties:
            reasoning_tokens:
              type: integer
              description: 思考过程 token 数
              example: 0
        prompt_tokens_details:
          type: object
          description: 输入 token 缓存分项
          properties:
            cached_tokens:
              type: integer
              description: 命中缓存的输入 token 数（缓存读）
              example: 2048
            cache_creation_input_tokens:
              type: integer
              description: 本次新创建缓存的 token 数（缓存写，显式缓存时返回）
              example: 0
    ContentPart:
      type: object
      description: 多模态内容片段，通过 `type` 声明类型，仅填写与该类型匹配的字段。可在任意片段上附加 `cache_control` 声明显式缓存。
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - text
            - image_url
            - input_audio
            - video_url
          description: |-
            内容类型

            - `text`：文本块
            - `image_url`：图片输入
            - `input_audio`：音频输入
            - `video_url`：视频文件输入
        text:
          type: string
          description: 当 `type=text` 时的文本内容
        image_url:
          type: object
          description: 图片输入（当 `type=image_url` 时）。支持 JPEG / PNG / GIF / WEBP。
          required:
            - url
          properties:
            url:
              type: string
              description: 图片 URL，或 `data:` 开头的 base64 data URL
            detail:
              type: string
              description: |-
                图片解析精度

                - `low`：低精度，消耗 token 更少
                - `high`：高精度，识别更细
                - `auto`（默认）：由模型自动决定
              enum:
                - low
                - high
                - auto
              default: auto
        input_audio:
          type: object
          description: 音频输入（当 `type=input_audio` 时）。
          required:
            - data
            - format
          properties:
            data:
              type: string
              description: 音频 URL，或 `data:` 开头的 base64 data URL
            format:
              type: string
              description: 音频格式，如 `mp3`、`wav` 等
        video_url:
          type: object
          description: 视频文件输入（当 `type=video_url` 时）。
          required:
            - url
          properties:
            url:
              type: string
              description: 视频文件 URL，或 `data:` 开头的 base64 data URL
        cache_control:
          type: object
          description: |-
            显式缓存标记。系统以该标记位置为终点向前回溯创建 / 命中缓存块。

            - 最小可缓存长度 **1024 token**，有效期 **5 分钟**（命中后重置）
            - 单次请求最多 **4 个**缓存标记
            - 与隐式缓存互斥，单请求只应用一种

            命中 / 创建情况见响应 `usage.prompt_tokens_details`。
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - ephemeral
              description: 缓存类型，固定为 `ephemeral`（5 分钟临时缓存）
    AssistantMessage:
      type: object
      description: 助手回复消息。
      properties:
        role:
          type: string
          example: assistant
        content:
          type: string
          description: 回复正文
          example: 你好！我是通义千问 Qwen3.8-Max-Preview。
        reasoning_content:
          type: string
          description: 思考过程内容（`enable_thinking=true` 时返回）
        tool_calls:
          type: array
          description: 模型发起的工具调用列表
          items:
            type: object
  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
        ```

````