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}`.'