openapi: 3.0.3
info:
  title: Hailuo AI / MiniMax 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.
  - name: Files
    description: Retrieve generated assets by file_id.
  - name: Text to Speech
    description: Speech synthesis (T2A v2).
  - name: Chat Completions
    description: OpenAI-compatible LLM chat completions.
  - name: Music Generation
    description: Vocal music generation from prompt and lyrics.
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'
  /files/retrieve:
    get:
      operationId: retrieveFile
      tags:
        - Files
      summary: Retrieve a generated file
      description: >-
        Retrieves a generated asset by file_id and returns a temporary download
        URL. For video, the returned URL is valid for roughly 9 hours (32,400
        seconds) before it expires.
      parameters:
        - name: file_id
          in: query
          required: true
          description: The file_id returned by a successful query response.
          schema:
            type: string
      responses:
        '200':
          description: File metadata including a temporary download_url.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileRetrieveResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /t2a_v2:
    post:
      operationId: createSpeech
      tags:
        - Text to Speech
      summary: Synthesize speech (T2A v2)
      description: >-
        Synchronous text-to-speech over HTTP using the speech-2.8 / speech-2.6 /
        speech-02 / speech-01 HD or turbo models. Text must be under 10,000
        characters. A real-time WebSocket variant is documented separately at
        wss://api.minimax.io/ws/v1/t2a_v2 (see the AsyncAPI document).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/T2ARequest'
      responses:
        '200':
          description: Synthesized audio (hex-encoded or a URL) plus metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/T2AResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /chat/completions:
    post:
      operationId: createChatCompletion
      tags:
        - Chat Completions
      summary: Create a chat completion
      description: >-
        OpenAI-compatible chat completions served by MiniMax's large language
        models (the MiniMax-M / abab family). Supports streaming, tool/function
        calling, and long context.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatCompletionRequest'
      responses:
        '200':
          description: A chat completion response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatCompletionResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /music_generation:
    post:
      operationId: createMusicGeneration
      tags:
        - Music Generation
      summary: Generate a vocal song (modeled)
      description: >-
        Generates a vocal song from a music-style description (prompt) plus
        lyrics. Endpoint path and payload are modeled from MiniMax's published
        music API; reconcile against the live reference.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MusicGenerationRequest'
      responses:
        '200':
          description: Generated audio (hex-encoded or a URL) plus metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MusicGenerationResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  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}`.
  responses:
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BaseResp'
  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
    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
    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'
    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'
    FileRetrieveResponse:
      type: object
      properties:
        file:
          type: object
          properties:
            file_id:
              type: string
              example: '205258526306433'
            bytes:
              type: integer
              example: 5242880
            created_at:
              type: integer
              example: 1731000000
            filename:
              type: string
              example: output.mp4
            purpose:
              type: string
              example: video_generation
            download_url:
              type: string
              description: >-
                Temporary download URL. For video, valid for about 9 hours
                (32,400 seconds).
              example: https://public-cdn.minimax.io/.../output.mp4
        base_resp:
          $ref: '#/components/schemas/BaseResp'
    T2ARequest:
      type: object
      required:
        - model
        - text
      properties:
        model:
          type: string
          enum:
            - speech-2.8-hd
            - speech-2.8-turbo
            - speech-2.6-hd
            - speech-2.6-turbo
            - speech-02-hd
            - speech-02-turbo
            - speech-01-hd
            - speech-01-turbo
          example: speech-2.6-hd
        text:
          type: string
          description: Text to synthesize; must be under 10,000 characters.
          example: Welcome to the API Evangelist network.
        stream:
          type: boolean
          example: false
        voice_setting:
          type: object
          properties:
            voice_id:
              type: string
              example: male-qn-qingse
            speed:
              type: number
              example: 1.0
            vol:
              type: number
              example: 1.0
            pitch:
              type: integer
              example: 0
        audio_setting:
          type: object
          properties:
            sample_rate:
              type: integer
              example: 32000
            bitrate:
              type: integer
              example: 128000
            format:
              type: string
              example: mp3
    T2AResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            audio:
              type: string
              description: Hex-encoded audio bytes (or a URL, per audio settings).
            status:
              type: integer
        extra_info:
          type: object
        base_resp:
          $ref: '#/components/schemas/BaseResp'
    ChatCompletionRequest:
      type: object
      required:
        - model
        - messages
      properties:
        model:
          type: string
          description: MiniMax LLM model identifier.
          example: MiniMax-M1
        messages:
          type: array
          items:
            type: object
            properties:
              role:
                type: string
                enum:
                  - system
                  - user
                  - assistant
                  - tool
              content:
                type: string
        stream:
          type: boolean
          example: false
        temperature:
          type: number
          example: 1.0
        max_tokens:
          type: integer
          example: 1024
        tools:
          type: array
          items:
            type: object
    ChatCompletionResponse:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          example: chat.completion
        created:
          type: integer
        model:
          type: string
        choices:
          type: array
          items:
            type: object
            properties:
              index:
                type: integer
              message:
                type: object
                properties:
                  role:
                    type: string
                  content:
                    type: string
              finish_reason:
                type: string
        usage:
          type: object
          properties:
            prompt_tokens:
              type: integer
            completion_tokens:
              type: integer
            total_tokens:
              type: integer
        base_resp:
          $ref: '#/components/schemas/BaseResp'
    MusicGenerationRequest:
      type: object
      required:
        - model
        - prompt
        - lyrics
      properties:
        model:
          type: string
          example: music-1.5
        prompt:
          type: string
          description: Music style / mood description.
          example: Upbeat synthwave with driving drums.
        lyrics:
          type: string
          description: Lyrics for the vocal track.
          example: '[verse] Neon lights over the city tonight'
        audio_setting:
          type: object
          properties:
            sample_rate:
              type: integer
              example: 44100
            bitrate:
              type: integer
              example: 256000
            format:
              type: string
              example: mp3
    MusicGenerationResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            audio:
              type: string
              description: Hex-encoded audio bytes (or a URL).
        base_resp:
          $ref: '#/components/schemas/BaseResp'