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

# 混合理解

> 使用返回的任务 ID [进行查询](/pages/zh/api-manual/task-management/get-task-detail) 获取最终结果。



## OpenAPI

````yaml openapi/zh/llm-custom.json POST /v1/llm/generations
openapi: 3.1.0
info:
  title: LLM · llm-custom protocol
  version: '1.0'
  description: >-
    统一 LLM 入口的 **`llm-custom`** 请求格式：OpenAI Chat Completions
    超集，`messages[*].content` 数组除 `text` / `image_url` 外额外接受 `video_url` /
    `audio_url` / `file_url`；响应统一为 OpenAI `ChatCompletion` /
    `chat.completion.chunk`。


    **`/v1/llm/generations` 端点支持 5 种请求形态**：

    - `llm-text`：仅 `prompt`

    - `llm-vision`：`prompt` + `image_urls[]`

    - `llm-video`：`prompt` + `video_urls[]`

    - `llm-audio`：`audio_url`

    - `llm-custom`（本文件）：`messages[]`（OpenAI Chat 兼容）


    任务最终结果通过 `GET /v1/tasks/{task_id}` 查询。当前 token 可用的模型清单可通过 `GET
    /v1/configs/llm_generations_models` 动态查询。
servers:
  - url: https://api.aihubmax.com
security:
  - BearerAuth: []
paths:
  /v1/llm/generations:
    post:
      tags:
        - LLM > llm-custom
      summary: 提交 LLM 生成任务（llm-custom 协议）
      description: >-
        使用返回的任务 ID [进行查询](/pages/zh/api-manual/task-management/get-task-detail)
        获取最终结果。
      operationId: llm-custom
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LLMCustomRequest'
            examples:
              openai_non_stream:
                summary: OpenAI Chat 家族 · 非流式
                value:
                  model: gpt-5.5
                  messages:
                    - role: user
                      content: count 1 to 3
                  stream: false
                  max_tokens: 32
              anthropic_stream:
                summary: Anthropic 家族 · 流式（max_tokens 必填）
                value:
                  model: claude-opus-4-7
                  messages:
                    - role: system
                      content: You are a terse assistant.
                    - role: user
                      content: count 1 to 3
                  stream: true
                  max_tokens: 64
              gemini_stream:
                summary: Gemini 家族 · 流式
                value:
                  model: gemini-3.5-flash
                  messages:
                    - role: user
                      content: count 1 to 3
                  stream: true
                  max_tokens: 64
              multimodal_image:
                summary: 多模态 · image_url（claude-opus-4-7）
                value:
                  model: claude-opus-4-7
                  messages:
                    - role: user
                      content:
                        - type: text
                          text: describe this image briefly
                        - type: image_url
                          image_url:
                            url: https://example.com/sample.png
                  stream: false
                  max_tokens: 256
      responses:
        '200':
          description: 任务已创建
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitResponse'
              examples:
                non_stream:
                  summary: stream=false
                  value:
                    id: task-llm-1776874481-rj6bs3yb
                    object: llm.generation.task
                    type: llm
                    model: gpt-5.5
                    status: pending
                    progress: 0
                    created: 1776874481
                    stream: null
                    results: null
                    error: null
                stream:
                  summary: stream=true
                  value:
                    id: task-llm-1776874565-yq3szvcu
                    object: llm.generation.task
                    type: llm
                    model: claude-opus-4-7
                    status: pending
                    progress: 0
                    created: 1776874565
                    stream:
                      url: /v1/llm/generations/task-llm-1776874565-yq3szvcu/stream
                    results: null
                    error: null
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  schemas:
    LLMCustomRequest:
      type: object
      required:
        - model
        - messages
      additionalProperties: true
      description: >-
        `messages[]` 形态的请求体（OpenAI Chat 兼容）。除下列字段外，其他 OpenAI
        兼容参数（`temperature`、`top_p`、`stop`、`frequency_penalty` 等）按 OpenAI Chat
        规范使用。
      properties:
        model:
          type: string
          description: >-
            [获取模型列表](/pages/zh/api-manual/text-series/llm-async/llm-generations-models)
          example: claude-opus-4-7
        messages:
          type: array
          description: >-
            OpenAI Chat 格式消息数组。`messages[*].content` 可为 string 或 array；array 元素
            `type` ∈ {`text`, `image_url`, `video_url`, `audio_url`,
            `file_url`}。模型不支持的 `type` 返 422 `model_not_support_capability`。


            **典型 content 形态示例：**


            1. 纯 text（string content，最简形式）：

            ```json

            [{"role": "user", "content": "count 1 to 3"}]

            ```


            2. 纯 text（array content，与多模态混用时统一格式）：

            ```json

            [{"role": "user", "content": [{"type": "text", "text": "count 1 to
            3"}]}]

            ```


            3. text + 图片：

            ```json

            [{"role": "user", "content": [
              {"type": "text", "text": "describe this image"},
              {"type": "image_url", "image_url": {"url": "https://example.com/x.png"}}
            ]}]

            ```


            4. text + 视频：

            ```json

            [{"role": "user", "content": [
              {"type": "text", "text": "summarize this video"},
              {"type": "video_url", "video_url": {"url": "https://example.com/clip.mp4"}}
            ]}]

            ```


            5. text + 文件：

            ```json

            [{"role": "user", "content": [
              {"type": "text", "text": "extract key points"},
              {"type": "file_url", "file_url": {"url": "https://example.com/doc.pdf"}}
            ]}]

            ```


            6. 多轮对话（system + 多轮 user/assistant）：

            ```json

            [
              {"role": "system", "content": "You are a terse assistant."},
              {"role": "user", "content": "1+1?"},
              {"role": "assistant", "content": "2"},
              {"role": "user", "content": "3+3?"}
            ]

            ```


            7. 全类型附件混合（单条 user 消息内含 `image_url` / `video_url` / `audio_url` /
            `file_url` 各 2 个）：

            ```json

            [{"role": "user", "content": [
              {"type": "text", "text": "汇总下列图片、视频、音频和文档的核心信息"},
              {"type": "image_url", "image_url": {"url": "https://example.com/image-1.png"}},
              {"type": "image_url", "image_url": {"url": "https://example.com/image-2.jpg"}},
              {"type": "video_url", "video_url": {"url": "https://example.com/clip-1.mp4"}},
              {"type": "video_url", "video_url": {"url": "https://example.com/clip-2.mp4"}},
              {"type": "audio_url", "audio_url": {"url": "https://example.com/audio-1.mp3"}},
              {"type": "audio_url", "audio_url": {"url": "https://example.com/audio-2.wav"}},
              {"type": "file_url", "file_url": {"url": "https://example.com/doc-1.pdf"}},
              {"type": "file_url", "file_url": {"url": "https://example.com/doc-2.docx"}}
            ]}]

            ```


            **内联 base64（仅异步模式，`sync` 省略或为 `false`）**：`image_url` / `video_url` /
            `audio_url` / `file_url` 四种块中，值为 `{"url": ...}` 对象形态的内联
            base64（`data:` URI，或 4096 个以上编码字符且解码内容命中已知媒体签名的裸
            base64），会在请求入库与提交上游之前上传文件存储并替换为 URL，不以 base64 原文入库；更短的裸
            base64、或签名不可识别的内容按原样透传，也不做体积校验。上限只作用于内联 base64 项（公网 http(s) URL
            不受限）：单项解码后 ≤ 5 MB、单数组内联 ≤ 5 项、单请求合计 ≤ 10 MB、单请求内联总数 ≤ 20 项。`data:`
            前缀格式非法或 payload 解码为 0 字节返回 422，超限同样返回 422，请改用 `/v1/files/upload`
            上传后传 URL。


            `sync: true` 时请求不写任务记录，以上均不适用：内联 base64 原样提交上游，不做任何体积或数量校验。


            不在覆盖范围内的形态：`input_audio.data` / `file.file_data`，以及
            `{"type":"image_url","image_url":"data:..."}` 字符串直挂形态（值不是 `{"url":
            ...}` 对象）——这些内联 base64 按原样透传。
          items:
            $ref: '#/components/schemas/ChatMessage'
          example:
            - role: user
              content: count 1 to 3
        stream:
          type: boolean
          default: false
          description: >
            是否流式。


            **行为差异：**

            | 值 | Submit 响应 `stream` 字段 | SSE 端点 |

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

            | `false` | `null` | 不可用 |

            | `true` | `{"url": "/v1/llm/generations/{task_id}/stream"}` | 可用；同时
            task.data 累积完整响应 |
          example: false
        max_tokens:
          type: integer
          nullable: true
          description: 生成 token 上限。家族级约束：`claude-*` **必填**；`gpt-*` 通常 ≥ 16；`gemini-*` 可选。
          example: 64
        temperature:
          type: number
          nullable: true
          description: 采样温度。
        top_p:
          type: number
          nullable: true
          description: nucleus sampling。
        stop:
          description: 停止序列。
          oneOf:
            - type: string
            - type: array
              items:
                type: string
    SubmitResponse:
      type: object
      description: >-
        Submit 响应，对齐统一任务标准形状。`results` / `error` 在 submit 阶段固定为
        `null`，任务完成/失败后通过 `GET /v1/tasks/{task_id}` 返回
      required:
        - id
        - object
        - type
        - model
        - status
        - progress
        - created
      properties:
        id:
          type: string
          description: >-
            任务 ID，格式 `task-llm-{timestamp}-{8random}`。用于 `GET
            /v1/tasks/{task_id}` 查询或 `GET /v1/llm/generations/{task_id}/stream`
            订阅 SSE
          example: task-llm-1776874565-yq3szvcu
        object:
          type: string
          description: 对象类型，固定 `llm.generation.task`
          enum:
            - llm.generation.task
          example: llm.generation.task
        type:
          type: string
          description: 媒体类型，固定 `llm`
          enum:
            - llm
          example: llm
        model:
          type: string
          description: 客户端提交的模型名（原样回显）
          example: claude-opus-4-7
        status:
          type: string
          description: 任务状态，submit 阶段固定 `pending`
          enum:
            - pending
          example: pending
        progress:
          type: integer
          description: 进度 0-100，submit 阶段固定 0
          example: 0
        created:
          type: integer
          description: 创建时间（Unix 秒）
          example: 1776874565
        stream:
          nullable: true
          description: >-
            `stream=true` 时返回 `{url: ...}`；`stream=false` 时为 `null`。客户端据此决定是否连接
            SSE
          oneOf:
            - $ref: '#/components/schemas/StreamInfo'
            - type: 'null'
        results:
          type: array
          nullable: true
          description: >-
            submit 阶段固定 `null`；任务完成后通过 `GET /v1/tasks/{task_id}` 获取，`results[0]`
            为完整 OpenAI `ChatCompletion` 响应。


            **已知限制**：thinking 模型的推理内容（`reasoning_content`）仅在 SSE 流的 `delta`
            中出现，不累积到 `results[0].message.content`
          items:
            type: object
          example: null
        error:
          type: object
          nullable: true
          description: submit 阶段固定 `null`；任务失败时通过 `GET /v1/tasks/{task_id}` 返回
          example: null
    ChatMessage:
      type: object
      required:
        - role
        - content
      properties:
        role:
          type: string
          enum:
            - system
            - user
            - assistant
          description: 消息角色（OpenAI 命名）
        content:
          description: 消息正文。string 表示纯文本；array 表示多模态内容块
          oneOf:
            - type: string
            - type: array
              items:
                $ref: '#/components/schemas/ContentBlock'
          example: count 1 to 3
    StreamInfo:
      type: object
      description: SSE 订阅信息。仅在 `stream=true` 时作为 `SubmitResponse.stream` 返回
      required:
        - url
      properties:
        url:
          type: string
          description: SSE 订阅路径，形如 `/v1/llm/generations/{task_id}/stream`
          example: /v1/llm/generations/task-llm-1776874565-yq3szvcu/stream
    ErrorResponse401:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              example: 未提供认证 token
            type:
              type: string
              example: authentication_error
    ErrorResponse422:
      type: object
      description: >-
        参数校验失败。常见 `code`：

        - `no_available_model`：所传模型当前未配置或不可用

        - `model_not_support_capability`：请求的内容类型组合（如 text + video）该模型不支持

        - `model_rule_violation`：违反模型规则；具体子规则名见错误体 `code` 字段（如
        `gemini_video_size_exceeded`、`anthropic_max_tokens_required`）

        - `invalid_param`：常规 schema 校验失败（含 `max_tokens` 家族约束违反等）
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              example: 模型 gpt-5.5 不支持 text + video 同时使用，请更换模型或联系管理员。
            type:
              type: string
              example: invalid_request_error
            code:
              type: string
              example: model_not_support_capability
    ErrorResponse429:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              example: 请求频率超限
            type:
              type: string
              example: rate_limit_error
    ErrorResponse500:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              example: Internal server error
            type:
              type: string
              example: internal_error
    ErrorResponse503:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              example: Upstream temporarily unavailable
            type:
              type: string
              example: service_unavailable
    ContentBlock:
      type: object
      description: 多模态内容块。不同 `type` 使用不同的并列字段承载 URL 或文本
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - text
            - image_url
            - video_url
            - audio_url
            - file_url
          description: 内容块类型
        text:
          type: string
          description: '`type=text` 时必填'
        image_url:
          type: object
          description: '`type=image_url` 时必填'
          required:
            - url
          properties:
            url:
              type: string
              description: 公网可访问的图片 URL（或 base64 data URL）
        video_url:
          type: object
          description: '`type=video_url` 时必填；模型不支持时返 422 `model_not_support_capability`'
          required:
            - url
          properties:
            url:
              type: string
        audio_url:
          type: object
          description: '`type=audio_url` 时必填；模型不支持时返 422 `model_not_support_capability`'
          required:
            - url
          properties:
            url:
              type: string
        file_url:
          type: object
          description: '`type=file_url` 时必填；模型不支持时返 422 `model_not_support_capability`'
          required:
            - url
          properties:
            url:
              type: string
  responses:
    Unauthorized:
      description: Token 无效或缺失
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse401'
    UnprocessableEntity:
      description: 参数校验失败或模型不支持本次请求；具体原因见响应体 `error.code`
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse422'
    TooManyRequests:
      description: 请求频率超限
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse429'
    InternalServerError:
      description: 服务器内部错误
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse500'
    ServiceUnavailable:
      description: 上游不可用
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse503'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: |-
        所有接口均需要使用 Bearer Token 进行认证。在请求头中添加：

        `Authorization: Bearer YOUR_API_KEY`

        `YOUR_API_KEY` 为 API Token（`sk-...` 格式）。

````