> ## 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-video.json POST /v1/llm/generations
openapi: 3.1.0
info:
  title: LLM · llm-video protocol
  version: '1.0'
  description: >-
    统一 LLM 入口的 **`llm-video`** 请求格式：`prompt` + `video_urls[]`（1–10 个）→ 视频理解。


    **`/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 兼容）


    **video_urls 接受 URL 或 base64 data URI**：

    - HTTP/HTTPS URL（公网可达）

    - `data:video/<mp4|webm|mov>;base64,<payload>` data URI（base64 内联，注意视频
    base64 体积大）


    **视频 token 成本提示**：视频通常按帧采样 + 时间编码，30s 视频可能消耗 20K+ tokens。建议优先选择 gemini
    类长上下文模型。


    任务最终结果通过 `GET /v1/tasks/{task_id}` 查询；SSE 流式订阅端点为 `GET
    /v1/llm/generations/{task_id}/stream`，所有 5 种 protocol 共用。
servers:
  - url: https://api.aihubmax.com
security:
  - BearerAuth: []
paths:
  /v1/llm/generations:
    post:
      tags:
        - LLM > llm-video
      summary: 提交 LLM 生成任务（llm-video 协议）
      description: >-
        使用返回的任务 ID [进行查询](/pages/zh/api-manual/task-management/get-task-detail)
        获取最终结果。
      operationId: llm-video
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LLMVideoRequest'
            examples:
              example_0:
                summary: Async — describe a video
                value:
                  model: gemini-2.5-pro
                  prompt: What is happening in this video?
                  video_urls:
                    - >-
                      https://storage.googleapis.com/cloud-samples-data/video/animals.mp4
                  max_tokens: 128
              example_1:
                summary: Sync non-stream with reasoning enabled
                value:
                  model: gemini-2.5-pro
                  prompt: Identify the species and habitat in one sentence.
                  video_urls:
                    - >-
                      https://storage.googleapis.com/cloud-samples-data/video/animals.mp4
                  sync: true
                  max_tokens: 64
                  reasoning: true
      responses:
        '200':
          description: 任务已创建（async 模式）/ 完整响应（sync 模式）
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitResponse'
              examples:
                non_stream:
                  summary: sync=false, stream=false
                  value:
                    id: task-llmrouter-1776874481-rj6bs3yb
                    object: llm.generation.task
                    type: llm
                    model: gemini-2.5-pro
                    status: pending
                    progress: 0
                    created: 1776874481
                    stream: null
                    results: null
                    error: null
                stream:
                  summary: sync=false, stream=true
                  value:
                    id: task-llmrouter-1776874565-yq3szvcu
                    object: llm.generation.task
                    type: llm
                    model: gemini-2.5-pro
                    status: pending
                    progress: 0
                    created: 1776874565
                    stream:
                      url: >-
                        /v1/llm/generations/task-llmrouter-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:
    LLMVideoRequest:
      type: object
      required:
        - model
        - prompt
        - video_urls
      additionalProperties: true
      properties:
        model:
          type: string
          description: >-
            [获取模型列表](/pages/zh/api-manual/text-series/llm-async/llm-generations-models)
          example: gemini-2.5-pro
        prompt:
          type: string
          maxLength: 100000
          description: 用户提示词，最多 100,000 字符。
          example: What is happening in this video?
        video_urls:
          type: array
          minItems: 1
          maxItems: 10
          description: >-
            视频源数组（1–10 个）。每个元素接受以下两种形式：

            - 公网 HTTP/HTTPS URL

            - `data:video/<type>;base64,<payload>` data URI（base64 内联，注意视频体积大）


            **URL 格式约束**（基于 fal openrouter 实测，2026-05-13）：

            - 直接视频文件：扩展名必须是 `.mp4` / `.mpeg` / `.mpg` / `.mov` / `.webm`

            - YouTube 视频：支持 `https://www.youtube.com/watch?v=<id>` 和
            `https://youtu.be/<id>`（仅 Gemini 家族可用）

            - **不支持** YouTube Shorts
            URL（`https://www.youtube.com/shorts/<id>`），上游会返回 422。客户端可将 `<id>`
            改写为 `watch?v=<id>` 形式后再调用


            **模型限制**：是否支持多视频以及上限张数由所选模型对应上游决定；当某模型仅支持单视频而请求传入多个时，路由层返回 422
            `model_rule_violation`（具体规则维护在
            `app/relays/llm_router/model_rules.py`）。Gemini 家族通常支持多视频。


            **成本提示**：视频按帧 + 时间编码，30s 视频可能 20K+ tokens。建议短片段或低帧率源。


            **内联 base64（仅异步模式，`sync` 省略或为 `false`）**：网关识别为内联媒体的 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 原样提交上游，不做任何体积或数量校验。
          items:
            type: string
          example:
            - >-
              https://storage.googleapis.com/cloud-samples-data/video/animals.mp4
        sync:
          type: boolean
          default: false
          description: 同步模式（参见 llm-text schema）。
          example: false
        stream:
          type: boolean
          default: false
          description: 是否流式（参见 llm-text schema）。
          example: false
        max_tokens:
          type: integer
          nullable: true
          minimum: 1
          description: 生成 token 上限。可选。
          example: 128
        temperature:
          type: number
          nullable: true
          minimum: 0
          maximum: 2
          description: 采样温度，区间 [0, 2]。可选。
        system_prompt:
          type: string
          nullable: true
          maxLength: 10000
          description: 系统指令。可选。
        reasoning:
          type: boolean
          nullable: true
          description: 是否包含 reasoning tokens。`gemini-2.5-pro` 等思考模型可能需设为 `true`。
    SubmitResponse:
      type: object
      description: >-
        Submit 响应，对齐统一任务标准形状。`results` / `error` 在 submit 阶段固定为
        `null`，任务完成/失败后通过 `GET /v1/tasks/{task_id}` 返回。`sync=true, stream=false`
        模式下端点直接返回完整 OpenAI ChatCompletion JSON。
      required:
        - id
        - object
        - type
        - model
        - status
        - progress
        - created
      properties:
        id:
          type: string
          description: 任务 ID，格式 `task-llmrouter-{timestamp}-{8random}`。
          example: task-llmrouter-1776874565-yq3szvcu
        object:
          type: string
          enum:
            - llm.generation.task
          example: llm.generation.task
        type:
          type: string
          enum:
            - llm
          example: llm
        model:
          type: string
          description: 客户端提交的模型名（原样回显）
          example: gemini-2.5-pro
        status:
          type: string
          enum:
            - pending
          example: pending
        progress:
          type: integer
          example: 0
        created:
          type: integer
          example: 1776874565
        stream:
          nullable: true
          description: '`stream=true` 时返回 `{url: ...}`；`stream=false` 时为 `null`。'
          oneOf:
            - $ref: '#/components/schemas/StreamInfo'
            - type: 'null'
        results:
          type: array
          nullable: true
          description: >-
            submit 阶段固定 `null`；任务完成后通过 `GET /v1/tasks/{task_id}` 返回，`results[0]`
            为完整 OpenAI `ChatCompletion` 响应。
          items:
            type: object
          example: null
        error:
          type: object
          nullable: true
          description: submit 阶段固定 `null`；任务失败时通过 `GET /v1/tasks/{task_id}` 返回。
          example: null
    StreamInfo:
      type: object
      required:
        - url
      properties:
        url:
          type: string
          example: /v1/llm/generations/task-llmrouter-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`：`model_rule_violation`（命中模型固有规则，如单视频模型收到多个）、`model_not_support_capability`（候选渠道未声明
        `video`
        能力）、`model_not_registered`、`invalid_param`、`upstream_client_error`。
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              example: >-
                model 'xxx' only accepts a single video_url; received
                video_urls.length=2
            type:
              type: string
              example: invalid_request_error
            code:
              type: string
              example: model_input_not_supported
    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: 'all 3 candidates exhausted; last error: ...'
            type:
              type: string
              example: upstream_error
            code:
              type: string
              example: all_platforms_exhausted
  responses:
    Unauthorized:
      description: Token 无效或缺失
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse401'
    UnprocessableEntity:
      description: 参数校验失败 / 模型固有约束（如单视频模型收到多个）/ 候选渠道未声明 `video` 能力 / 模型未注册 / 上游 4xx
      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-...` 格式）。

````