Retrieves generated assets by file_id (GET /files/retrieve), returning a temporary download URL - video URLs are valid for roughly 9 hours (32,400 seconds). Used to fetch the finished MP4 after a video task completes, and to manage uploaded inputs.
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'