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

# Audio Understanding

> Use the returned task ID to [query the task](/pages/en/api-manual/task-management/get-task-detail) for the final result.



## OpenAPI

````yaml openapi/en/llm-audio.json POST /v1/llm/generations
openapi: 3.1.0
info:
  title: LLM · llm-audio protocol
  version: '1.0'
  description: >-
    Request format of the unified LLM entrypoint **`llm-audio`**: a single
    `audio_url` (+ optional `prompt`) → audio understanding / transcription.


    **The `/v1/llm/generations` endpoint supports 5 request forms**:

    - `llm-text`: `prompt` only

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

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

    - `llm-audio` (this file): `audio_url`

    - `llm-custom`: `messages[]` (OpenAI Chat compatible)


    **audio_url accepts URL or base64 data URI**:

    - HTTP/HTTPS URL (publicly reachable)

    - `data:audio/<wav|mp3|mpeg|aiff|aac|ogg|flac|m4a>;base64,<payload>` data
    URI (base64 inline)


    The final task result is queried via `GET /v1/tasks/{task_id}`; the SSE
    streaming subscription endpoint is `GET
    /v1/llm/generations/{task_id}/stream`, shared by all 5 protocols.
servers:
  - url: https://api.aihubmax.com
security:
  - BearerAuth: []
paths:
  /v1/llm/generations:
    post:
      tags:
        - LLM > llm-audio
      summary: Submit an LLM generation task (llm-audio protocol)
      description: >-
        Use the returned task ID to [query the
        task](/pages/en/api-manual/task-management/get-task-detail) for the
        final result.
      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: Task created
          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: >-
            [Get Model
            List](/pages/en/api-manual/text-series/llm-async/llm-generations-models)
          example: gemini-2.5-pro
        audio_url:
          type: string
          minLength: 1
          description: >-
            Audio source. Accepts one of the following two forms:

            - Publicly reachable HTTP/HTTPS URL

            - `data:audio/<type>;base64,<payload>` data URI (base64 inline)


            **Audio format support per family** (the specific available models
            are driven by channel configuration):

            - Gemini family (e.g. `gemini-*`): wav/mp3/aiff/aac/ogg/flac/m4a;
            total request body (prompt + system + inline files) ≤ 20 MB


            **Inline base64 (asynchronous mode only, when `sync` is omitted or
            `false`)**: Base64 recognized by the gateway as inline media
            (`data:` URI, or at least 4096 encoded characters whose decoded
            content matches a known media signature) is uploaded to file storage
            and replaced with a URL before the request is persisted or submitted
            upstream; the original base64 is not stored. Shorter raw base64 or
            content with an unrecognized signature is passed through unchanged
            and is not size-validated. Limits apply only to inline base64 items
            (public URLs are not limited): decoded size ≤ 5 MB per item. This
            field can contain at most one inline item, which still counts toward
            the shared per-request limits of ≤ 10 MB total and ≤ 20 inline
            items. An invalid `data:` prefix or payload that decodes to zero
            bytes returns 422; exceeding a limit also returns 422. Use
            `/v1/files/upload` first and pass the resulting URL instead.


            When `sync: true`, the request is not stored as a task and the rules
            above do not apply: inline base64 is submitted upstream unchanged
            without size or count validation.
          example: >-
            https://storage.googleapis.com/cloud-samples-tests/speech/brooklyn.flac
        prompt:
          type: string
          nullable: true
          maxLength: 100000
          description: >-
            User prompt. When omitted, defaults to `'Please transcribe this
            audio file'`, aligning with the transcription scenario.
          example: Identify the speakers and emotion in this audio.
        sync:
          type: boolean
          default: false
          description: >-
            Synchronous mode. When `true`, the endpoint blocks until the
            upstream completes and returns the full response (if `stream=true`
            at the same time, returns an SSE stream); when `false`, the endpoint
            returns the task ID immediately, and results are fetched via `GET
            /v1/tasks/{task_id}` or the SSE endpoint.
          example: false
        stream:
          type: boolean
          default: false
          description: >-
            Whether to stream. When `true`, the Submit response includes
            `stream.url` pointing to the SSE subscription path; streaming chunks
            are unified as the OpenAI `chat.completion.chunk` format.
          example: false
        max_tokens:
          type: integer
          nullable: true
          minimum: 1
          description: Generation token limit. Optional.
          example: 256
        temperature:
          type: number
          nullable: true
          minimum: 0
          maximum: 2
          description: Sampling temperature, range [0, 2]. Optional.
        system_prompt:
          type: string
          nullable: true
          maxLength: 10000
          description: System instruction. Optional.
        reasoning:
          type: boolean
          nullable: true
          description: >-
            Whether to include reasoning tokens. Some thinking models require
            this to be set to `true`.
    SubmitResponse:
      type: object
      description: >-
        Submit response, conforming to the unified task standard shape.
        `results` / `error` are fixed at `null` during submit; they are returned
        via `GET /v1/tasks/{task_id}` after the task completes or fails.
      required:
        - id
        - object
        - type
        - model
        - status
        - progress
        - created
      properties:
        id:
          type: string
          description: Task ID, formatted as `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: The model name submitted by the client (echoed verbatim)
          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: 'Returns `{url: ...}` when `stream=true`; `null` when `stream=false`.'
          oneOf:
            - $ref: '#/components/schemas/StreamInfo'
            - type: 'null'
        results:
          type: array
          nullable: true
          description: >-
            Fixed at `null` during submit; returned via `GET
            /v1/tasks/{task_id}` after the task completes — `results[0]` is the
            full OpenAI `ChatCompletion` response (audio transcription /
            understanding output is in `message.content`).
          items:
            type: object
          example: null
        error:
          type: object
          nullable: true
          description: >-
            Fixed at `null` during submit; returned via `GET
            /v1/tasks/{task_id}` when the task fails.
          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: No authentication token provided
            type:
              type: string
              example: authentication_error
    ErrorResponse422:
      type: object
      description: >-
        Parameter validation failure. Common `code`s: `invalid_param` (e.g. the
        audio_url format or data URI mime is not supported by the upstream),
        `model_not_support_capability` (no candidate channel declares the
        `audio` capability), `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: Request rate limit exceeded
            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 invalid or missing
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse401'
    UnprocessableEntity:
      description: >-
        Parameter validation failure (audio_url format or data URI mime not
        supported by upstream, no candidate channel declares the `audio`
        capability, model not registered, etc.)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse422'
    TooManyRequests:
      description: Request rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse429'
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse500'
    ServiceUnavailable:
      description: >-
        Upstream is unavailable, or the current deployment has not configured an
        upstream for this model
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse503'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        All endpoints require Bearer Token authentication. Add to the request
        header:


        `Authorization: Bearer YOUR_API_KEY`


        `YOUR_API_KEY` is the API Token (`sk-...` format).

````