Hailuo AI / MiniMax Video Generation API

openapi: 3.0.3
info:
  title: Hailuo AI / MiniMax Chat Completions Video Generation API
  description: 'Documented HTTP APIs for MiniMax''s Hailuo generative video and audio platform. The primary surface is AI video generation (Hailuo models), which follows an asynchronous three-step pattern: create a task (POST /video_generation) to receive a task_id, poll status (GET /query/video_generation) until it returns a file_id, then retrieve the file (GET /files/retrieve) to obtain a temporary download URL for the finished MP4. The same platform also serves text-to-speech (T2A), OpenAI-compatible chat completions, and music generation. All endpoints authenticate with a Bearer API key from the MiniMax console.

    Video generation endpoints, methods, the async task/query/retrieve flow, model names, and core parameters are grounded in MiniMax''s published documentation. Request and response schemas are modeled to reflect the documented fields; treat exact field-level shapes as approximate and reconcile against the live API reference. The text-to-speech, chat-completions, and music-generation request bodies are modeled representative payloads.'
  version: '1.0'
  contact:
    name: MiniMax
    url: https://platform.minimax.io
  x-endpointsModeled: true
  x-endpointsModeledNote: Video generation, query, and file-retrieve endpoints, HTTP methods, model names, and the async workflow are confirmed from live MiniMax docs. Detailed JSON schemas, and the music-generation endpoint payload, are honestly modeled and should be reconciled against the official reference before production use.
servers:
- url: https://api.minimax.io/v1
  description: MiniMax International (global)
- url: https://api-uw.minimax.io/v1
  description: MiniMax International - US West (lower time-to-first-audio for T2A)
- url: https://api.minimaxi.chat/v1
  description: MiniMax Mainland China
security:
- bearerAuth: []
tags:
- name: Video Generation
  description: Asynchronous AI video generation with the Hailuo models.
paths:
  /video_generation:
    post:
      operationId: createVideoGenerationTask
      tags:
      - Video Generation
      summary: Create a video generation task
      description: Submits a video generation request and returns a task_id. Supports text-to-video (prompt only), image-to-video (first_frame_image), first-and-last-frame video (first_frame_image + last_frame_image), and subject-reference video (subject_reference for face-consistent characters). The task is processed asynchronously; poll GET /query/video_generation with the returned task_id.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VideoGenerationRequest'
      responses:
        '200':
          description: Task accepted. Returns a task_id for polling.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoGenerationCreateResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /query/video_generation:
    get:
      operationId: queryVideoGenerationTask
      tags:
      - Video Generation
      summary: Query a video generation task
      description: Checks the status of a video generation task by task_id. Status progresses through Queueing, Preparing, Processing, then Success (which includes a file_id) or Fail. A polling interval of about 10 seconds is recommended to avoid unnecessary load.
      parameters:
      - name: task_id
        in: query
        required: true
        description: The task_id returned by POST /video_generation.
        schema:
          type: string
      responses:
        '200':
          description: Current task status, plus file_id when the task has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoGenerationQueryResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    BaseResp:
      type: object
      description: Standard MiniMax response status wrapper.
      properties:
        status_code:
          type: integer
          description: 0 indicates success; non-zero indicates an error.
          example: 0
        status_msg:
          type: string
          example: success
    VideoGenerationQueryResponse:
      type: object
      properties:
        task_id:
          type: string
          example: '106916112212032'
        status:
          type: string
          description: Task status.
          enum:
          - Queueing
          - Preparing
          - Processing
          - Success
          - Fail
          example: Success
        file_id:
          type: string
          description: Present when status is Success; pass to GET /files/retrieve to obtain the download URL.
          example: '205258526306433'
        base_resp:
          $ref: '#/components/schemas/BaseResp'
    VideoGenerationCreateResponse:
      type: object
      properties:
        task_id:
          type: string
          description: Identifier used to poll GET /query/video_generation.
          example: '106916112212032'
        base_resp:
          $ref: '#/components/schemas/BaseResp'
    VideoGenerationRequest:
      type: object
      required:
      - model
      properties:
        model:
          type: string
          description: Video model to use.
          enum:
          - MiniMax-Hailuo-2.3
          - MiniMax-Hailuo-2.3-Fast
          - MiniMax-Hailuo-02
          - Video-01
          - T2V-01
          - I2V-01
          - S2V-01
          example: MiniMax-Hailuo-2.3
        prompt:
          type: string
          description: Describes the video content and motion.
          example: A cinematic drone shot flying over a neon-lit city at night.
        first_frame_image:
          type: string
          description: URL (or base64 data URI) of the starting frame for image-to-video and first-and-last-frame modes.
        last_frame_image:
          type: string
          description: URL of the ending frame for first-and-last-frame mode.
        subject_reference:
          type: array
          description: Character face reference(s) for subject-reference mode, giving facial consistency across the generated video.
          items:
            type: object
            properties:
              type:
                type: string
                example: character
              image:
                type: array
                items:
                  type: string
                  description: URL(s) of the reference face photo.
        duration:
          type: integer
          description: Video length in seconds (e.g. 6 or 10, model dependent).
          example: 6
        resolution:
          type: string
          description: Output resolution, model dependent (e.g. 512P, 768P, 1080P).
          example: 1080P
        prompt_optimizer:
          type: boolean
          description: When true, MiniMax automatically refines the prompt.
          example: true
  responses:
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BaseResp'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Bearer API key created in the MiniMax platform console under Account Management > API Keys. Passed as `Authorization: Bearer {api_key}`.'