> ## 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-audio.json POST /v1/llm/generations
openapi: 3.1.0
info:
  title: LLM · llm-audio protocol
  version: '1.0'
  description: >-
    统一 LLM 入口的 **`llm-audio`** 请求格式：单个 `audio_url`（+ 可选 `prompt`）→ 音频理解 / 转写。


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


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

    - HTTP/HTTPS URL（公网可达）

    - `data:audio/<wav|mp3|mpeg|aiff|aac|ogg|flac|m4a>;base64,<payload>` data
    URI（base64 内联）


    任务最终结果通过 `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-audio
      summary: 提交 LLM 生成任务（llm-audio 协议）
      description: >-
        使用返回的任务 ID [进行查询](/pages/zh/api-manual/task-management/get-task-detail)
        获取最终结果。
      operationId: llm-audio
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LLMAudioRequest'
            examples:
              example_0:
                summary: Transcribe a short audio clip
                value:
                  model: gemini-2.5-pro
                  audio_url: >-
                    https://storage.googleapis.com/cloud-samples-tests/speech/brooklyn.flac
                  max_tokens: 256
              example_1:
                summary: Audio with a custom prompt
                value:
                  model: gemini-2.5-pro
                  prompt: Identify the speakers and emotion in this audio.
                  audio_url: https://www.kozco.com/tech/piano2.wav
                  sync: true
              example_2:
                summary: Inline base64 audio (data URI)
                value:
                  model: gemini-2.5-pro
                  prompt: Transcribe this audio.
                  audio_url: >-
                    data:audio/wav;base64,UklGRiQAAABXQVZFZm10IBAAAAABAAEAQB8AAEAfAAABAAgAZGF0YQAAAAA=
      responses:
        '200':
          description: 任务已创建
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitResponse'
              examples:
                non_stream:
                  summary: sync=false, stream=false
                  value:
                    id: task-llm-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: stream=true
                  value:
                    id: task-llm-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-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:
    LLMAudioRequest:
      type: object
      required:
        - model
        - audio_url
      additionalProperties: true
      properties:
        model:
          type: string
          description: >-
            [获取模型列表](/pages/zh/api-manual/text-series/llm-async/llm-generations-models)
          example: gemini-2.5-pro
        audio_url:
          type: string
          minLength: 1
          description: >-
            音频源。接受以下两种形式：

            - 公网 HTTP/HTTPS URL

            - `data:audio/<type>;base64,<payload>` data URI（base64 内联）


            **各家族音频格式支持**（具体可用模型由渠道配置驱动）：

            - Gemini 家族（如 `gemini-*`）：wav/mp3/aiff/aac/ogg/flac/m4a；整个请求体（prompt
            + system + 内联文件）≤ 20 MB


            **内联 base64（仅异步模式，`sync` 省略或为 `false`）**：网关识别为内联媒体的 base64（`data:`
            URI，或 4096 个以上编码字符且解码内容命中已知媒体签名的裸 base64），会在请求入库与提交上游之前上传文件存储并替换为
            URL，不以 base64 原文入库；更短的裸 base64、或签名不可识别的内容按原样透传，也不做体积校验。上限只作用于内联
            base64 项（公网 URL 不受限）：单项解码后 ≤ 5 MB；本字段最多携带 1 个内联项，但仍占用「单请求合计 ≤ 10
            MB、单请求内联总数 ≤ 20 项」的全请求公共额度。`data:` 前缀格式非法或 payload 解码为 0 字节返回
            422，超限同样返回 422，请改用 `/v1/files/upload` 上传后传 URL。


            `sync: true` 时请求不写任务记录，以上均不适用：内联 base64 原样提交上游，不做任何体积或数量校验。
          example: >-
            https://storage.googleapis.com/cloud-samples-tests/speech/brooklyn.flac
        prompt:
          type: string
          nullable: true
          maxLength: 100000
          description: 用户提示词。省略时默认为 `'Please transcribe this audio file'`，与转写场景一致。
          example: Identify the speakers and emotion in this audio.
        sync:
          type: boolean
          default: false
          description: >-
            同步模式。`true` 时端点阻塞直到上游完成并返回完整响应（如同时 `stream=true`，则返回 SSE 流）；`false`
            时端点立即返回任务 ID，结果通过 `GET /v1/tasks/{task_id}` 或 SSE 端点获取。
          example: false
        stream:
          type: boolean
          default: false
          description: >-
            是否流式。`true` 时 Submit 响应包含 `stream.url` 指向 SSE 订阅路径；流式 chunks 统一为
            OpenAI `chat.completion.chunk` 格式。
          example: false
        max_tokens:
          type: integer
          nullable: true
          minimum: 1
          description: 生成 token 上限。可选。
          example: 256
        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。部分思考模型需设为 `true`。
    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}`。
          example: task-llm-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` 响应（音频转写 / 理解输出在 `message.content`）。
          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-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`：`invalid_param`（如 audio_url 格式或 data URI mime
        不被上游支持）、`model_not_support_capability`（候选渠道未声明 `audio`
        能力）、`model_not_registered`、`upstream_client_error`。
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              example: audio_url format not supported by upstream model
            type:
              type: string
              example: invalid_request_error
            code:
              type: string
              example: invalid_param
    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 channel not configured for 'gemini-2.5-pro'
            type:
              type: string
              example: service_unavailable
            code:
              type: string
              example: channel_not_found
  responses:
    Unauthorized:
      description: Token 无效或缺失
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse401'
    UnprocessableEntity:
      description: 参数校验失败（audio_url 格式或 data URI mime 不被上游支持、候选渠道未声明 `audio` 能力、模型未注册等）
      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-...` 格式）。

````