Execute AI Agent with Multi-Model Support

November 24, 2025

Table of contents

  1. Request Headers
  2. Request Body
  3. Responses
  4. Model
  5. Examples
  6. Try It

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. 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).

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 10 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
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

  • account is optional when only one account configured. However, if you have multiple accounts configured, this parameter becomes required.

  • prompt is required, describe your request to the AI agent.

  • models is 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/Pro
    • nano-banana - Nano Banana
    • seedream-4.0 - Seedream 4.0
    • f.1-kontext - F.1 Kontext
    • qwen - Qwen Image
    • kolors - Kolors

    Audio Models:

    • speech-2.5-hd-preview - Speech 2.5 HD Preview
    • speech-2.5-turbo-preview - Speech 2.5 Turbo Preview
    • minimax-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.

  • file is optional, attach reference files for the agent to process. You can upload multiple files.

  • async is optional. When set to true, the API returns immediately with a job ID and processes the request in the background. Default: false (synchronous).

  • replyUrl is optional, if not provided value from useapi.net account will be used. Place here your callback URL. API will call the provided replyUrl once 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.

  • replyRef is optional, place here your reference id which will be stored and returned along with this agent response/result. Maximum length 1024 characters.

Responses

  • 200 OK

    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"
                }
            },
            {
                "attachmentID": "att_987654321",
                "type": 2,
                "status": 3,
                "file": {
                    "fileName": "cat_piano_image.png",
                    "fileUrl": "https://cdn.hailuoai.video/...png",
                    "type": "image/png"
                }
            }
        ]
    }
}

  • 201 Created

    Agent task created and processing in background (asynchronous mode with async: true).

    Use the returned jobId to 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"
    }
}

  • 400 Bad Request

    Invalid request parameters.

    {
  "error": "Error …",
  "code": 400
}

  • 401 Unauthorized

    {
  "error": "Unauthorized",
  "code": 401
}

  • 422 Unprocessable Content

    Moderated content or invalid file.

    {
  "error": "Your prompt contains content that violates our policies"
}

  • 429 Too Many Requests

    Dynamic capacity limit reached. Wait for at least one job to complete (or wait ~30 seconds) and try again.

    {
  "error": "Agent generation failed"
}

  • 500 Internal Server Error

    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
  }
}

  • 504 Gateway Timeout

    Agent task timed out after 10 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 
{
  // 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?: Record<string, any>  // Additional file metadata
        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?: Record<string, any>     // Node information (if applicable)
    }>
  }

  // 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'])
Try It