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

# Image 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-vision.json POST /v1/llm/generations
openapi: 3.1.0
info:
  title: LLM · llm-vision protocol
  version: '1.0'
  description: >-
    Request format of the unified LLM entrypoint **`llm-vision`**: `prompt` +
    `image_urls[]` (1–10 images) → vision understanding.


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

    - `llm-text`: `prompt` only

    - `llm-vision` (this file): `prompt` + `image_urls[]`

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

    - `llm-audio`: `audio_url`

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


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

    - HTTP/HTTPS URL (publicly reachable)

    - `data:image/<png|jpeg|webp|gif>;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-vision
      summary: Submit an LLM generation task (llm-vision 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-vision
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LLMVisionRequest'
            examples:
              example_0:
                summary: Async — describe an image
                value:
                  model: claude-opus-4-7
                  prompt: Describe this image in one sentence.
                  image_urls:
                    - https://fal.media/files/lion/AOtzfcyHpx-MOITAUeMrK.jpeg
                  max_tokens: 64
              example_1:
                summary: Sync streaming — multi-image
                value:
                  model: gemini-2.5-pro
                  prompt: What is common to all of these images?
                  image_urls:
                    - https://fal.media/files/lion/AOtzfcyHpx-MOITAUeMrK.jpeg
                    - https://fal.media/files/penguin/QxEROl7HcfUomtBEkSYXG.jpg
                  sync: true
                  stream: true
              example_2:
                summary: >-
                  Inline base64 image (data URI) — works on flaky upstream
                  egress
                value:
                  model: gemini-2.5-pro
                  prompt: Describe in one word.
                  image_urls:
                    - >-
                      data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR4nGNgAAIAAAUAAen63NgAAAAASUVORK5CYII=
                  max_tokens: 8
      responses:
        '200':
          description: Task created (async mode) / full response (sync mode)
          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: claude-opus-4-7
                    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:
    LLMVisionRequest:
      type: object
      required:
        - model
        - prompt
        - image_urls
      additionalProperties: true
      properties:
        model:
          type: string
          description: >-
            [Get Model
            List](/pages/en/api-manual/text-series/llm-async/llm-generations-models)
          example: claude-opus-4-7
        prompt:
          type: string
          maxLength: 100000
          description: User prompt, up to 100,000 characters.
          example: Describe this image in one sentence.
        image_urls:
          type: array
          minItems: 1
          maxItems: 10
          description: >-
            Array of image sources (1–10 images). Each element accepts one of
            the following two forms:

            - Publicly reachable HTTP/HTTPS URL

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


            **Model constraints**: the maximum count is determined by the
            upstream behind the selected model; when a model supports only a
            single image but the request passes multiple, the routing layer
            returns 422 `model_rule_violation` (the specific rules are
            maintained in `app/relays/llm_router/model_rules.py`, covering
            "model-intrinsic" constraints beyond channel configuration).


            **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 HTTP(S) URLs are not limited): decoded size ≤ 5 MB per item,
            ≤ 5 inline items per array, ≤ 10 MB total per request, and ≤ 20
            inline items per request. 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.
          items:
            type: string
          example:
            - https://fal.media/files/lion/AOtzfcyHpx-MOITAUeMrK.jpeg
        sync:
          type: boolean
          default: false
          description: Synchronous mode (see llm-text schema).
          example: false
        stream:
          type: boolean
          default: false
          description: Whether to stream (see llm-text schema).
          example: false
        max_tokens:
          type: integer
          nullable: true
          minimum: 1
          description: Generation token limit. Optional.
          example: 64
        temperature:
          type: number
          nullable: true
          minimum: 0
          maximum: 2
          description: Sampling temperature, range [0, 2]. Optional.
          example: 0.3
        system_prompt:
          type: string
          nullable: true
          maxLength: 10000
          description: System instruction. Optional.
          example: You are a vision assistant.
        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. In
        `sync=true, stream=false` mode, the endpoint directly returns the full
        OpenAI ChatCompletion JSON.
      required:
        - id
        - object
        - type
        - model
        - status
        - progress
        - created
      properties:
        id:
          type: string
          description: Task ID, formatted as `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: The model name submitted by the client (echoed verbatim)
          example: claude-opus-4-7
        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.
          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-llmrouter-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: `model_rule_violation`
        (hit a model's inherent rule, e.g. a single-image model received
        multiple), `model_not_support_capability` (no candidate channel declares
        the `vision` capability), `model_not_registered`, `invalid_param`,
        `upstream_client_error`.
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              example: >-
                model 'xxx' only accepts a single image_url; received
                image_urls.length=3
            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: 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: 'all 3 candidates exhausted; last error: ...'
            type:
              type: string
              example: upstream_error
            code:
              type: string
              example: all_platforms_exhausted
  responses:
    Unauthorized:
      description: Token invalid or missing
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse401'
    UnprocessableEntity:
      description: >-
        Parameter validation failure / model intrinsic constraint (e.g. a
        single-image model received multiple) / no candidate channel declares
        the `vision` capability / model not registered / upstream 4xx
      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 service unavailable
      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).

````