Execute AI Agent with Multi-Model Support
November 24, 2025 (November 26, 2025)
Table of contents
Execute MiniMax AI Agent with support for multiple AI models including video generation (Hailuo 2.3, 02), image generation (Nano Banana 2/Pro, Seedream 4.0, F.1 Kontext, Qwen, Kolors), and audio synthesis (Speech 2.5, Music 2.0).
The agent API can operate in synchronous or asynchronous mode.
Be very specific in your prompt about the type of content you want to generate. Explicitly state “generate a video”, “generate an image”, or “generate a song based on my lyrics” to ensure the agent uses the correct model from your provided list. You can also specify aspect ratio and resolution directly in your prompt, e.g., “create 1:1 4K image of a sunset” or “generate 16:9 video of waves”. Without clear instructions, the agent may choose a different model or generate unexpected content type (e.g., generating a video when you wanted an image). To verify which model was actually used along with the resolution and aspect ratio, check the file.extra fields in the response (see Model section for model_name, model_aspect_ratio, model_resolution fields).
This endpoint features dynamic capacity limits. If you receive a 429 response, wait for at least one job to complete (or wait ~30 seconds) and try again. Use GET agent/jobs to monitor running jobs.
Execution Times:
- Simple one-step tasks: 20-60 seconds
- Medium complexity tasks: 60 seconds to 2 minutes
- Multi-step complex tasks with multiple models: 5+ minutes
- Jobs expire after 15 minutes
Use hailuoai.video account to execute agent tasks, see Setup MiniMax for details.
Note:
Model nano-banana-2 Nano Banana 2/Pro has less content moderation compared to Google Flow and is capable of editing photos of minors or famous people. Use responsibly and in compliance with applicable laws and regulations.
https://api.useapi.net/v1/minimax/agent
Request Headers
Authorization: Bearer {API token}
Content-Type: multipart/form-data
API tokenis required, see Setup useapi.net for details.
Request Body
Below is a FormData multipart/form-data example using Postman notation:
| Key | Type | Value (example) |
|---|---|---|
| account | Text | Optional MiniMax API account |
| prompt | Text | Generate a video of a cat playing |
| models | Text | hailuo-2.3,nano-banana-2 |
| file | File | «Reference.jpg» |
| file | File | «Style.png» |
| async | Text | false |
| replyUrl | Text | https://webhook.site/your-id |
| replyRef | Text | my-task-123 |
-
accountis optional when only one account configured. However, if you have multiple accounts configured, this parameter becomes required. -
promptis required, describe your request to the AI agent. -
modelsis required, comma-separated list of AI models to use. Supported models:Video Models:
hailuo-2.3- Hailuo 2.3 (highest quality)hailuo-2.3-fast- Hailuo 2.3-Fast (faster generation)hailuo-02- Hailuo 02
Image Models:
nano-banana-2- Nano Banana 2/Pronano-banana- Nano Bananaseedream-4.0- Seedream 4.0f.1-kontext- F.1 Kontextqwen- Qwen Imagekolors- Kolors
Audio Models:
speech-2.5-hd-preview- Speech 2.5 HD Previewspeech-2.5-turbo-preview- Speech 2.5 Turbo Previewminimax-music-2.0- MiniMax Music 2.0
Example:
"hailuo-2.3,nano-banana-2"will use both Hailuo 2.3 video and Nano Banana 2/Pro image models. -
fileis optional, attach reference files for the agent to process. You can upload multiple files. -
asyncis optional. When set totrue, the API returns immediately with a job ID and processes the request in the background. Default:false(synchronous). -
replyUrlis optional, if not provided value from useapi.net account will be used. Place here your callback URL. API will call the providedreplyUrlonce the agent task is completed or failed. The callback payload format matches the response Model shown below. Maximum length 1024 characters. We recommend using sites like webhook.site to test callback URL functionality. -
replyRefis optional, place here your reference id which will be stored and returned along with this agent response/result. Maximum length 1024 characters.
Responses
-
Agent task completed successfully (synchronous mode).
{ "jobId": "p123456789-u12345-a67890-bot:minimax", "status": "completed", "created": "2025-11-24T12:34:56.789Z", "request": { "account": "67890", "prompt": "Generate a video of a cat playing piano", "models": [ "hailuo-2.3", "nano-banana-2" ], "replyUrl": "https://webhook.site/your-webhook-id", "replyRef": "my-task-123" }, "response": { "projectID": "123456789", "sectionID": "987654321", "chatID": "456789123", "msg_content": "I've generated a video of a cat playing piano and an image variation.", "timestamp": 1732366496789, "elapsedTime": "02:15", "attachments": [ { "attachmentID": "att_123456789", "type": 1, "status": 3, "file": { "fileName": "cat_piano_video.mp4", "fileUrl": "https://cdn.hailuoai.video/...mp4", "type": "video/mp4", "extra": { "width": "1280", "height": "720", "duration": "5.0", "fps": "24", "no_watermark_url": "https://cdn.hailuoai.video/.../no_watermark.mp4", "watermark_url": "https://cdn.hailuoai.video/.../watermark.mp4", "thumbnail_url": "https://cdn.hailuoai.video/.../thumb.jpg" } } }, { "attachmentID": "att_987654321", "type": 2, "status": 3, "file": { "fileName": "cat_piano_image.png", "fileUrl": "https://cdn.hailuoai.video/...png", "type": "image/png", "extra": { "model_name": "banana_2", "model_aspect_ratio": "16:9", "model_resolution": "1K" } } } ] } } -
Agent task created and processing in background (asynchronous mode with
async: true).Use the returned
jobIdto check status via GET agent/jobId.{ "jobId": "p987654321-u12345-a67890-bot:minimax", "status": "started", "created": "2025-11-24T12:30:00.000Z", "request": { "account": "67890", "prompt": "Generate a video of a cat playing piano", "models": [ "hailuo-2.3" ], "async": true, "replyUrl": "https://webhook.site/your-webhook-id", "replyRef": "my-task-456" }, "response": { "projectID": "987654321", "sectionID": "123456789", "chatID": "456789012" } } -
Invalid request parameters.
{ "error": "Error …", "code": 400 } -
{ "error": "Unauthorized", "code": 401 } -
Moderated content or invalid file.
{ "error": "Your prompt contains content that violates our policies" } -
Dynamic capacity limit reached. Wait for at least one job to complete (or wait ~30 seconds) and try again.
{ "error": "Agent generation failed" } -
Agent execution failed.
{ "jobId": "p123456789-u12345-a67890-bot:minimax", "status": "failed", "created": "2025-11-23T12:34:56.789Z", "request": { "prompt": "Generate a video", "models": ["hailuo-2.3"] }, "error": { "message": "Agent connection error", "status": 500 } } -
Agent task timed out after 15 minutes.
{ "jobId": "p123456789-u12345-a67890-bot:minimax", "status": "failed", "created": "2025-11-23T12:34:56.789Z", "request": { "prompt": "Generate a video", "models": ["hailuo-2.3"] }, "error": { "message": "Timeout waiting for assistant response", "status": 504 } } -
596 Pending mod message
Your hailuoai.video account has been placed on hold, which may last a few hours. It may be a good idea to pause operations until then. You can reach out to the Discord support channel or send an email requesting your account to be unlocked. Based on the information we have gathered, this seems to be a temporary ban that will automatically unlock in just a few hours.
{ "error": "Unusual account activities detected. Please contact customer support at [email protected]" }
Model
response.attachments[].file.fileUrl- primary download URL (may have watermark)response.attachments[].file.extra.no_watermark_url- URL without watermark (when available)response.attachments[].file.extra.watermark_url- URL with watermarkresponse.attachments[].node.agentFile.noWatermarkUrl- alternative watermark-free URLresponse.attachments[].node.agentFile.url- alternative file URL
{
// Job metadata
jobId: string // Unique job identifier
status: 'started' | 'completed' | 'failed' // Job status
created: string // ISO 8601 timestamp
code?: number // HTTP status code (optional)
// Original request
request: {
prompt: string // User's prompt
file?: Array<{ // File metadata (actual files not included)
name: string
size: number
type: string
}>
models: string[] // Model IDs used
async?: boolean // Async mode flag
replyUrl?: string // Callback URL
replyRef?: string // User's reference ID
}
// Agent response (only present on completion)
response?: {
projectID: string // MiniMax project ID
sectionID: string // MiniMax section ID
chatID: string // MiniMax chat ID
msg_content: string // Agent's response message
timestamp: number // Response timestamp (milliseconds since epoch)
elapsedTime: string // Elapsed time (mm:ss format)
attachments?: Array<{ // Generated files
attachmentID: string // Attachment identifier
type: number // Attachment type (numeric)
status: number // Attachment status (3 = completed)
file: {
fileName: string // File name
fileUrl: string // CDN URL to download file
extra?: { // Additional file metadata
// Video-specific fields
height?: string // Video height in pixels
width?: string // Video width in pixels
duration?: string // Duration in seconds
fps?: string // Frames per second
frames?: string // Total frame count
no_watermark_url?: string // CDN URL without watermark
watermark_url?: string // CDN URL with watermark
thumbnail_url?: string // Thumbnail image URL
url?: string // Alternative URL
path?: string // File path
task_id?: string // Generation task ID
vendor?: string // Video generation vendor
subtitle_path?: string // Subtitle file path
// Image-specific fields (nano-banana-2 model)
model_aspect_ratio?: string // e.g. "9:16", "16:9"
model_name?: string // e.g. "banana_2"
model_resolution?: string // e.g. "1K", "2K"
// Audio/TTS-specific fields
format?: string // e.g. "mp3"
type?: string // e.g. "audio"
model_speech_count?: string // Character count for TTS
}
posterUrl?: string // Poster/thumbnail URL
type?: string // File MIME type
referenceType?: number // Reference type
}
text?: string // Associated text content
extra?: Record<string, any> // Additional metadata
node?: { // Node/timeline information
nodeID: string // Unique node identifier
xStart: number // X position start
yStart: number // Y position start
width: number // Node width
height: number // Node height
layer: number // Layer index
nodeType: number // Node type identifier
agentFile?: { // Generated file details
id: string // File ID
name: string // File name
url: string // File URL
coverInfo?: { // Cover image info
coverURL: string // Cover image URL
}
noWatermarkUrl?: string // URL without watermark
duration?: number // Duration in seconds
relativePath?: string // Relative file path
thumbnailUrl?: string // Thumbnail URL
}
status: number // Node status
playWidth: number // Playback width
playHeight: number // Playback height
logoType: number // Logo type identifier
}
}>
}
// Error information (only present on failure)
error?: string | { // Error can be a string or object
message: string // Error description
status: number // HTTP status code
details?: any // Additional error details
}
}
Examples
-
# Synchronous request curl -H "Authorization: Bearer YOUR_API_TOKEN" \ -F "prompt=Generate a video of a cat playing piano" \ -F "models=hailuo-2.3,nano-banana-2" \ "https://api.useapi.net/v1/minimax/agent" # Asynchronous request curl -H "Authorization: Bearer YOUR_API_TOKEN" \ -F "prompt=Generate a video of a cat playing piano" \ -F "models=hailuo-2.3" \ -F "async=true" \ -F "replyUrl=https://webhook.site/your-webhook-id" \ "https://api.useapi.net/v1/minimax/agent" # With file upload curl -H "Authorization: Bearer YOUR_API_TOKEN" \ -F "prompt=Generate a video using this reference" \ -F "models=hailuo-2.3" \ -F "file=@/path/to/reference.jpg" \ "https://api.useapi.net/v1/minimax/agent" -
const token = "YOUR_API_TOKEN"; const apiUrl = "https://api.useapi.net/v1/minimax/agent"; // Synchronous request const formData = new FormData(); formData.append('prompt', 'Generate a video of a cat playing piano'); formData.append('models', 'hailuo-2.3,nano-banana-2'); const response = await fetch(apiUrl, { method: 'POST', headers: { 'Authorization': `Bearer ${token}` }, body: formData }); const result = await response.json(); console.log("Job completed:", result); if (result.response?.attachments) { result.response.attachments.forEach(att => { console.log(`${att.file.fileName}: ${att.file.fileUrl}`); }); } // Asynchronous request const asyncFormData = new FormData(); asyncFormData.append('prompt', 'Generate a video of a cat playing piano'); asyncFormData.append('models', 'hailuo-2.3'); asyncFormData.append('async', 'true'); asyncFormData.append('replyUrl', 'https://webhook.site/your-webhook-id'); const asyncResponse = await fetch(apiUrl, { method: 'POST', headers: { 'Authorization': `Bearer ${token}` }, body: asyncFormData }); const asyncResult = await asyncResponse.json(); console.log("Job ID:", asyncResult.jobId); -
import requests token = "YOUR_API_TOKEN" api_url = "https://api.useapi.net/v1/minimax/agent" headers = { "Authorization": f"Bearer {token}" } # Synchronous request data = { "prompt": "Generate a video of a cat playing piano", "models": "hailuo-2.3,nano-banana-2" } response = requests.post(api_url, headers=headers, data=data) result = response.json() print("Job completed:", result) if result.get('response', {}).get('attachments'): for att in result['response']['attachments']: print(f"{att['file']['fileName']}: {att['file']['fileUrl']}") # Asynchronous request async_data = { "prompt": "Generate a video of a cat playing piano", "models": "hailuo-2.3", "async": "true", "replyUrl": "https://webhook.site/your-webhook-id" } async_response = requests.post(api_url, headers=headers, data=async_data) async_result = async_response.json() print("Job ID:", async_result['jobId'])