=== useapi.net — universal note ===

Generated: 2026-09-11 20:33 UTC

Authentication (applies to every useapi.net API).
  Header: Authorization: Bearer user:<number>-<unique-string>
  Use the COMPLETE token, including the `user:` prefix and the alphanumeric
  suffix. Do not truncate. Do not URL-encode. A single token authorizes every
  API under the user's subscription.

Service-specific patterns. Identifier names (jobid / taskId / musicId / etc.),
job lifecycle, response shapes, webhook semantics, and synchronous-vs-async
behavior vary PER API. Use ONLY the service-specific documentation below to
determine the correct request body, response shape, polling endpoint, and
status values for THIS API. Do not assume conventions from another useapi.net
API carry over.

For cross-service context (e.g. which APIs expose the same underlying model,
billing tiers, model availability matrix), see https://useapi.net/llms.txt

=== END universal note ===

=== URL: https://useapi.net/docs/start-here/setup-minimax ===
Document URL: https://useapi.net/docs/start-here/setup-minimax
---
layout: default
title: Setup MiniMax
description: "How to set up MiniMax (Hailuo) for the useapi.net API — connect your account and start generating via the API."
parent: Start Here
nav_order: 350
---
# <img style="height:1.5em;vertical-align: middle;" src="/assets/images/minimax.png"> Setup MiniMax | Hailuo AI
<small>September 25, 2024 (November 24, 2025)</small>

## Table of contents
<small>Approximately 5 minutes to complete setup steps.</small>  

---
> This is the setup guide for [MiniMax API](/docs/api-minimax-v1). A [Hailuo AI](https://hailuoai.video) account and a [useapi.net subscription](/docs/subscription) are required for the API to work.

### Connect your account (recommended)

Link your Hailuo account right in your own browser — a quick copy-and-paste, with no software to install and no remote setup. It runs entirely on your own machine and never touches your Google login.

[Open the connect page](/assets/setup-browser/minimax.html)

<small>Prefer to do it by hand? Continue with the manual steps below.</small>

---

## Setup <b>hailuoai.video</b> account

You need a [hailuoai.video](https://hailuoai.video) account to to use MiniMax API. Sign-in with your Google account at [hailuoai.video](https://hailuoai.video). You can create as many accounts as you need. Our API uses automated load balancing and will select an account with available capacity.

### Step 1 • Navigate to hailuoai.video

Open Chromium-compatible browser (e.g. [Google Chrome](https://www.google.com/chrome/), [Microsoft Edge](https://www.microsoft.com/en-us/edge) or [Opera](https://www.opera.com/)) and navigate to [https://hailuoai.video](https://hailuoai.video). 

Once the page is fully loaded, ensure that you're logged in with your Google account <span style="color: red;">`1`</span>.

Open [Developer Tools](https://developer.chrome.com/docs/devtools) by right-clicking on the page and selecting "Inspect Element" <span style="color: red;">`2`</span>.

Finally refresh page <span style="color: red;">`3`</span>.

![](/assets/images/minimax_video_setup_1.png)

### Step 2 • Locate `url`

Select Developer Tools » Network <span style="color: red;">`1`</span>:  
* On the left side many click on  `Assets` submenu <span style="color: red;">`2`</span>.  
* Type `/cursor` in the filter box <span style="color: red;">`3`</span> and hit Enter.  
* Make sure that `All`  or `Fetch/XHR` is selected <span style="color: red;">`4`</span>.  
* You should see a http call(s) entry as shown below <span style="color: red;">`5`</span>, click on that entry.  
* Select "Headers" tab <span style="color: red;">`6`</span>.  
* Locate General » Request URL <span style="color: red;">`7`</span> as shown below and copy its value. This is your `url`.

[EXPAND](/assets/images/minimax_video_setup_2.png){:target="_blank"}
![](/assets/images/minimax_video_setup_2.png)

As an example below the `url` is 

```
https://hailuoai.video/v3/api/multimodal/video/my/cursor?type=next&currentID=0&limit=30&scene=mine&filterType=2&device_platform=web&app_id=3001&version_code=22202&biz_id=0&lang=en&uuid=8a2d8b5d-ac0d-4bb5-8028-3177fa64f861&device_id=301350748241866752&os_name=Windows&browser_name=opera&device_memory=8&cpu_core_num=12&browser_language=en-US&browser_platform=Win32&screen_width=1920&screen_height=1080&unix=1728704107000
```

### Step 3 • Locate `token` value

Locate Request Headers » Token <span style="color: red;">`7`</span> as shown below and copy it's value. This is your `token`.  

[EXPAND](/assets/images/minimax_video_setup_3.png){:target="_blank"}
![](/assets/images/minimax_video_setup_3.png)

As an example below the `token` is 

```
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3MzIxNTk4MjksInVzZXIiOnsiaWQiOiIzMDEzNDg0MDk1ODE4MzgzMzYiLCJuYW1lIjoidXNlIGFwaSIsImF2YXRhciI6Imh0dHBzOi8vbGgzLmdvb2dsZXVzZXJjb250ZW50LmNvbS9hL0FDZzhvY0lLNEJaMmpfSlIxcTh3TkFKU2RlZzlwVHZlTDJTSVhFRjg4TkU4MV85VlowbFBRQT1zOTYtYyIsImRldmljZUlEIjoiIn19.1-zGnbUfENnVdjDGDBuaZ4Sf7rTelfqUKk5XNj7liE4
```

If you are curious, you can use [jwt.io](https://jwt.io) to decode the token and see its content.

## Verify and add account

Use the form below to verify your credentials and add your MiniMax account.

Select **Add Account** to complete setup, or **Verify** to test your credentials first. You should receive response `200` if successful. You can also use [POST /accounts](/docs/api-minimax-v1/post-minimax-accounts-account) directly.

<script>
  async function apiTestAccountMiniMax(addAccount) {
      data = {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${document.getElementById('post-accounts-MiniMax-api_token').value}`,
          'Content-Type': 'application/json'
        }
      };

      let url = document.getElementById(`post-accounts-MiniMax-url`)?.value;
      let token = document.getElementById(`post-accounts-MiniMax-token`)?.value;

      url = url && url.length ? url : undefined;
      token = token && token.length ? token : undefined;

      const body = { token, url, maxJobs: 3 };
      if (!addAccount) body.dryRun = true;
      data.body = JSON.stringify(body);

      await apiExecute(`https://api.useapi.net/v1/minimax/accounts`, 'post-accounts-MiniMax', data);
  }
</script>

<form id="post-accounts-MiniMax" onsubmit="apiTestAccountMiniMax(document.getElementById('post-accounts-MiniMax-action').value === 'add'); return false;" class="input-form">
  <div class="input-field">
    <div class="input-field-row">
      <label for="post-accounts-MiniMax-api_token"><span>API Token<small> (see <a href="/docs/start-here/setup-useapi">Setup useapi.net</a>)</small></span>
        <input id="post-accounts-MiniMax-api_token" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length">
      </label>
      <label for="post-accounts-MiniMax-url"><span>url&nbsp;&nbsp;&nbsp;</span>
        <input id="post-accounts-MiniMax-url" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length">
      </label>
      <label for="post-accounts-MiniMax-token"><span>token</span>
        <input id="post-accounts-MiniMax-token" type="text" class="input-element" required aria-required="true" oninput="this.size = this.value.length">
      </label>
      <label for="post-accounts-MiniMax-action"><span>action</span>
        <select id="post-accounts-MiniMax-action" class="input-element">
          <option value="verify">Verify — test credentials only</option>
          <option value="add">Add Account — required to complete setup</option>
        </select>
      </label>
    </div>
    <button id="post-accounts-MiniMax-button" class="btn btn-primary fs-3" type="submit">Go</button>
  </div>
</form>

<div id="post-accounts-MiniMax-response" class="response-placeholder visible-false"></div>

=== URL: https://useapi.net/docs/api-minimax-v1 ===
Document URL: https://useapi.net/docs/api-minimax-v1
---
layout: default
title: MiniMax API v1
description: "useapi.net MiniMax (Hailuo) API v1 — REST API for MiniMax / Hailuo AI: 19 video models across Hailuo 01/02/2.3, Hailuo 3.0, Veo 3.1, Sora 2 and Seedance 2.0 (Standard/Fast/Mini), image generation (Midjourney, Nano Banana, GPT Image, Seedream), music generation with Music-3.0 and Music-2.6, and text to speech with ten Speech models and voice cloning."
nav_order: 3000
has_children: true
permalink: /docs/api-minimax-v1
---

# <img style="height:1.5em;vertical-align: middle;" src="/assets/images/minimax.png"> MiniMax API v1

<small>September 25, 2024 (August 24, 2026)</small>

This is [experimental](/docs/legal) API for for the [MiniMax AI](https://minimaxi.com), a Chinese AI startup backed by Alibaba and Tencent. 

We provide full API support for following MiniMax/Hailuo AI models:
* MiniMax [videos](/docs/api-minimax-v1/post-minimax-videos-create) supports 19 models across 5 families: [Hailuo 01/02/2.3](https://hailuoai.video), [Hailuo 3.0](https://hailuoai.video), [Veo 3.1](https://deepmind.google/models/veo/), [Sora 2](https://openai.com/sora/), and [Seedance 2.0 Standard/Fast/Mini](https://seed.bytedance.com/). These models are notable for generating ultra-realistic video clips with precise prompt following.
* MiniMax [images](/docs/api-minimax-v1/post-minimax-images-create) supports 9 models: [Midjourney V7](https://www.midjourney.com/), [Midjourney NiJi 7](https://www.midjourney.com/), [Nano Banana 2](https://hailuoai.video), [Nano Banana Pro](https://blog.google/technology/ai/nano-banana-pro/), [GPT Image 1.5](https://openai.com/index/introducing-4o-image-generation/), [GPT Image 2](https://openai.com/index/introducing-4o-image-generation/), [Seedream 4.5/5.0](https://seed.bytedance.com/en/seedream4_5), and image-01.
* MiniMax [agent](/docs/api-minimax-v1/post-minimax-agent) supports multiple AI models including video generation ([Hailuo 2.3](https://hailuoai.video/ai-video-landing/ai-video-generator-hailuo-2-3), [02](https://www.minimax.io/news/minimax-hailuo-02), [Veo 3.1](https://deepmind.google/models/veo/), [Sora 2](https://openai.com/sora/)), image generation ([Midjourney V7/NiJi 7](https://www.midjourney.com/), [Nano Banana 2/Pro](https://blog.google/technology/ai/nano-banana-pro/), [Seedream 4.5/5.0](https://seed.bytedance.com/en/seedream4_5), [Kontext](https://bfl.ai/models/flux-kontext), [Qwen](https://github.com/QwenLM/Qwen-Image), Kolors), and audio synthesis ([Speech 2.5](https://minimax-ai.chat/models/minimax-speech-25/), [Music 2.0](https://www.minimax.io/news/minimax-music-20)).
* MiniMax [music](/docs/api-minimax-v1/post-minimax-music-create) generates complete songs — vocals and instrumental — with [Music-3.0](https://www.minimax.io/audio/music) and Music-2.6. Write your own lyrics or let the model write them from your prompt, and stream the audio back while it renders. Upload a track as a [reference](/docs/api-minimax-v1/post-minimax-music-reference) and the model covers it, keeping the melody and structure while your prompt sets the genre.
* MiniMax [speech](/docs/api-minimax-v1/post-minimax-speech-create) turns text into narration with ten models, [Speech-2.8](https://www.minimax.io/audio/text-to-speech) down to Speech-01, in `hd` and `turbo` variants. Mark the text up with emotions, breaths and pauses, get word timings back for captions, and [clone a voice](/docs/api-minimax-v1/post-minimax-speech-clone-voice) from a sample to narrate in it. [GET speech/voices](/docs/api-minimax-v1/get-minimax-speech-voices) lists 600+ voices across 40 languages, and MiniMax keeps adding.
  
Nano Banana 2/Pro deployment provided by MiniMax has less content moderation compared to Google Flow and is capable of editing photos of minors or famous people.

<details markdown="block">
<summary><small><b>💲 Credits estimator</b></small></summary>

Actual costs may change, see [hailuoai.video](https://hailuoai.video) for current pricing. The **$ at Master** column prices each generation on the [$79.99/m Master](https://hailuoai.video/subscribe/modal) plan ($0.00762/credit, the lowest cost per credit). Paid plans apply Seedance 2.0 at half credits, already reflected below.

Seedance 2.0 and Hailuo 3.0 bill per second, and a video reference is charged on its own length on top of the generated clip — at a lower per-second rate than the output. Image and audio references carry no per-second charge. The calculator below takes a video reference length so you can see the full cost.

| Plan | Monthly | Credits/mo | $/credit |
|:-----|:-----:|:-----:|:-----:|
| Standard | $9.99 | 1,000 | $0.00999 |
| Pro | $34.99 | 4,500 | $0.00778 |
| Master | $79.99 | 10,500 | $0.00762 |
| Max | $199.99 | 20,000 | $0.01000 |

**Images** — per image, see [images/create](/docs/api-minimax-v1/post-minimax-images-create) for details

| Model | Credits | $ at Master |
|:------|:-------:|:-----------:|
| image-01 | 1 | $0.008 |
| midjourney-v7, midjourney-niji7 | 3 | $0.023 |
| seedream-4.5, seedream-5.0 | 4 | $0.030 |
| nano-banana-2 (512P/1K) | 4 | $0.030 |
| nano-banana-2 (2K) | 5 | $0.038 |
| nano-banana-2 (4K) | 8 | $0.061 |
| nano-banana-pro (1K/2K) | 6 | $0.046 |
| nano-banana-pro (4K) | 10 | $0.076 |
| gpt-image-1.5 (Low/Medium/High) | 4 / 8 / 15 | $0.030 / $0.061 / $0.114 |
| gpt-image-2 quality `low` (1K/2K/4K) | 2 / 5 / 10 | $0.015 / $0.038 / $0.076 |
| gpt-image-2 quality `medium` (1K/2K/4K) | 8 / 20 / 40 | $0.061 / $0.152 / $0.305 |
| gpt-image-2 quality `high` (1K/2K/4K) | 30 / 80 / 160 | $0.229 / $0.609 / $1.219 |

**Videos** — see [videos/create](/docs/api-minimax-v1/post-minimax-videos-create) for details

Billed per second, so multiply by your `duration` (4–15). A video reference is charged on its own length as well, at the rate in the last column — image and audio references add nothing per second.

| Model | Resolution | Credits/sec | Video ref/sec | $ at Master, per sec |
|:------|:-----------|:-----------:|:-------------:|:--------------------:|
| Hailuo-3.0 | 768p | 7 | 7 | $0.053 |
| Hailuo-3.0 | 2K | 12 | 12 | $0.091 |
| Seedance-2.0 | 480p | 10 | 6 | $0.076 |
| Seedance-2.0 | 720p | 21 | 14 | $0.160 |
| Seedance-2.0 | 1080p | 50 | 30 | $0.381 |
| Seedance-2.0 | 4K | 100 | 60 | $0.762 |
| Seedance-2.0-Fast | 480p | 8 | 4 | $0.061 |
| Seedance-2.0-Fast | 720p | 17 | 11 | $0.130 |
| Seedance-2.0-Mini | 480p | 5 | 3 | $0.038 |
| Seedance-2.0-Mini | 720p | 11 | 7 | $0.084 |

Billed per video, at a fixed price per option.

| Model | Option | Credits | $ at Master |
|:------|:-------|:-------:|:-----------:|
| Hailuo 01 (all models) | — | 25 | $0.190 |
| Hailuo 02, T2V-2.3, I2V-2.3 | 768p / 1080p | 25–80 | $0.190–$0.609 |
| I2V-2.3-Fast | 768p / 1080p | 15–50 | $0.114–$0.381 |
| Sora-2 | 4 / 8 / 12 sec | 40 / 80 / 120 | $0.305 / $0.609 / $0.914 |
| Veo-3.1, Veo-3.1-S2V | 720p / 1080p / 4K | 120 / 120 / 180 | $0.914 / $0.914 / $1.371 |
| Veo-3.1-Fast, Veo-3.1-S2V-Fast | 720p / 1080p / 4K | 60 / 60 / 90 | $0.457 / $0.457 / $0.686 |

**Interactive calculator** — pick a plan and model for the per-generation cost:

<div class="mm-cc" markdown="0">
<style>
.mm-cc{border:1px solid #d0d7de;padding:1em;border-radius:6px;background:#fafbfc;max-width:600px}
.mm-cc .r{display:flex;gap:.6em;align-items:center;margin-bottom:.5em;flex-wrap:wrap}
.mm-cc label.l{min-width:88px;font-weight:600}
.mm-cc select{padding:3px 6px;font-size:.95em;max-width:100%}
.mm-cc .out{margin-top:.6em;padding:.7em;background:#fff;border:1px solid #dfe2e5;border-radius:4px;font-size:1.15em}
.mm-cc .out b{color:#0366d6}
.mm-cc .sub{color:#57606a;font-size:.8em}
</style>
<div class="r"><label class="l" for="mmPlan">Plan</label><select id="mmPlan">
<option value="0.0076181">Master — $79.99/m · 10,500 cr (best $/credit)</option>
<option value="0.0077756">Pro — $34.99/m · 4,500 cr</option>
<option value="0.00999">Standard — $9.99/m · 1,000 cr</option>
<option value="0.0099995">Max — $199.99/m · 20,000 cr</option>
</select></div>
<div class="r"><label class="l" for="mmKind">Type</label><select id="mmKind"><option value="video">Video</option><option value="image">Image</option></select></div>
<div class="r"><label class="l" for="mmModel">Model</label><select id="mmModel"></select></div>
<div class="r" id="mmOptR"><label class="l" for="mmOpt">Option</label><select id="mmOpt"></select></div>
<div class="r" id="mmDurR"><label class="l" for="mmDur">Duration (s)</label><select id="mmDur"></select></div>
<div class="r" id="mmVrefR"><label class="l" for="mmVref">Video ref (s)</label><select id="mmVref"></select></div>
<div class="out" id="mmOut">—</div>
</div>

<script>
(function(){
var M={
video:{
'Hailuo-3.0':{sd:{'768p':[7,7],'2K (1440)':[12,12]}},
'02':{opt:{'512p · 6s':12,'512p · 10s':25,'768p · 6s':25,'768p · 10s':50,'1080p · 6s':80}},
'T2V-2.3':{opt:{'768p · 6s':25,'768p · 10s':50,'1080p · 6s':80}},
'I2V-2.3':{opt:{'768p · 6s':25,'768p · 10s':50,'1080p · 6s':80}},
'I2V-2.3-Fast':{opt:{'768p · 6s':15,'768p · 10s':30,'1080p · 6s':50}},
'T2V-01':{flat:25},'I2V-01':{flat:25},'I2V-01-live':{flat:25},'I2V-01-Director':{flat:25},'T2V-01-Director':{flat:25},'S2V-01':{flat:25},
'Seedance-2.0':{sd:{'480p':[10,6],'720p':[21,14],'1080p':[50,30],'4K':[100,60]}},
'Seedance-2.0-Fast':{sd:{'480p':[8,4],'720p':[17,11]}},
'Seedance-2.0-Mini':{sd:{'480p':[5,3],'720p':[11,7]}},
'Sora-2':{opt:{'720p · 4s':40,'720p · 8s':80,'720p · 12s':120}},
'Veo-3.1':{opt:{'720p · 8s':120,'1080p · 8s':120,'4K · 8s':180}},
'Veo-3.1-Fast':{opt:{'720p · 8s':60,'1080p · 8s':60,'4K · 8s':90}},
'Veo-3.1-S2V':{opt:{'720p · 8s':120,'1080p · 8s':120,'4K · 8s':180}},
'Veo-3.1-S2V-Fast':{opt:{'720p · 8s':60,'1080p · 8s':60,'4K · 8s':90}}
},
image:{
'image-01':{flat:1},'midjourney-v7':{flat:3},'midjourney-niji7':{flat:3},'seedream-4.5':{flat:4},'seedream-5.0':{flat:4},
'nano-banana-2':{opt:{'512P/1K':4,'2K':5,'4K':8}},
'nano-banana-pro':{opt:{'1K/2K':6,'4K':10}},
'gpt-image-1.5':{opt:{'Low':4,'Medium':8,'High':15}},
'gpt-image-2':{opt:{'low · 1K':2,'low · 2K':5,'low · 4K':10,'medium · 1K':8,'medium · 2K':20,'medium · 4K':40,'high · 1K':30,'high · 2K':80,'high · 4K':160}}
}
};
function g(id){return document.getElementById(id);}
var plan=g('mmPlan'),kind=g('mmKind'),model=g('mmModel'),optR=g('mmOptR'),opt=g('mmOpt'),durR=g('mmDurR'),dur=g('mmDur'),vrefR=g('mmVrefR'),vref=g('mmVref'),out=g('mmOut');
function fill(sel,arr){sel.innerHTML='';for(var i=0;i<arr.length;i++){var o=document.createElement('option');o.value=arr[i];o.textContent=arr[i];sel.appendChild(o);}}
function models(){fill(model,Object.keys(M[kind.value]));inputs();}
function inputs(){
var m=M[kind.value][model.value]||{};
if(m.sd){optR.style.display='';durR.style.display='';vrefR.style.display='';fill(opt,Object.keys(m.sd));var d=[];for(var i=4;i<=15;i++)d.push(String(i));fill(dur,d);dur.value='5';var v=[];for(var j=0;j<=15;j++)v.push(String(j));fill(vref,v);vref.value='0';}
else if(m.opt){optR.style.display='';durR.style.display='none';vrefR.style.display='none';fill(opt,Object.keys(m.opt));}
else{optR.style.display='none';durR.style.display='none';vrefR.style.display='none';}
calc();
}
function calc(){
var m=M[kind.value][model.value]||{},cr=0,d='';
if(m.sd){var r=m.sd[opt.value]||[0,0],rt=r[0],vr=r[1],s=+dur.value,vs=+vref.value;cr=rt*s+vr*vs;d=rt+' cr/sec × '+s+'s'+(vs?' + '+vr+' cr/sec × '+vs+'s video ref':'');}
else if(m.opt){cr=m.opt[opt.value];d='per '+kind.value;}
else{cr=m.flat||0;d='per '+kind.value;}
var pc=+plan.value,usd=cr*pc;
out.innerHTML='<b>'+cr+' credits</b> ≈ <b>$'+usd.toFixed(usd<1?3:2)+'</b> <span class="sub">'+d+', at $'+pc.toFixed(5)+'/credit</span>';
}
plan.onchange=calc;kind.onchange=models;model.onchange=inputs;opt.onchange=calc;dur.onchange=calc;vref.onchange=calc;
models();
})();
</script>

Estimate only — it does not include any discounts or promotional pricing. Plan rates are the current published monthly prices.

</details>

<details markdown="block">

<summary><small><b>💲 Music credits</b></small></summary>

Music bills against the [MiniMax Audio](https://www.minimax.io/audio/subscribe) balance, which is a separate ledger from the video credits above — a video plan does not pay for songs, and vice versa.

300 credits per song, whatever the model, length, or whether it has vocals. A `quantity` of 3 costs 900.

Both prices below are MiniMax's own — what changes is which MiniMax product you buy:

| Cost of one song | |
|:---|---:|
| [minimax.io/audio](https://www.minimax.io/audio/subscribe) — Pro plan, $99/mo <small>(what this API uses)</small> | $0.01 |
| [platform.minimax.io](https://platform.minimax.io/docs/guides/pricing-paygo#music) — pay-as-you-go | $0.15 |

A fifteenth of the price of MiniMax's own developer API, for the same song.

Also worth knowing:

- Other tiers carry 100,000 credits on Starter (~330 songs), 330,000 on Creator (~1,100), 750,000 on Standard (~2,500).
- Pay-as-you-go adds $0.01 when the model writes the lyrics. On a minimax.io plan that is part of the same 300 credits.

Actual costs may change, see [minimax.io](https://www.minimax.io/audio/subscribe) for current pricing.

</details>

<details markdown="block">

<summary><small><b>💲 Speech credits</b></small></summary>

Speech bills against the same [MiniMax Audio](https://www.minimax.io/audio/subscribe) balance as music — the same plans, so characters and songs draw on one pool.

Billing is per character — 1 credit on an `hd` model, 0.6 on a `turbo` one, so `turbo` costs 40% less and takes twice the text in a single call.

All three prices below are MiniMax's own — what changes is which MiniMax product you buy:

| Cost of 1,000,000 characters on `speech-2.8-hd` | |
|:---|---:|
| [minimax.io/audio](https://www.minimax.io/audio/subscribe) — Pro plan, $99/mo <small>(what this API uses)</small> | $33 |
| [platform.minimax.io](https://platform.minimax.io/docs/guides/pricing-speech) — Audio Subscription, Pro $99/mo | $90 |
| [platform.minimax.io](https://platform.minimax.io/docs/guides/pricing-paygo) — pay-as-you-go | $100 |

A third of the price of MiniMax's own developer API, for the same audio.

Also worth knowing:

- Other tiers carry 100,000 credits on Starter, 330,000 on Creator, 750,000 on Standard.
- Voice cloning costs no credits. It uses a voice slot — 10 on Starter up to 250 on Pro — which [POST speech/delete-voice](/docs/api-minimax-v1/post-minimax-speech-delete-voice) frees and [GET speech/equity](/docs/api-minimax-v1/get-minimax-speech-equity) counts.
- Emotion tags are free. Sound and pause markup is billed as ordinary text.
- On `turbo` it is $19.80 a million against pay-as-you-go's $60. MiniMax discounts both sides by the same 0.6, so the gap stays a third whichever model you pick.

Actual costs may change, see [minimax.io](https://www.minimax.io/audio/subscribe) for current pricing.

</details>

[Setup MiniMax](/docs/start-here/setup-minimax)

[Postman collection](https://www.postman.com/useapinet/useapi-net/collection) <small>(August 24, 2026)</small>  
[LLM-friendly API spec](https://useapi.net/assets/aibot/api-minimax-v1.txt) <small>Feed this to your LLM to build integrations</small>

[Q&A: How is your experimental MiniMax API different from the official MiniMax API?](/docs/questions-and-answers#how-is-your-experimental-minimax-api-different-from-the-official-minimax-api)

Examples:
* [MiniMax: Music Generation, Three Ways](/blog/260817)
* [MiniMax H3 vs Seedance 2.0: 2K with native audio, head to head](/blog/260730)
* [Seedance 2.0: Standard vs Fast vs Mini, omni references](/blog/260626b)
* [17 AI Image Models: The Showdown](/blog/260309i)
* [Nano Banana 2](/blog/260227)
* [Midjourney V7: prompts, image references, and pricing](/blog/260629)
* [MiniMax Sora 2 & Midjourney V7](/blog/260224)
* [MiniMax Sora 2, Veo 3.1](/blog/260102)
* [MiniMax Agent: Nano Banana 2/Pro, Speech 2.5, Music 2.0 and more...](/blog/251124)
* [MiniMax 2.3](/blog/251030)
* [MiniMax 02 End Frame](/blog/250830)
* [Groundbreaking Video Agents](/blog/250630)
* [MiniMax Images](/blog/250508)

Articles:
* [Fun with MiniMax API](/docs/articles/minimax-bash)
* [How to Generate Text-to-Speech Audio with the MiniMax (Hailuo) API](/docs/articles/minimax-speech-bash)
* [Seedance 2.0 API Pricing: The Cheapest Ways to Run It, Compared](/docs/articles/seedance-2-api-pricing)
* [AI Music APIs One Generation Later: MiniMax Music-3.0 vs Lyria 3.5 vs Mureka V9.5](/docs/articles/ai-music-flagships-compared)

Developer Community:
* <a href="https://discord.gg/w28uK3cnmF"><img style="height:1em;vertical-align: middle;" src="/assets/images/discord.svg"> Discord Server</a>
* <a href="https://t.me/use_api"><img style="height:1.3em;vertical-align: middle;" src="/assets/images/telegram.svg"> Telegram Channel</a>

=== URL: https://useapi.net/docs/api-minimax-v1/del-minimax-accounts-account ===
Document URL: https://useapi.net/docs/api-minimax-v1/del-minimax-accounts-account
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-delete">DEL</code> accounts/`account`
description: "Delete a previously configured MiniMax account by name via DEL accounts/account in the useapi.net MiniMax API v1."
parent: MiniMax API v1
nav_order: 400
---
## Delete MiniMax API account
<small>September 25, 2024 (March 17, 2025)</small>

---
> **https://api.useapi.net/v1/minimax/accounts/`account`**

The `account` value should correspond to an account configured previously via a [POST /accounts](/docs/api-minimax-v1/post-minimax-accounts-account) request.

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Responses 

**204**
**204 No Content** 

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**

##### Model 
```typescript
{ // TypeScript, all fields are optional
  error: string,
  errorDetails: string,
  code: number
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X DELETE https://api.useapi.net/v1/minimax/accounts/<account> 
```

**JavaScript**
``` javascript
const account = "Previously configured account"; 
const apiUrl = `https://api.useapi.net/v1/minimax/accounts/${channnel}`; 
const token = "API token";
const data = { 
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
account = "Previously configured account" 
apiUrl = f"https://api.useapi.net/v1/minimax/accounts/{account}" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.delete(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/del-minimax-files-fileID ===
Document URL: https://useapi.net/docs/api-minimax-v1/del-minimax-files-fileID
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-delete">DEL</code> files/`fileID`
description: "Delete an uploaded file by fileID via DEL files/fileID in the useapi.net MiniMax API v1 — always succeeds, even if the file is already gone."
parent: MiniMax API v1
nav_order: 3500
---
## Delete file
<small>December 23, 2024</small>

---

Use this endpoint to delete file uploaded by

* [POST files](/docs/api-minimax-v1/post-minimax-files)

This endpoint will return a response `200` if you're trying to delete a file that does not exist or has already been deleted. It is safe to say it always succeeds.
> **https://api.useapi.net/v1/minimax/files/`fileID`**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Path parameter
- `fileID` is **required**. Specify the fileID you want to delete.   

##### Responses 

**200**
**200 OK**  

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Examples

**Curl**
``` bash
curl  -X DELETE "https://api.useapi.net/v1/minimax/files/fileID" \
      -H "Accept: application/json" \
      -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const fileID = "fileID to delete"; 
const apiUrl = `https://api.useapi.net/v1/minimax/files/${fileID}`; 
const response = await fetch(apiUrl, {
  method: 'DELETE',
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
fileID = "fileID to delete"
apiUrl = f"https://api.useapi.net/v1/minimax/files/{fileID}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.delete(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/del-minimax-images-imageId ===
Document URL: https://useapi.net/docs/api-minimax-v1/del-minimax-images-imageId
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-delete">DEL</code> images/`imageId`
description: "Soft-delete a generated image by imageId via DEL images/imageId in the useapi.net MiniMax API v1 — hides it from GET images but keeps it retrievable by ID."
parent: MiniMax API v1
nav_order: 1400
---
## Delete image 
<small>March 17, 2025</small>

---

Use this endpoint to delete image generated by

* [POST images/create](/docs/api-minimax-v1/post-minimax-images-create)

This endpoint will return a response `200` if you're trying to delete a image that does not exist or has already been deleted. It is safe to say it always succeeds.

Images are soft-deleted. While the image will no longer appear in [GET images](/docs/api-minimax-v1/get-minimax-images), you can still retrieve it via [GET images/`imageId`](/docs/api-minimax-v1/get-minimax-images-imageId).
> **https://api.useapi.net/v1/minimax/images/`imageId`**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Path parameter
- `imageId` is **required**. Specify the imageId you want to delete.   

##### Responses 

**200**
**200 OK**  

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Examples

**Curl**
``` bash
curl  -X DELETE "https://api.useapi.net/v1/minimax/images/<imageId>" \
      -H "Accept: application/json" \
      -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const imageId = "imageId to delete"; 
const apiUrl = `https://api.useapi.net/v1/minimax/images/${imageId}`; 
const response = await fetch(apiUrl, {
  method: 'DELETE',
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
imageId = "imageId to delete"
apiUrl = f"https://api.useapi.net/v1/minimax/images/{imageId}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.delete(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/del-minimax-music-musicId ===
Document URL: https://useapi.net/docs/api-minimax-v1/del-minimax-music-musicId
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-delete">DELETE</code> music/`musicId`
description: "Remove a generated song from the MiniMax account via DELETE music/musicId in the useapi.net MiniMax API v1 — takes the musicId returned by POST music/create."
parent: MiniMax API v1
nav_order: 3100
---
## Delete Music
<small>August 17, 2026</small>

---

Deletes a song from the MiniMax account it was generated on. The track disappears from [GET music](/docs/api-minimax-v1/get-minimax-music) and its `audio_url` stops resolving, so download anything you want to keep first.
> **https://api.useapi.net/v1/minimax/music/{musicId}**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters

- `musicId` is **required**, the value returned by [POST music/create](/docs/api-minimax-v1/post-minimax-music-create). Path parameter, for example `user:12345-minimax:123456789012345678-music:987654321098765`.

**Notes:**

- The account is taken from the `musicId` itself, so no `account` parameter is needed.
- A song that is still rendering **cannot** be deleted — the call returns `409`. Wait until [GET music/musicId](/docs/api-minimax-v1/get-minimax-music-musicId) reports `statusFinal` as `true`, then delete. The generation is unaffected by the rejected attempt.

##### Responses 

**200**
**200 OK**
```json
{
  "musicId": "user:12345-minimax:123456789012345678-music:987654321098765",
  "deleted": true
}
```

**400**
**400 Bad Request**
```json
{
  "error": "Path parameter musicId (bogus) has incorrect format",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**409**
**409 Conflict**
```json
{
  "error": "This song is still generating and cannot be deleted yet. Wait for statusFinal, then delete.",
  "code": 409
}
```

**596**
**596 Account Error**
```json
{
  "error": "Your minimax account has pending error. Please address this issue at https://useapi.net/docs/api-minimax-v1/post-minimax-accounts-account before making any new API calls.",
  "code": 596
}
```

A `musicId` belonging to a different useapi.net user is rejected with `400 Path parameter musicId (…) unauthorized access to user:NNNNN detected`.

##### Model
```typescript
{ // TypeScript, all fields are optional
  musicId: string,       // The song that was deleted
  deleted: boolean
}
```

##### Examples

**Curl**
```bash
curl -X DELETE "https://api.useapi.net/v1/minimax/music/user:12345-minimax:123456789012345678-music:987654321098765" \
  -H "Authorization: Bearer …"
```

**JavaScript**
```javascript
const musicId = "user:12345-minimax:123456789012345678-music:987654321098765";

const response = await fetch(`https://api.useapi.net/v1/minimax/music/${musicId}`, {
  method: "DELETE",
  headers: { "Authorization": "Bearer …" }
});

console.log(await response.json());
```

**Python**
```python
import requests

music_id = "user:12345-minimax:123456789012345678-music:987654321098765"

response = requests.delete(
    f"https://api.useapi.net/v1/minimax/music/{music_id}",
    headers={"Authorization": "Bearer …"}
)

print(response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/del-minimax-scheduler-videoId ===
Document URL: https://useapi.net/docs/api-minimax-v1/del-minimax-scheduler-videoId
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-delete">DEL</code> scheduler/`id`
description: "Remove a video, image, music or speech generation from scheduler tracking via DEL scheduler/id in the useapi.net MiniMax API v1 without cancelling the underlying job."
parent: MiniMax API v1
nav_order: 3800
---
## Remove video, image, music or speech generation from being tracked by the scheduler
<small>September 25, 2024 (August 17, 2026)</small>

---

API tracks the running generations of images and videos. This is done to maintain a list of currently executed video generations and to send webhook messages via optionally provided `replyUrl` parameters. If you want to remove image or video generation from being tracked by the scheduler, use this endpoint.
> **https://api.useapi.net/v1/minimax/scheduler/`id`**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```
- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Path parameter
- `id` is **required**. Specify videoId, imageId, musicId or audioId you want to stop tracking.

**Notes:**

- Stopping tracking does not cancel the work at MiniMax. A video or song carries on and can still be found through its own GET endpoint.
- Speech is the exception worth knowing about. An `audioId` is issued by useapi.net rather than MiniMax, so once it stops being tracked there is nothing left to resolve it — [GET speech/`audioId`](/docs/api-minimax-v1/get-minimax-speech_audio_id) reports it as `failed` from that point on. The recording itself still completes and appears in [GET speech](/docs/api-minimax-v1/get-minimax-speech).

##### Responses 

**204**
**204 No Content**  

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**  
```json
{
  "error": "Unable to locate running <id>"
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  error: string
  code: number
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X DELETE "https://api.useapi.net/v1/minimax/scheduler/<id>" 
```

**JavaScript**
``` javascript
const videoId = "videoId to cancel"; 
const apiUrl = `https://api.useapi.net/v1/minimax/scheduler/${videoId}`; 
const token = "API token";
const data = { 
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
videoId = "videoId to cancel" 
apiUrl = f"https://api.useapi.net/v1/minimax/scheduler/{videoId}" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.delete(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/del-minimax-speech-audio_id ===
Document URL: https://useapi.net/docs/api-minimax-v1/del-minimax-speech-audio_id
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-delete">DEL</code> speech/`audio_id`
description: "Delete a speech recording from a MiniMax account via DELETE speech/audioId in the useapi.net MiniMax API v1, removing it from the account history for good."
parent: MiniMax API v1
nav_order: 1901
---
## Delete text-to-speech audio clip 
<small>December 27, 2024 (August 24, 2026)</small>

---

This endpoint will delete audio clip generated by 

* [POST speech/create](/docs/api-minimax-v1/post-minimax-speech-create)
* [POST speech/create-mp3](/docs/api-minimax-v1/post-minimax-speech-create-mp3)

This endpoint returns `200` for an audio clip that does not exist or has already been deleted. The one case that does not succeed is a generation still in flight — see the notes below.
> **https://api.useapi.net/v1/minimax/speech/`audio_id`**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Path parameter
- `audio_id` is **required**. Specify the audio_id you want to delete.   

**Notes:**

- Accepts an `audioId` returned by [POST speech/create](/docs/api-minimax-v1/post-minimax-speech-create) as well as any `audio_id` listed by [GET speech](/docs/api-minimax-v1/get-minimax-speech).
- A generation that is still running cannot be deleted, because there is nothing stored yet. Cancel it with [DELETE scheduler/`id`](/docs/api-minimax-v1/del-minimax-scheduler-videoId) instead, passing the same `audioId`.
- Deleting is permanent. The recording leaves the MiniMax account and stops appearing in [GET speech](/docs/api-minimax-v1/get-minimax-speech).

##### Responses 

**200**
**200 OK**  

**400**

**400 Bad Request**

A generation that is still running has nothing stored to delete yet:

```json
{
    "error": "Generation is still running. Cancel it with DELETE /v1/minimax/scheduler/user:12345-minimax:123456789012345678-audio:178737039436895391"
}
```

And one that never produced a recording:

```json
{
    "error": "Nothing was generated for this audioId, so there is nothing to delete"
}
```

Anything else:

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**596**
**596 Account Error**
```json
{
  "error": "Your minimax account has pending error. Please address this issue at https://useapi.net/docs/api-minimax-v1/post-minimax-accounts-account before making any new API calls.",
  "code": 596
}
```

##### Examples

**Curl**
``` bash
curl  -X DELETE "https://api.useapi.net/v1/minimax/speech/<audio_id>" \
      -H "Accept: application/json" \
      -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const audio_id = "audio_id to delete"; 
const apiUrl = `https://api.useapi.net/v1/minimax/speech/${audio_id}`; 
const response = await fetch(apiUrl, {
  method: 'DELETE',
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
audio_id = "audio_id to delete"
apiUrl = f"https://api.useapi.net/v1/minimax/speech/{audio_id}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.delete(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/del-minimax-videos-videoId ===
Document URL: https://useapi.net/docs/api-minimax-v1/del-minimax-videos-videoId
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-delete">DEL</code> videos/`videoId`
description: "Delete a generated video by videoId via DEL videos/videoId in the useapi.net MiniMax API v1 — always returns 200, even if already deleted."
parent: MiniMax API v1
nav_order: 1000
---
## Delete video 
<small>December 23, 2024</small>

---

Use this endpoint to delete video generated by

* [videos/create](/docs/api-minimax-v1/post-minimax-videos-create)

This endpoint will return a response `200` if you're trying to delete a video that does not exist or has already been deleted. It is safe to say it always succeeds.
> **https://api.useapi.net/v1/minimax/videos/`videoId`**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Path parameter
- `videoId` is **required**. Specify the videoId you want to delete.   

##### Responses 

**200**
**200 OK**  

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Examples

**Curl**
``` bash
curl  -X DELETE "https://api.useapi.net/v1/minimax/videos/videoId" \
      -H "Accept: application/json" \
      -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const videoId = "videoId to delete"; 
const apiUrl = `https://api.useapi.net/v1/minimax/videos/${videoId}`; 
const response = await fetch(apiUrl, {
  method: 'DELETE',
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
videoId = "videoId to delete"
apiUrl = f"https://api.useapi.net/v1/minimax/videos/{videoId}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.delete(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/get-minimax-accounts-account ===
Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-accounts-account
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> accounts/`account`
description: "Retrieve the configuration for a single MiniMax account by name via GET accounts/account in the useapi.net MiniMax API v1."
parent: MiniMax API v1
nav_order: 200
---
## Retrieve MiniMax API account configuration for `account` 
<small>September 25, 2024 (March 17, 2025)</small>

---
> **https://api.useapi.net/v1/minimax/accounts/`account`**

The `account` value should correspond to an account configured previously via a [POST /accounts](/docs/api-minimax-v1/post-minimax-accounts-account) request.

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Responses 

**200**
**200 OK**
```json
{
    "account": "123456",
    "jwt": {
        "token": "abc…secured…xyz",
        "user": {
            "deviceID": "123456789",
            "id": "123456",
            "isAnonymous": true,
            "name": "<name>",
            "avatar": "<url>"
        },
        "exp": 1734858598.864,
        "iat": 1732266598.864,
        "host": "hailuoai.video",
        "searchParams": "device_platform=web&app_id=3001&version_code=22201&uuid=b5df53d1-4c0d-4c77-8422-87e3f3b1a1d6&device_id=123456789&os_name=Windows&browser_name=chrome&device_memory=8&cpu_core_num=4&browser_language=en-US&browser_platform=Win32&screen_width=1920&screen_height=1080&unix=1732266598000",
        "iat_Issued": "2024-01-01T00:00:00.000Z",
        "exp_Expire": "2024-12-01T00:00:00.000Z"
    },
    "maxJobs": 1,
    "supportVideo": true,
    "supportChat": true,
    "supportAudio": true
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**  

Configuration not found. To create configuration use [POST /accounts](/docs/api-minimax-v1/post-minimax-accounts-account).

##### Model 
```typescript
{ // TypeScript, all fields are optional
  account: string
  jwt: {
    token: string
    user: {
      deviceID: string
      id: string
      isAnonymous: boolean
      name: string
      avatar: string
    },
    exp: number
    iat: number
    host: string
    searchParams: string
    iat_Issued: string
    exp_Expire: string
  }
  maxJobs: number
  supportVideo: boolean 
  supportChat: boolean 
  supportAudio: boolean 
  supportMusic: boolean
}
```

##### Examples

**Curl**
``` bash
curl https://api.useapi.net/v1/minimax/accounts/<account> \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const account = "Previously configured account"; 
const apiUrl = `https://api.useapi.net/v1/minimax/accounts/${account}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
account = "Previously configured account"
apiUrl = f"https://api.useapi.net/v1/minimax/accounts/{account}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/get-minimax-accounts ===
Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-accounts
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> accounts
description: "List all configured MiniMax API accounts via GET accounts in the useapi.net MiniMax API v1 — used for load-balanced multi-account setups."
parent: MiniMax API v1
nav_order: 100
---
## Retrieve MiniMax API accounts configuration
<small>September 25, 2024 (March 17, 2025)</small>

---

For your convenience, you can specify your MiniMax configuration values under your MiniMax account. If you specify multiple MiniMax accounts, the API will automatically perform load balancing by randomly selecting an account with available capacity before making calls to MiniMax.

This endpoint retrieves the complete list of configured API accounts for MiniMax.
> **https://api.useapi.net/v1/minimax/accounts**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Responses 

**200**
**200 OK**
```json
{
    "123456": {
        "account": "123456",
        "jwt": {
            "token": "abc…secured…xyz",
            "user": {
                "deviceID": "123456789",
                "id": "123456",
                "isAnonymous": true,
                "name": "<name>",
                "avatar": "<url>"
            },
            "exp": 1734858598.864,
            "iat": 1732266598.864,
            "host": "hailuoai.video",
            "searchParams": "device_platform=web&app_id=3001&version_code=22201&uuid=b5df53d1-4c0d-4c77-8422-87e3f3b1a1d6&device_id=123456789&os_name=Windows&browser_name=chrome&device_memory=8&cpu_core_num=4&browser_language=en-US&browser_platform=Win32&screen_width=1920&screen_height=1080&unix=1732266598000",
            "iat_Issued": "2024-01-01T00:00:00.000Z",
            "exp_Expire": "2024-12-01T00:00:00.000Z"
        },
        "maxJobs": 1,
        "supportVideo": true,
        "supportChat": true,
        "supportAudio": true
    },
    "78910": {
        "account": "78910",
        "jwt": {
            "token": "edf…secured…lmn",
            "user": {
                "deviceID": "987654321",
                "id": "78910",
                "isAnonymous": true,
                "name": "<name>",
                "avatar": "<url>"
            },
            "host": "hailuoai.com",
            "exp": 1744858598.864,
            "iat": 1742266598.864,
            "searchParams": "device_platform=web&app_id=3001&version_code=22201&uuid=92f1a65c-3e9e-4a37-8bd7-8615a6cf60ee&device_id=987654321&os_name=Windows&browser_name=firefox&device_memory=16&cpu_core_num=8&browser_language=en-US&browser_platform=Win64&screen_width=2560&screen_height=1440&unix=1742266598000",
            "iat_Issued": "2025-01-01T00:00:00.000Z",
            "exp_Expire": "2025-12-01T00:00:00.000Z"
        },
        "maxJobs": 1,
        "supportVideo": true,
        "supportChat": true,
        "supportAudio": true
    }
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**

Configuration not found. To create configuration use [POST /accounts](/docs/api-minimax-v1/post-minimax-accounts-account).

##### Model 
```typescript
{ // TypeScript, all fields are optional
    [account: string]: {
        account: string
        jwt: {
            token: string
            user: {
                deviceID: string
                id: string
                isAnonymous: boolean
                name: string
                avatar: string
            },
            exp: number
            iat: number
            host: string
            searchParams: string
            iat_Issued: string
            exp_Expire: string
        }
        maxJobs: number
        supportVideo: boolean 
        supportChat: boolean 
        supportAudio: boolean 
        supportMusic: boolean
    }
}
```

##### Examples

**Curl**
``` bash
curl https://api.useapi.net/v1/minimax/accounts \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const apiUrl = "https://api.useapi.net/v1/minimax/accounts"; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
apiUrl = "https://api.useapi.net/v1/minimax/accounts"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/get-minimax-agent-jobId ===
Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-agent-jobId
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> agent/`jobId`
description: "Poll the status and results of an async AI Agent job by jobId via GET agent/jobId in the useapi.net MiniMax API v1 — jobs are retained for 31 days."
parent: MiniMax API v1
nav_order: 2100
---
## Retrieve Agent Job Status and Results
<small>November 24, 2025 (November 26, 2025)</small>

---

Retrieve the status and results of an agent job. Jobs are stored for 31 days after creation.

Use this endpoint to check the progress of asynchronous agent jobs created with [POST agent](/docs/api-minimax-v1/post-minimax-agent) using `async: true`.
> **https://api.useapi.net/v1/minimax/agent/`jobId`**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

##### Path Parameters

- `jobId` is **required**. The job ID to query.

##### Responses

**200**
**200 OK**

Job found and returned successfully.

**Started Job:**
```json
{
    "jobId": "p123456789-u12345-a67890-bot:minimax",
    "status": "started",
    "created": "2025-11-23T12:34:56.789Z",
    "request": {
        "prompt": "Generate a video of a cat playing piano",
        "models": ["hailuo-2.3"],
        "async": true
    }
}
```

**Completed Job:**
```json
{
    "jobId": "p123456789-u12345-a67890-bot:minimax",
    "status": "completed",
    "created": "2025-11-23T12:34:56.789Z",
    "request": {
        "prompt": "Generate a video of a cat playing piano",
        "models": ["hailuo-2.3", "nano-banana-2"]
    },
    "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"
                    }
                }
            }
        ]
    }
}
```

**Failed Job:**
```json
{
    "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
    }
}
```

**400**
**400 Bad Request**

Invalid job ID format or access denied.

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

**401**
**401 Unauthorized**

Invalid API token.

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

**404**
**404 Not Found**

Job not found or expired after 31 days.

```json
{
  "error": "Job not found or expired after 31 days",
  "code": 404
}
```

##### Model

**Downloading Generated Files:**
- `file.fileUrl` - Primary download URL (may have watermark)
- `file.extra.no_watermark_url` - URL without watermark (when available)
- `file.extra.watermark_url` - URL with watermark
- `node.agentFile.noWatermarkUrl` - Alternative watermark-free URL
- `node.agentFile.url` - Alternative file URL

```typescript
{
  // 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 when status is 'completed')
  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 when status is 'failed')
  error?: string | {                 // Error can be a string or object
    message: string                  // Error description
    status: number                   // HTTP status code
    details?: any                    // Additional error details
  }
}
```

##### Examples

**Curl**
``` bash
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.useapi.net/v1/minimax/agent/p123456789-u12345-a67890-bot:minimax"
```

**JavaScript**
``` javascript
const token = "YOUR_API_TOKEN";
const jobId = "p123456789-u12345-a67890-bot:minimax";
const apiUrl = `https://api.useapi.net/v1/minimax/agent/${jobId}`;

const response = await fetch(apiUrl, {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

const job = await response.json();
console.log('Job status:', job.status);

if (job.status === 'completed' && job.response?.attachments) {
  job.response.attachments.forEach(att => {
    console.log(`${att.file.fileName}: ${att.file.fileUrl}`);
  });
} else if (job.status === 'failed') {
  console.error('Job failed:', job.error);
}
```

**Python**
``` python
import requests

token = "YOUR_API_TOKEN"
job_id = "p123456789-u12345-a67890-bot:minimax"
api_url = f"https://api.useapi.net/v1/minimax/agent/{job_id}"

response = requests.get(
    api_url,
    headers={'Authorization': f'Bearer {token}'}
)

job = response.json()
print(f"Job status: {job['status']}")

if job['status'] == 'completed' and job.get('response', {}).get('attachments'):
    for att in job['response']['attachments']:
        print(f"{att['file']['fileName']}: {att['file']['fileUrl']}")
elif job['status'] == 'failed':
    print(f"Job failed: {job['error']}")
```

=== URL: https://useapi.net/docs/api-minimax-v1/get-minimax-agent-jobs ===
Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-agent-jobs
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> agent/jobs
description: "List all currently running AI Agent jobs via GET agent/jobs in the useapi.net MiniMax API v1 — only in-progress jobs; completed ones require GET agent/jobId."
parent: MiniMax API v1
nav_order: 2200
---
## List Running Agent Jobs
<small>November 24, 2025</small>

---

List all currently running agent jobs for your account. This endpoint returns jobs that are still being processed (status: `started`).

Completed and failed jobs are not included in this list but can be retrieved using [GET agent/`jobId`](/docs/api-minimax-v1/get-minimax-agent-jobId) if you have the job ID.
> **https://api.useapi.net/v1/minimax/agent/jobs**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

##### Responses

**200**
**200 OK**

List of running jobs returned successfully.

Returns jobs grouped by account with execution statistics.

```json
{
    "accounts": ["67890", "54321"],
    "summary": {
        "67890": {
            "executing": 2
        },
        "54321": {
            "executing": 1
        }
    },
    "executing": {
        "67890": [
            {
                "jobId": "p123456789-u12345-a67890-bot:minimax",
                "elapsed": "02:15"
            },
            {
                "jobId": "p987654321-u12345-a67890-bot:minimax",
                "elapsed": "01:30"
            }
        ],
        "54321": [
            {
                "jobId": "p456789123-u12345-a54321-bot:minimax",
                "elapsed": "00:45"
            }
        ]
    }
}
```

**401**
**401 Unauthorized**

Invalid API token.

```json
{
  "error": "Unauthorized"
}
```

##### Model

```typescript
{
  accounts: string[]                    // List of account IDs with configured access
  summary: Record<string, {
    executing: number                   // Number of currently executing jobs for this account
  }>
  executing: Record<string, Array<{     // Jobs grouped by account
    jobId: string                       // Job identifier
    elapsed: string                     // Elapsed time since job started (mm:ss format)
  }>>
}
```

##### Examples

**Curl**
``` bash
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://api.useapi.net/v1/minimax/agent/jobs"
```

**JavaScript**
``` javascript
const token = "YOUR_API_TOKEN";
const apiUrl = "https://api.useapi.net/v1/minimax/agent/jobs";

const response = await fetch(apiUrl, {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

const result = await response.json();
console.log(`${result.accounts.length} account(s) configured`);

for (const account of result.accounts) {
  const summary = result.summary[account];
  if (summary) {
    console.log(`Account ${account}: ${summary.executing} job(s) executing`);
  }

  const jobs = result.executing[account] || [];
  jobs.forEach(job => {
    console.log(`  ${job.jobId} (${job.elapsed})`);
  });
}
```

**Python**
``` python
import requests

token = "YOUR_API_TOKEN"
api_url = "https://api.useapi.net/v1/minimax/agent/jobs"

response = requests.get(
    api_url,
    headers={'Authorization': f'Bearer {token}'}
)

result = response.json()
print(f"{len(result['accounts'])} account(s) configured")

for account in result['accounts']:
    summary = result['summary'].get(account)
    if summary:
        print(f"Account {account}: {summary['executing']} job(s) executing")

    jobs = result['executing'].get(account, [])
    for job in jobs:
        print(f"  {job['jobId']} ({job['elapsed']})")
```

=== URL: https://useapi.net/docs/api-minimax-v1/get-minimax-features ===
Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-features
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> features
description: "Retrieve account credits, available models, per-model credit costs, and queue lengths for your hailuoai.video and minimax.io/audio accounts via GET features in the useapi.net MiniMax API v1."
parent: MiniMax API v1
nav_order: 450
---
## Retrieve your hailuoai.video and minimax.io/audio accounts information
<small>October 14, 2024 (May 31, 2025)</small>

---

Retrieve your [hailuoai.video](https://hailuoai.video) and [www.minimax.io/audio](https://www.minimax.io/audio) accounts information, see [Setup MiniMax](/docs/start-here/setup-minimax) for details.   

This endpoint provides detailed information about available credits and features supported by your account, such as the list of models, credits required for different models, maximum size of jobs query, and so on.
> **https://api.useapi.net/v1/minimax/features/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](/docs/api-minimax-v1/get-minimax-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

##### Responses 

**200**
**200 OK**  

```json
{
    "privilegeType": 0,
    "totalCredits": 100,
    "expireText": "100 points will expire within 24 hours",
    "videoCost": 30,
    "queueLength": 3,
    "memberText": "Subscribe",
    "memberHoverText": "",
    "expireTime": 0,
    "isNewUser": false,
    "questionText": "",
    "trialExpireTime": 0,
    "trialText": 0,
    "memberName": "Free",
    "newUserVersion": 0,
    "creditExpireText": [
        {
            "credit": 100,
            "endTime": 1748735999999
        }
    ],
    "modelControl": [
        {
            "modelId": "image-01",
            "videoCost": 1,
            "isMember": false,
            "freeCount": 0,
            "durations": [],
            "resolutions": [],
            "modes": [],
            "videoCosts": []
        },
        {
            "modelId": "23000",
            "videoCost": 30,
            "isMember": false,
            "freeCount": 0,
            "durations": [],
            "resolutions": [],
            "modes": [],
            "videoCosts": []
        },
        {
            "modelId": "23010",
            "videoCost": 30,
            "isMember": false,
            "freeCount": 0,
            "durations": [],
            "resolutions": [],
            "modes": [],
            "videoCosts": []
        },
        {
            "modelId": "23001",
            "videoCost": 30,
            "isMember": false,
            "freeCount": 0,
            "durations": [],
            "resolutions": [],
            "modes": [],
            "videoCosts": []
        },
        {
            "modelId": "23011",
            "videoCost": 30,
            "isMember": false,
            "freeCount": 0,
            "durations": [],
            "resolutions": [],
            "modes": [],
            "videoCosts": []
        },
        {
            "modelId": "23102",
            "videoCost": 30,
            "isMember": false,
            "freeCount": 0,
            "durations": [],
            "resolutions": [],
            "modes": [],
            "videoCosts": []
        },
        {
            "modelId": "23021",
            "videoCost": 45,
            "isMember": false,
            "freeCount": 0,
            "durations": [],
            "resolutions": [],
            "modes": [],
            "videoCosts": []
        }
    ],
    "supportModes": [],
    "imageQueueLength": 5,
    "totalCreditsStr": "100",
    "isPaidSubscription": false,
    "canManagePlan": true,
    "audio": {
        "total_credit": 100,
        "sub_credits": [
            {
                "credit_type": 3,
                "end_time": 1748735999999,
                "credit": 100,
                "text": "",
                "record": [
                    {
                        "credit": 100,
                        "endTime": 1748735999999
                    }
                ],
                "coin_type": 0
            }
        ],
        "base_resp": {}
    }
}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model 
  
```typescript
{ // TypeScript, all fields are optional
    privilegeType: number
    totalCredits: number
    expireText: string
    videoCost: number
    queueLength: number
    memberText: string
    memberHoverText: string
    expireTime: number
    isNewUser: boolean
    questionText: string
    trialExpireTime: number
    trialText: number
    memberName: string
    newUserVersion: number
    creditExpireText: {
        credit: number
        endTime: number
    }[]
    modelControl: {
        modelId: string
        videoCost: number
        isMember: boolean
        freeCount: number
        durations: any[]
        resolutions: any[]
        modes: any[]
        videoCosts: any[]
    }[]
    supportModes: any[]
    imageQueueLength: number
    totalCreditsStr: string
    isPaidSubscription: boolean
    canManagePlan: boolean
    audio: {
        total_credit: number
        sub_credits: {
            credit_type: number
            end_time: number
            credit: number
            text: string
            record: {
                credit: number
                endTime: number
            }[]
            coin_type: number
        }[]
    }
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/minimax/features/?account=account" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const account = "Previously configured account"; 
const apiUrl = `https://api.useapi.net/v1/minimax/features/?account=${account}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
account = "Previously configured account"
apiUrl = f"https://api.useapi.net/v1/minimax/features/?account={account}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/get-minimax-files ===
Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-files
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> files
description: "List images previously used in video generation via GET files in the useapi.net MiniMax API v1 — this endpoint appears retired as of March 2025 and currently returns no data."
parent: MiniMax API v1
nav_order: 3400
---
## Retrieve the list of images you have uploaded
<small>October 14, 2024 (March 17, 2025)</small>

---

Use [hailuoai.video](https://hailuoai.video) account to retrieve list of uploaded images, see [Setup MiniMax](/docs/start-here/setup-minimax) for details.

This endpoint will return a list of all the images you've used previously to generate videos. Only images that were actually used for generation will be shown.

**NOTE**: As of March 2025, this endpoint appears to be retired both on [hailuoai.video](https://hailuoai.video) website and internally, as it is not used by any website API calls nor does it return any data. We decided to keep it just in case it is revived.
> **https://api.useapi.net/v1/minimax/files/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](/docs/api-minimax-v1/get-minimax-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

- `limit` is optional, specify the number of files to return. Default 10.

##### Responses 

**200**
**200 OK**  

```json
[
    {
        "file_id": "user:user_id-minimax:account-file:file_id_#1",
        "file_name": "<file name>",
        "file_type": "jpeg",
        "cdn_url": "<file ulr>",
        "oss_path": "<file path with name>",
        "file_scene": 10,
        "file_status": 1
    },
    {
        "file_id": "user:user_id-minimax:account-file:file_id_#n",
        "file_name": "<file name>",
        "file_type": "png",
        "cdn_url": "<file ulr>",
        "oss_path": "<file path with name>",
        "file_scene": 10,
        "file_status": 1
    }
]
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model 
  
```typescript
{ // TypeScript, all fields are optional
  file_id: string
  file_name: string
  file_type: string
  cdn_url: string
  oss_path: string
  file_scene: number
  file_status: number
}[]
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/minimax/files/?account=account" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const account = "Previously configured account"; 
const apiUrl = `https://api.useapi.net/v1/minimax/files/?account=${account}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
account = "Previously configured account"
apiUrl = f"https://api.useapi.net/v1/minimax/files/?account={account}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/get-minimax-images-imageId ===
Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-images-imageId
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> images/`imageId`
description: "Retrieve the status and results of an image generation by imageId via GET images/imageId in the useapi.net MiniMax API v1."
parent: MiniMax API v1
nav_order: 1300
---
## Retrieve image 
<small>March 17, 2025</small>

---

Use this endpoint to retrieve status and results of

* [POST images/create](/docs/api-minimax-v1/post-minimax-images-create)
> **https://api.useapi.net/v1/minimax/images/`imageId`**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Path parameter
- `imageId` is **required**. Specify the imageId you want to retrieve.   

##### Responses 

**200**
**200 OK**  

```json
{
  "id": "<image_id>",
  "desc": "...prompt...",
  "coverURL": "https://cdn.hailuoai.video/...png?x-oss-process=image/resize,w_1080/format,webp",
  "videoURL": "https://cdn.hailuoai.video/....png",
  "status": 2,
  "canRetry": false,
  "width": 0,
  "height": 0,
  "originFiles": [],
  "canAppeal": false,
  "downloadURL": "https://cdn.hailuoai.video/....png",
  "hasVoice": false,
  "modelID": "image-01",
  "useOriginPrompt": false,
  "isBookmarked": false,
  "disableGenerateSimilar": false,
  "createTime": 1742173334234,
  "postStatus": 0,
  "userID": 923847293472394000,
  "createType": 4,
  "promptImgURL": "",
  "extra": {
    "cameraMotions": [],
    "promptStruct": ""
  },
  "isVisitor": false,
  "videoURLs": {
    "feedURL": "",
    "downloadURLWithWatermark": "https://cdn.hailuoai.video/....png"
  },
  "priority": 0,
  "generatorType": 1,
  "isInFolder": false,
  "batchID": "357846312387492374",
  "aspectRatio": "9:16",
  "fileID": "user:<user>-minimax:<account>-file:<file_id>",
  "tags": [
    {
      "type": "normal",
      "tagIcon": "",
      "tagText": "image-01"
    },
    {
      "type": "normal",
      "tagIcon": "",
      "tagText": "Enable Optimization"
    },
    {
      "type": "normal",
      "tagIcon": "",
      "tagText": "Image to video"
    }
  ],
  "duration": 0,
  "resolution": 0,
  "humanCheckStatus": 0,
  "userIDStr": "<account>",
  "statusLabel": "completed",
  "statusFinal": true,
  "imageId": "user:<user>-minimax:<account>-image:<image_id>"
}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**  

```json
{
    "error": "Not found.",
    "code": 404
}
```

##### Model 

Known `status` values:

* **0** pending
* **1** processing
* **2** completed 
* **3** failed 
* **5** moderated
* **7** moderated
* **11** queued
* **12** processing
* **14** moderated

Optional fields `message` and `percent` will contain generation progress information.

```typescript
{   // TypeScript, all fields are optional
    id: string
    desc: string
    coverURL: string
    videoURL: string
    status: number
    message: string // Contains the message shown to the user while the image is being processed
    percent: number // Contains 0-100 percent while the image is being processed
    canRetry: boolean
    width: number
    height: number
    originFiles: any[]
    canAppeal: boolean
    downloadURL: string
    hasVoice: boolean
    modelID: string
    useOriginPrompt: boolean
    isBookmarked: boolean
    disableGenerateSimilar: boolean
    createTime: number
    postStatus: number
    userID: number
    createType: number
    promptImgURL: string
    extra: {
      cameraMotions: any[]
      promptStruct: string
    }
    isVisitor: boolean
    videoURLs: {
      feedURL: string
      downloadURLWithWatermark: string
    }
    priority: number
    generatorType: number
    isInFolder: boolean
    batchID: string
    aspectRatio: string
    fileID: string
    tags: {
      type: string
      tagIcon: string
      tagText: string
    }[]
    duration: number
    resolution: number
    humanCheckStatus: number
    userIDStr: string
    statusLabel: string
    statusFinal: boolean
    imageId: string
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/minimax/images/<imageId>" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const imageId = "imageId to retrieve"; 
const apiUrl = `https://api.useapi.net/v1/minimax/images/${imageId}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
imageId = "imageId to retrieve"
apiUrl = f"https://api.useapi.net/v1/minimax/images/{imageId}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/get-minimax-images ===
Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-images
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> images
description: "List all images you have generated via GET images in the useapi.net MiniMax API v1, with pagination and optional account filter."
parent: MiniMax API v1
nav_order: 1200
---
## Retrieve the list of images you have generated
<small>March 17, 2025</small>

---

Use [hailuoai.video](https://hailuoai.video) account to retrieve list of generated images, see [Setup MiniMax](/docs/start-here/setup-minimax) for details.

Returned image `fileID` value can be used as a parameter for [POST videos/create](/docs/api-minimax-v1/post-minimax-videos-create).
> **https://api.useapi.net/v1/minimax/images/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](/docs/api-minimax-v1/get-minimax-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

- `limit` is optional, specify the number of images to return. Default 30.

- `lastImageId` is optional, specify the image id from where to start.

##### Responses 

**200**
**200 OK**  

```json
{
    "images": [
        {
            "id": "<image_id>",
            "desc": "...prompt...",
            "coverURL": "https://cdn.hailuoai.video/...png?x-oss-process=image/resize,w_1080/format,webp",
            "videoURL": "https://cdn.hailuoai.video/....png",
            "status": 2,
            "canRetry": false,
            "width": 0,
            "height": 0,
            "originFiles": [],
            "canAppeal": false,
            "downloadURL": "https://cdn.hailuoai.video/....png",
            "hasVoice": false,
            "modelID": "image-01",
            "useOriginPrompt": false,
            "isBookmarked": false,
            "disableGenerateSimilar": false,
            "createTime": 1742173334234,
            "postStatus": 0,
            "userID": 923847293472394000,
            "createType": 4,
            "promptImgURL": "",
            "extra": {
                "cameraMotions": [],
                "promptStruct": ""
            },
            "isVisitor": false,
            "videoURLs": {
                "feedURL": "",
                "downloadURLWithWatermark": "https://cdn.hailuoai.video/....png"
            },
            "priority": 0,
            "generatorType": 1,
            "isInFolder": false,
            "batchID": "357846312387492374",
            "aspectRatio": "9:16",
            "fileID": "user:<user>-minimax:<account>-file:<file_id>",
            "tags": [
                {
                    "type": "normal",
                    "tagIcon": "",
                    "tagText": "image-01"
                },
                {
                    "type": "normal",
                    "tagIcon": "",
                    "tagText": "Enable Optimization"
                },
                {
                    "type": "normal",
                    "tagIcon": "",
                    "tagText": "Image to video"
                }
            ],
            "duration": 0,
            "resolution": 0,
            "humanCheckStatus": 0,
            "userIDStr": "<account>",
            "statusLabel": "completed",
            "statusFinal": true,
            "imageId": "user:<user>-minimax:<account>-image:<image_id>"
        }
    ],
    "hasPre": false,
    "hasNext": true,
    "processing": false,
    "total": 4135
}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model 

Known `status` values:

* **0** pending
* **1** processing
* **2** completed 
* **3** failed  
* **5** moderated
* **7** moderated
* **11** queued
* **12** processing
* **14** moderated
    
```typescript
{
  images: {
    id: string
    desc: string
    coverURL: string
    videoURL: string
    status: number
    canRetry: boolean
    width: number
    height: number
    originFiles: any[]
    canAppeal: boolean
    downloadURL: string
    hasVoice: boolean
    modelID: string
    useOriginPrompt: boolean
    isBookmarked: boolean
    disableGenerateSimilar: boolean
    createTime: number
    postStatus: number
    userID: number
    createType: number
    promptImgURL: string
    extra: {
      cameraMotions: any[]
      promptStruct: string
    }
    isVisitor: boolean
    videoURLs: {
      feedURL: string
      downloadURLWithWatermark: string
    }
    priority: number
    generatorType: number
    isInFolder: boolean
    batchID: string
    aspectRatio: string
    fileID: string
    tags: {
      type: string
      tagIcon: string
      tagText: string
    }[]
    duration: number
    resolution: number
    humanCheckStatus: number
    userIDStr: string
    statusLabel: string
    statusFinal: boolean
    imageId: string
  }[]
  hasPre: boolean
  hasNext: boolean
  processing: boolean
  total: number
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/minimax/images/?account=<account>" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const account = "Previously configured account"; 
const apiUrl = `https://api.useapi.net/v1/minimax/images/?account=${account}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
account = "Previously configured account"
apiUrl = f"https://api.useapi.net/v1/minimax/images/?account={account}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/get-minimax-music-musicId ===
Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-music-musicId
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> music/`musicId`
description: "Poll a single MiniMax song by musicId via GET music/musicId in the useapi.net MiniMax API v1 — returns status, duration, lyrics, and the MP3 download URL once rendering completes."
parent: MiniMax API v1
nav_order: 3000
---
## Retrieve Music
<small>September 25, 2024 (August 21, 2026)</small>

---

Retrieve a single song created with [POST music/create](/docs/api-minimax-v1/post-minimax-music-create). Poll this endpoint until `statusFinal` is `true`, at which point `audio_url` holds the MP3 and `duration` is set.

It also returns reference tracks uploaded with [POST music/reference](/docs/api-minimax-v1/post-minimax-music-reference), which need no polling — they arrive `completed`. `typeLabel` tells the two apart.

Supplying a `replyUrl` on the original create call avoids polling altogether — we POST this same object to your URL as soon as the track finishes.
> **https://api.useapi.net/v1/minimax/music/{musicId}**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters

- `musicId` is **required**, the value returned by [POST music/create](/docs/api-minimax-v1/post-minimax-music-create). Path parameter, for example `user:12345-minimax:123456789012345678-music:987654321098765`.

**Notes:**

- Poll every 15 to 20 seconds. Generation time varies with the model, the length of the song, and how busy MiniMax is.
- When `quantity` was greater than `1`, each `musicId` finishes independently — poll each one.

##### Status values

| status | statusLabel | statusFinal | Notes |
|:------:|-------------|:-----------:|-------|
| 0 | `pending` | false | Queued, not started |
| 1 | `processing` | false | Rendering — `audio_url` empty, `duration` 0 |
| 2 | `completed` | true | `audio_url` and `duration` are set |
| 3 | `failed` | true | MiniMax accepted the request but could not render it — `audio_url` stays empty and `duration` stays 0 |
| 4 | `moderated` | true | Rejected by content moderation |

##### Responses 

**200**
**200 OK**
```json
{
  "musicId": "user:12345-minimax:123456789012345678-music:987654321098765",
  "title": "Lisbon Rain",
  "idea": "warm nylon guitar, slow bossa nova, about a rainy afternoon in Lisbon",
  "lyrics": "[Verse]\nThe tram climbs up the hill\n[Chorus]\nAnd the rain keeps falling still",
  "audio_url": "https://cdn.hailuoai.video/moss/prod/2026-08-16-02/moss-audio/user_music/1700000000000000000-987654321098765.mp3",
  "cover_url": "https://cdn.hailuoai.video/moss/staging/2025-06-22-16/music_cover/1700000000000000001-other_43.png",
  "model": "music-3.0",
  "status": 2,
  "statusLabel": "completed",
  "statusFinal": true,
  "typeLabel": "song",
  "instrumental": false,
  "duration": 138472,
  "create_time": 1786849532637,
  "update_time": 1786849671000,
  "is_favorite": false,
  "author_info": {
    "user_name": "Your Name",
    "avatar": "https://cdn.hailuoai.video/moss/prod/2026-03-02-06/user/user_avatar/1700000000000000003-avatar_123456789012345678"
  },
  "tag_list": [
    {
      "tag_name": "warm nylon guitar, slow bossa nova, about a rainy afternoon in Lisbon",
      "tag_type": 1
    }
  ]
}
```

**400**
**400 Bad Request**
```json
{
  "error": "Path parameter musicId (bogus) has incorrect format",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**
```json
{
  "error": "Music user:12345-minimax:123456789012345678-music:987654321098765 not found. Possibly moderated prompt."
}
```

**596**
**596 Account Error**
```json
{
  "error": "Your minimax account has pending error. Please address this issue at https://useapi.net/docs/api-minimax-v1/post-minimax-accounts-account before making any new API calls.",
  "code": 596
}
```

##### Model
```typescript
{ // TypeScript, all fields are optional
  musicId: string,
  title: string,
  idea: string,          // The prompt used to generate this track
  lyrics: string,        // Yours, or written by the model
  audio_url: string,     // MP3, 256 kbps 44.1 kHz stereo. Empty until complete
  cover_url: string,
  model: string,         // music-3.0 | music-2.6
  status: number,        // See the status table above
  statusLabel: string,
  statusFinal: boolean,
  typeLabel: string,     // song | reference — see GET music
  referenceMusicId: string, // Present only on a cover: the track it follows
  instrumental: boolean,
  duration: number,      // Milliseconds, 0 until complete
  create_time: number,
  update_time: number,
  is_favorite: boolean,
  author_info: { user_name: string, avatar: string },
  tag_list: [{ tag_name: string, tag_type: number }]
}
```

##### Examples

**Curl**
```bash
curl "https://api.useapi.net/v1/minimax/music/user:12345-minimax:123456789012345678-music:987654321098765" \
  -H "Authorization: Bearer …"
```

**JavaScript**
```javascript
const musicId = "user:12345-minimax:123456789012345678-music:987654321098765";

while (true) {
  const response = await fetch(`https://api.useapi.net/v1/minimax/music/${musicId}`, {
    headers: { "Authorization": "Bearer …" }
  });

  const track = await response.json();

  if (track.statusFinal) {
    console.log(track.status === 2 ? track.audio_url : track.statusLabel);
    break;
  }

  await new Promise(resolve => setTimeout(resolve, 20000));
}
```

**Python**
```python
import requests, time

music_id = "user:12345-minimax:123456789012345678-music:987654321098765"

while True:
    response = requests.get(
        f"https://api.useapi.net/v1/minimax/music/{music_id}",
        headers={"Authorization": "Bearer …"}
    )

    track = response.json()

    if track["statusFinal"]:
        print(track["audio_url"] if track["status"] == 2 else track["statusLabel"])
        break

    time.sleep(20)
```

=== URL: https://useapi.net/docs/api-minimax-v1/get-minimax-music ===
Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-music
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> music
description: "List the songs and reference tracks on a MiniMax account via GET music in the useapi.net MiniMax API v1 — newest first, filtered by type, with pagination by lastMusicId and a favourites filter."
parent: MiniMax API v1
nav_order: 3200
---
## Retrieve the list of your music
<small>September 25, 2024 (August 21, 2026)</small>

---

Lists the songs on a configured MiniMax account, newest first. Tracks still rendering appear here too, with `statusLabel` set to `processing` and an empty `audio_url`.

This list reflects the MiniMax account itself, so it also includes songs created directly on [minimax.io](https://www.minimax.io/audio/music) rather than through this API.

The account holds two kinds of record and `type` chooses between them. Generated songs are returned by default. Reference tracks — the clips uploaded with [POST music/reference](/docs/api-minimax-v1/post-minimax-music-reference) to make covers from — are held back unless you ask for them, so adding references to an account never changes what an existing integration sees.
> **https://api.useapi.net/v1/minimax/music/?account={account}&limit={limit}&lastMusicId={lastMusicId}&favorite={favorite}&type={type}**

Note the trailing slash after `music` — without it the request does not reach this endpoint.

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one account is configured. If you have several MiniMax accounts configured, this parameter becomes **required**.
- `limit` is optional, the number of songs to return. Default: `30`. Maximum: `100`.
- `lastMusicId` is optional, the `musicId` to start from. Results continue from the song *after* it, which is how you page through a long history.  
  The cursor is looked up across the most recent 1000 songs. A `musicId` older than that returns `400` rather than silently restarting from the newest song.
- `favorite` is optional, return only songs marked as favourites on the MiniMax account. Default: `false`.
- `type` is optional, which kind of record to return. Default: `song`.

  | Value | Returns |
  |---|---|
  | `song` | Generated songs, covers included. The default. |
  | `reference` | Reference tracks uploaded with [POST music/reference](/docs/api-minimax-v1/post-minimax-music-reference) |
  | `all` | Both, interleaved by date |

  Every row carries `typeLabel` saying which it is. A cover is a song, not a reference — you recognise it by `referenceMusicId` being set.

##### Responses 

**200**
**200 OK**
```json
[
  {
    "musicId": "user:12345-minimax:123456789012345678-music:987654321098766",
    "title": "Lisbon Rain",
    "idea": "warm nylon guitar, slow bossa nova, about a rainy afternoon in Lisbon",
    "lyrics": "[Verse]\nThe tram climbs up the hill\n[Chorus]\nAnd the rain keeps falling still",
    "audio_url": "https://cdn.hailuoai.video/moss/prod/2026-08-16-02/moss-audio/user_music/1700000000000000000-987654321098766.mp3",
    "cover_url": "https://cdn.hailuoai.video/moss/staging/2025-06-22-16/music_cover/1700000000000000002-other_45.png",
    "model": "music-3.0",
    "status": 2,
    "statusLabel": "completed",
    "statusFinal": true,
    "typeLabel": "song",
    "instrumental": false,
    "duration": 138472,
    "update_time": 1786827844513,
    "is_favorite": false,
    "hasWav": false,
    "tag_list": [
      {
        "tag_name": "warm nylon guitar, slow bossa nova, about a rainy afternoon in Lisbon",
        "tag_type": 1
      }
    ]
  }
]
```

**400**
**400 Bad Request**
```json
{
  "error": "Please use parameter account to specify account",
  "code": 400
}
```

A `lastMusicId` older than the retrievable window:

```json
{
  "error": "lastMusicId user:12345-minimax:123456789012345678-music:987654321098765 was not found in the most recent 1000 songs",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**596**
**596 Account Error**
```json
{
  "error": "Your minimax account has pending error. Please address this issue at https://useapi.net/docs/api-minimax-v1/post-minimax-accounts-account before making any new API calls.",
  "code": 596
}
```

An account with no songs returns an empty array.

##### Model
```typescript
[{ // TypeScript, all fields are optional
  musicId: string,       // Use with GET music/musicId
  title: string,
  idea: string,
  lyrics: string,
  audio_url: string,     // Empty while still rendering
  cover_url: string,
  model: string,         // music-3.0 | music-2.6
  status: number,        // See GET music/musicId for the status table
  statusLabel: string,
  statusFinal: boolean,
  typeLabel: string,     // song | reference
  referenceMusicId: string, // Present only on a cover: the track it follows
  instrumental: boolean,
  duration: number,      // Milliseconds
  update_time: number,
  is_favorite: boolean,
  hasWav: boolean,
  tag_list: [{ tag_name: string, tag_type: number }]
}]
```

##### Examples

**Curl**
```bash
curl "https://api.useapi.net/v1/minimax/music/?limit=10" \
  -H "Authorization: Bearer …"
```

**JavaScript**
```javascript
const response = await fetch("https://api.useapi.net/v1/minimax/music/?limit=10", {
  headers: { "Authorization": "Bearer …" }
});

const tracks = await response.json();

for (const track of tracks)
  console.log(track.title, track.statusLabel, track.audio_url);
```

**Python**
```python
import requests

response = requests.get(
    "https://api.useapi.net/v1/minimax/music/",
    headers={"Authorization": "Bearer …"},
    params={"limit": 10}
)

for track in response.json():
    print(track["title"], track["statusLabel"], track["audio_url"])
```

=== URL: https://useapi.net/docs/api-minimax-v1/get-minimax-scheduler-available ===
Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-scheduler-available
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> scheduler/available
description: "Check running video jobs and per-account slot availability via GET scheduler/available in the useapi.net MiniMax API v1 before submitting new generations."
parent: MiniMax API v1
nav_order: 3700
---
## Retrieve the list of videos currently running via the API along with the available account capacity
<small>October 15, 2024 (August 17, 2026)</small>

---

This endpoint retrieves the list of images and videos currently running via the API along with the available account capacity.   

If you want to get all videos currently being executed including you manually initiated from hailuoai.com website use [GET /videos](/docs/api-minimax-v1/get-minimax-videos). 

If you want to get all images currently being executed including you manually initiated from hailuoai.com website use [GET /images](/docs/api-minimax-v1/get-minimax-images). 

Please refer to code provided in article [Fun with MiniMax API](/docs/articles/minimax-bash) to see how this endpoint can be used in conjunction with [POST /files](/docs/api-minimax-v1/post-minimax-files) and [POST videos/create](/docs/api-minimax-v1/post-minimax-videos-create).

**NOTE**: The available capacity (array `available`) includes only videos, the API does not include currently executing image generations in that capacity.
> **https://api.useapi.net/v1/minimax/scheduler/available**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Responses 

**200**
**200 OK**  
```json
{
    "executing": [
        {
            "videoId": "user:user_id-minimax:account-video:id1",
            "started": "2024-09-25T01:55:16.128Z",
            "elapsed": "03:57",
            "replyUrl": "<optional callback URL>",
            "replyRef": "<optional reference>"
        },
        {
            "videoId": "user:user_id-minimax:account-image:inN",
            "started": "2024-09-25T01:58:18.555Z",
            "elapsed": "00:35",
            "replyUrl": "<optional callback URL>",
            "replyRef": "<optional reference>"
        },
        {
            "musicId": "user:user_id-minimax:account-music:idN",
            "started": "2026-08-17T02:11:04.312Z",
            "elapsed": "01:12"
        },
        {
            "audioId": "user:user_id-minimax:account-audio:idN",
            "started": "2026-08-24T02:11:04.312Z",
            "elapsed": "00:08"
        }
    ],
    "available": [
        {
            "account": "<account_1>",
            "maxJobs": 5,
            "executing": 0,
            "available": 5,
            "executingMusic": 0
        },
        {
            "account": "<account_2>",
            "maxJobs": 5,
            "executing": 3,
            "available": 2,
            "executingMusic": 1
        },
        {
            "account": "<account_N>",
            "maxJobs": 3,
            "executing": 2,
            "available": 1,
            "executingMusic": 0
        }
    ]
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
    executing: {
        videoId: string
        imageId: string
        musicId: string
        audioId: string
        started: string 
        elapsed: string 
        replyUrl: string
        replyRef: string
    }[]
    available: {
        account: string
        maxJobs: number
        executing: number
        available: number
        executingMusic: number   // music generations in flight; music has no local ceiling
        executingAudio: number   // speech generations in flight, same reasoning
    }[]
    error: string
    code: number
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/minimax/scheduler/available" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const apiUrl = `https://api.useapi.net/v1/minimax/scheduler/available`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
apiUrl = f"https://api.useapi.net/v1/minimax/scheduler/available"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/get-minimax-scheduler ===
Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-scheduler
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> scheduler
description: "Retrieve all video, image, music and speech generations currently running via the API via GET scheduler in the useapi.net MiniMax API v1 — API-initiated jobs only."
parent: MiniMax API v1
nav_order: 3600
---
## Retrieve the list of images, videos, music and speech currently being executed by the API
<small>September 25, 2024 (August 17, 2026)</small>

---

This endpoint retrieves the list of images and videos currently being executed by the API.

If you want to get all videos currently being executed including you manually initiated from hailuoai.com website use [GET /videos](/docs/api-minimax-v1/get-minimax-videos). 

If you want to get all images currently being executed including you manually initiated from hailuoai.com website use [GET /images](/docs/api-minimax-v1/get-minimax-images). 
> **https://api.useapi.net/v1/minimax/scheduler/**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Responses 

**200**
**200 OK**  
```json
[
    {
        "videoId": "user:user_id-minimax:account-video:id1",
        "started": "2024-09-25T01:55:16.128Z",
        "elapsed": "03:57",
        "replyUrl": "<optional callback URL>",
        "replyRef": "<optional reference>"
    },
    {
        "videoId": "user:user_id-minimax:account-image:inN",
        "started": "2024-09-25T01:58:18.555Z",
        "elapsed": "00:35",
        "replyUrl": "<optional callback URL>",
        "replyRef": "<optional reference>"
    },
    {
        "musicId": "user:user_id-minimax:account-music:idN",
        "started": "2026-08-17T02:11:04.312Z",
        "elapsed": "01:12",
        "replyUrl": "<optional callback URL>",
        "replyRef": "<optional reference>"
    },
    {
        "audioId": "user:user_id-minimax:account-audio:idN",
        "started": "2026-08-24T02:11:04.312Z",
        "elapsed": "00:08",
        "replyUrl": "<optional callback URL>",
        "replyRef": "<optional reference>"
    }
]
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
    videoId: string
    imageId: string
    musicId: string
    audioId: string
    started: number
    elapsed: string
    replyUrl: string
    replyRef: string
}[]
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/minimax/scheduler/" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const apiUrl = `https://api.useapi.net/v1/minimax/scheduler/`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
apiUrl = f"https://api.useapi.net/v1/minimax/scheduler/"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/get-minimax-speech-config ===
Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-speech-config
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> speech/config
description: "Fetch the speech emotion list and voice tag vocabularies via GET speech/config in the useapi.net MiniMax API v1, everything needed to build your own voice picker."
parent: MiniMax API v1
nav_order: 1899
---
## Retrieve audio configuration parameters
<small>December 23, 2024 (August 24, 2026)</small>

---

Returns the vocabularies speech generation accepts — the emotion names, the voice tags used for filtering, and the languages available for `language_boost`.
> **https://api.useapi.net/v1/minimax/speech/config/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](/docs/api-minimax-v1/get-minimax-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

##### Responses 

**200**
**200 OK**  

```json
{
    "t2a_emotion": [
        {
            "label": "Happy",
            "value": "happy"
        },
        {
            "label": "...",
            "value": "..."
        }
    ],
    "voice_tag_accent": [
        {
            "language": "English",
            "tag_name": "EN-US (General)"
        },
        {
            "language": "...",
            "tag_name": "..."
        }
    ],
    "voice_tag_age": [
        {
            "tag_name": "Young"
        },
        {
            "tag_name": "..."
        }
    ],
    "voice_tag_gender": [
        {
            "tag_name": "Male"
        },
        {
            "tag_name": "..."
        }
    ],
    "voice_tag_language": [
        {
            "tag_name": "English"
        },
        {
            "tag_name": "..."
        }
    ]
}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**596**
**596 Account Error**
```json
{
  "error": "Your minimax account has pending error. Please address this issue at https://useapi.net/docs/api-minimax-v1/post-minimax-accounts-account before making any new API calls.",
  "code": 596
}
```

##### Model 

```typescript
{   // TypeScript, all fields are optional
    t2a_emotion: {
        label: string
        value: string
    }[]
    voice_tag_accent: {
        language: string
        tag_name: string
    }[]
    voice_tag_age: {
        tag_name: string
    }[]
    voice_tag_gender: {
        tag_name: string
    }[]
    voice_tag_language: {
        tag_name: string
    }[]
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/minimax/speech/config/?account=account" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const account = "Previously configured account"; 
const apiUrl = `https://api.useapi.net/v1/minimax/speech/config/?account=${account}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
account = "Previously configured account"
apiUrl = f"https://api.useapi.net/v1/minimax/speech/config/?account={account}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/get-minimax-speech-equity ===
Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-speech-equity
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> speech/equity
description: "Check how many voice cloning slots an account has used and how many it holds via GET speech/equity in the useapi.net MiniMax API v1, before spending twenty seconds on a clone that cannot be saved."
parent: MiniMax API v1
nav_order: 1900
---
## Voice Cloning Quota
<small>August 24, 2026</small>

---

Returns how many cloned voice slots the MiniMax account holds and how many are in use.

Worth calling before [POST speech/clone-voice](/docs/api-minimax-v1/post-minimax-speech-clone-voice), which spends around twenty seconds building a voice. Without this the only signal that an account is out of slots arrives after that work is done.
> **https://api.useapi.net/v1/minimax/speech/equity?account={account}**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

##### Query Parameters

- `account` is optional when only one account is configured. If you have several MiniMax accounts configured, this parameter becomes **required**.

##### Responses 

**200**
**200 OK**
```json
{
  "used": 3,
  "total": 3,
  "voice_clone_preview_free_quota": "inf",
  "srt_download": false,
  "base_resp": {}
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**596**
**596 Account Error**
```json
{
  "error": "Your minimax account has pending error. Please address this issue at https://useapi.net/docs/api-minimax-v1/post-minimax-accounts-account before making any new API calls.",
  "code": 596
}
```

##### Model
```typescript
{ // TypeScript, all fields are optional
  used: number,                            // Cloned voices currently stored
  total: number,                           // Slots the plan grants
  voice_clone_preview_free_quota: string,  // Free clone previews left, "inf" when unlimited
  srt_download: boolean                    // Whether the plan includes SRT download on minimax.io
}
```

- `used` is allowed to exceed `total`. An account observed with three slots reported four in use, so treat these figures as advisory rather than as a hard gate — the authoritative refusal is the error returned by [POST speech/clone-voice](/docs/api-minimax-v1/post-minimax-speech-clone-voice) itself.
- Slots are freed by [POST speech/delete-voice](/docs/api-minimax-v1/post-minimax-speech-delete-voice).
- `srt_download` reflects whether the MiniMax plan includes subtitle downloads on their own site. It does not gate this API — word timings come back on [POST speech/create-mp3](/docs/api-minimax-v1/post-minimax-speech-create-mp3) and the streaming `done` event whatever it says, see [Word timings](/docs/api-minimax-v1/post-minimax-speech-create#word-timings).

##### Examples

**Curl**
```bash
curl "https://api.useapi.net/v1/minimax/speech/equity?account=123456789012345678" \
  -H "Authorization: Bearer …"
```

**JavaScript**
```javascript
const response = await fetch("https://api.useapi.net/v1/minimax/speech/equity?account=123456789012345678", {
  headers: { "Authorization": "Bearer …" }
});

const { used, total } = await response.json();

console.log(`${used} of ${total} voice slots in use`);
```

**Python**
```python
import requests

response = requests.get(
    "https://api.useapi.net/v1/minimax/speech/equity",
    headers={"Authorization": "Bearer …"},
    params={"account": "123456789012345678"}
)

equity = response.json()

print(equity["used"], "of", equity["total"], "voice slots in use")
```

=== URL: https://useapi.net/docs/api-minimax-v1/get-minimax-speech-voices ===
Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-speech-voices
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> speech/voices
description: "Browse MiniMax speech voices via GET speech/voices in the useapi.net MiniMax API v1 — system and cloned voices, filtered by language, gender, age and accent tags."
parent: MiniMax API v1
nav_order: 1898
---
## Retrieve the list of system and cloned audio voices
<small>December 23, 2024 (August 24, 2026)</small>

---

Lists the voices the account can generate with — MiniMax's built-in catalogue, or the ones you have cloned yourself.

600+ pre-built voices, tagged for filtering with `tag_list`:
* Languages: 40, from English, Chinese (Mandarin and Cantonese), Japanese and Korean through to Thai, Hindi, Tamil and Afrikaans
* Emotions: happy, sad, angry, fearful, disgusted, surprised, neutral, fluent
* Accents: `EN-US (General)`, `EN-Australian`, `EN-British`, `EN-Indian`, `CN-Northern`, `CN-Southern`
* Ages: `Child`, `Young`, `Middle-aged`, `Elderly`
* Genders: `Male`, `Female`

`tag_list` matches these strings exactly, including case. A tag it does not recognise is ignored rather than rejected, so a typo silently *widens* the result instead of narrowing it — `Female,Middle-Aged` returns the same 310 voices as `Female` alone, spanning every age. Check the count when you add a filter. [GET speech/config](/docs/api-minimax-v1/get-minimax-speech-config) returns the tags the picker UI offers, updated as MiniMax adds to them. Voices carry others besides — `Documentary`, `Calm` and `Adult` all match voices without appearing there.
> **https://api.useapi.net/v1/minimax/speech/voices/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](/docs/api-minimax-v1/get-minimax-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

- `tag_list` is optional. Specify a comma-separated list of tags using those returned by [GET speech/config](/docs/api-minimax-v1/get-minimax-speech-config) to narrow down the returned results.    
  Example: `Italian,Female`
  
- `page` and `page_size` are optional. Use them to retrieve the next page of data when the returned `has_more` field is `true`.   
  Default `page_size` is 500.  

- `is_system` is optional. Set to `false` if you want to retrieve a list of custom voices cloned via [POST speech/clone-voice](/docs/api-minimax-v1/post-minimax-speech-clone-voice). The entire list of custom voices will be returned at once, the `page` and `page_size` parameters will not be used.  
  Default is `true` (return system voices).  

##### Responses 

**200**
**200 OK**  

`GET` [https://api.useapi.net/v1/minimax/speech/voices/?tag_list=Italian,Female](https://api.useapi.net/v1/minimax/speech/voices/?tag_list=Italian,Female)

```json
{
    "voice_list": [
        {
            "voice_id": "209544421245048",
            "parent_voice_id": "0",
            "voice_name": "Diligent Leader",
            "tag_list": [
                "Italian",
                "Female",
                "Adult",
                "Calm",
                "Standard"
            ],
            "file_id": "",
            "cover_url": "https://cdn.hailuoai.video/moss/staging/2024-11-21-14/moss-audio/voice_cover//1732171514479796864-207331589841022.png?x-oss-process=image/resize,p_50/format,webp",
            "create_time": 1732711650948,
            "update_time": 1732711650948,
            "collected": false,
            "voice_status": 2,
            "sample_audio": "https://cdn.hailuoai.video/moss/staging/2024-11-25-20/moss-audio/voice_sample_audio/1732537441602153587-official_sample_audio/4_it05.mp3",
            "uniq_id": "Italian_DiligentLeader",
            "group_id": "0"
        }
    ],
    "total": 1,
    "has_more": false
}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**596**
**596 Account Error**
```json
{
  "error": "Your minimax account has pending error. Please address this issue at https://useapi.net/docs/api-minimax-v1/post-minimax-accounts-account before making any new API calls.",
  "code": 596
}
```

##### Model 

```typescript
{   // TypeScript, all fields are optional
    voice_list: {
        voice_id: string
        parent_voice_id: string
        voice_name: string
        tag_list: string[]
        file_id: string
        cover_url: string
        create_time: number
        update_time: number
        collected: boolean
        voice_status: number
        sample_audio: string
        uniq_id: string
        group_id: string
    }[]
    total: number
    has_more: boolean
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/minimax/speech/voices/?account=account" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const account = "Previously configured account"; 
const apiUrl = `https://api.useapi.net/v1/minimax/speech/voices/?account=${account}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
account = "Previously configured account"
apiUrl = f"https://api.useapi.net/v1/minimax/speech/voices/?account={account}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/get-minimax-speech ===
Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-speech
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> speech
description: "List every speech recording on a MiniMax account via GET speech in the useapi.net MiniMax API v1 — newest first, with audio URLs, voice names and subtitle availability."
parent: MiniMax API v1
nav_order: 1896
---
## Retrieve the list of text-to-speech audio clips you have generated
<small>December 23, 2024 (August 24, 2026)</small>

---

This endpoint will return audio clips generated by 

* [POST speech/create](/docs/api-minimax-v1/post-minimax-speech-create)
* [POST speech/create-mp3](/docs/api-minimax-v1/post-minimax-speech-create-mp3)
> **https://api.useapi.net/v1/minimax/speech/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](/docs/api-minimax-v1/get-minimax-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

- `page` and `page_size` are optional. Use them to retrieve the next page of data when the returned `has_more` field is `true`.   
  Default `page_size` is 100.  

##### Responses 

**200**
**200 OK**  

```json
{
    "audio_list": [
        {
            "audio_id": "user:user_id-minimax:account_id-audio:audio_id",
            "audio_review": 0,
            "user_id": "123456789012345678",
            "audio_title": "<Audio title>",
            "audio_url": "https://cdn.hailuoai.video/...mp3",
            "update_time": 1122334455780
        },
        {
            "audio_id": "user:user_id-minimax:account_id-audio:audio_id",
            "audio_review": 0,
            "user_id": "123456789012345678",
            "audio_title": "Audio title",
            "audio_url": "https://cdn.hailuoai.video/...mp3",
            "update_time": 1122334455779
        }
    ],
    "total": 2025,
    "has_more": true
}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**596**
**596 Account Error**
```json
{
  "error": "Your minimax account has pending error. Please address this issue at https://useapi.net/docs/api-minimax-v1/post-minimax-accounts-account before making any new API calls.",
  "code": 596
}
```

##### Model 

```typescript
{   // TypeScript, all fields are optional
    audio_list: {
        audio_id: string
        audio_review: number
        user_id: string    // The MiniMax account id
        audio_title: string
        audio_url: string
        update_time: number
        text: string
        voice_name: string
        status: number
        async: number
        has_srt: boolean   // Word timings are available for this recording
        has_wav: boolean   // A WAV rendition exists alongside the MP3
    }[]
    total: number
    has_more: boolean
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/minimax/speech/?account=account" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const account = "Previously configured account"; 
const apiUrl = `https://api.useapi.net/v1/minimax/speech/?account=${account}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
account = "Previously configured account"
apiUrl = f"https://api.useapi.net/v1/minimax/speech/?account={account}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/get-minimax-speech_audio_id ===
Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-speech_audio_id
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> speech/`audio_id`
description: "Poll or retrieve one speech recording via GET speech/audioId in the useapi.net MiniMax API v1 — pending and failed states, credit cost, model, voice and applied effects."
parent: MiniMax API v1
nav_order: 1897
---
## Retrieve text-to-speech audio clip
<small>December 23, 2024 (August 24, 2026)</small>

---

This endpoint will return audio clip generated by 

* [POST speech/create](/docs/api-minimax-v1/post-minimax-speech-create)
* [POST speech/create-mp3](/docs/api-minimax-v1/post-minimax-speech-create-mp3)
> **https://api.useapi.net/v1/minimax/speech/`audio_id`**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Path parameter
- `audio_id` is **required**. Specify audio clip you want to retrieve.

**Notes:**

- Accepts an `audioId` returned by [POST speech/create](/docs/api-minimax-v1/post-minimax-speech-create) as well as any `audio_id` listed by [GET speech](/docs/api-minimax-v1/get-minimax-speech).
- While a generation from [POST speech/create](/docs/api-minimax-v1/post-minimax-speech-create) is still running, the response is `{"statusLabel": "pending", "statusFinal": false}` with no `audio_url`. Poll until `statusFinal` is `true`, or supply a `replyUrl` and let the callback tell you.
- A generation that never completed reports `statusLabel: "failed"` with `code` and `error` describing why. Cancelling one with [DELETE scheduler/`id`](/docs/api-minimax-v1/del-minimax-scheduler-videoId) puts it in the same state.
- An `audioId` issued by [POST speech/create](/docs/api-minimax-v1/post-minimax-speech-create) resolves for 7 days. After that use [GET speech](/docs/api-minimax-v1/get-minimax-speech) to find the recording, which stays on the account.

##### Responses 

**200**
**200 OK**  

```json
{
    "audio_id": "user:user_id-minimax:account_id-audio:audio_id",
    "audio_review": 0,
    "voice_info": {
        "voice_id": "209533299589184",
        "parent_voice_id": "0",
        "voice_name": "Calm Woman",
        "tag_list": [
            "English",
            "Female",
            "Adult",
            "Audiobook",
            "US (General)"
        ],
        "file_id": "",
        "cover_url": "https://cdn.hailuoai.video/...png",
        "create_time": 1122334455667,
        "update_time": 1122334455668,
        "collected": false,
        "voice_status": 2,
        "sample_audio": "https://cdn.hailuoai.video/...mp3",
        "uniq_id": "English_CalmWoman",
        "group_id": "0"
    },
    "text": "<Text>",
    "audio_url": "https://cdn.hailuoai.video/...mp3",
    "audio_title": "<Title>",
    "create_time": 1122334455667,
    "emotion": "Auto",
    "language_boost": "Auto",
    "speed": 1,
    "pitch": 0,
    "update_time": 0,
    "effects": {
        "deepen_lighten": 0,
        "stronger_softer": 0,
        "nasal_crisp": 0,
        "spacious_echo": true,
        "lofi_telephone": false,
        "robotic": false,
        "auditorium_echo": false
    },
    "statusLabel": "completed",
    "statusFinal": true
}
```

While the generation is still running:

```json
{
    "audioId": "user:12345-minimax:123456789012345678-audio:178737039436895391",
    "status": 0,
    "statusLabel": "pending",
    "statusFinal": false
}
```

And when it failed, or was still unfinished after the 10-minute tracking window:

```json
{
    "audioId": "user:12345-minimax:123456789012345678-audio:178737039436895391",
    "status": 3,
    "statusLabel": "failed",
    "statusFinal": true,
    "code": 400,
    "error": "More than 10 minutes have passed, the task has expired."
}
```

Poll on `statusFinal` rather than `status` — `statusLabel` and `statusFinal` are added by useapi.net, because every MiniMax history row reports `status` `0` whether or not it finished.

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**

Returned with an empty body when MiniMax no longer holds the recording, for example once it has been deleted.

**596**
**596 Account Error**
```json
{
  "error": "Your minimax account has pending error. Please address this issue at https://useapi.net/docs/api-minimax-v1/post-minimax-accounts-account before making any new API calls.",
  "code": 596
}
```

##### Model 

```typescript
{   // TypeScript, all fields are optional
  audio_id: string
  audio_review: number
  voice_info: {
      voice_id: string
      parent_voice_id: string
      voice_name: string
      tag_list: string[]
      file_id: string
      cover_url: string
      create_time: number
      update_time: number
      collected: boolean
      voice_status: number
      sample_audio: string
      uniq_id: string
      group_id: string
  }
  text: string
  audio_url: string
  audio_title: string
  create_time: number
  emotion: string
  language_boost: string
  speed: number
  pitch: number
  volume: number
  update_time: number
  model: string        // The speech model used
  cost_credit: number  // Credits this generation cost
  is_first: boolean
  status: number
  statusLabel: string  // completed once audio_url is set, otherwise processing
  statusFinal: boolean
  async: number
  has_srt: boolean
  has_wav: boolean
  effects: {
      deepen_lighten: number
      stronger_softer: number
      nasal_crisp: number
      spacious_echo: boolean
      lofi_telephone: boolean
      robotic: boolean
      auditorium_echo: boolean
  }
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/minimax/speech/audio_id" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const audio_id = "audio_id to retrieve"; 
const apiUrl = `https://api.useapi.net/v1/minimax/speech/${audio_id}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
audio_id = "audio_id to retrieve"
apiUrl = f"https://api.useapi.net/v1/minimax/speech/{audio_id}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/get-minimax-videos-agent-templates ===
Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-videos-agent-templates
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> videos/agent-templates
description: "List available agent video templates via GET videos/agent-templates in the useapi.net MiniMax API v1 for use with POST videos/agent-create."
parent: MiniMax API v1
nav_order: 701
---
## Retrieve available agent video templates
<small>June 30, 2025</small>

---

Use [hailuoai.video](https://hailuoai.video) account to retrieve available agent video templates, see [Setup MiniMax](/docs/start-here/setup-minimax) for details.

Templates can be used with [POST videos/agent-create](/docs/api-minimax-v1/post-minimax-videos-agent-create) to generate videos.
> **https://api.useapi.net/v1/minimax/videos/agent-templates/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](/docs/api-minimax-v1/get-minimax-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

- `templateId` is optional, specify a template ID to get detailed information for a specific template including input requirements.

- `limit` is optional, specify the number of templates to return. Default 30.

- `lastId` is optional, specify the template id from where to start pagination.

##### Responses 

**200**
**200 OK**  

**Template List Response** (when `templateId` is not provided):

```json
{
    "videoList": [
        {
            "id": "1122334455667788",
            "createTime": 1702953600000,
            "videoAsset": {
                "id": "video_asset_id",
                "desc": "Template description",
                "coverURL": "https://example.com/cover.jpg",
                "videoURL": "https://example.com/video.mp4",
                "status": 2,
                "width": 1280,
                "height": 720,
                "duration": 10,
                "resolution": 1,
                "title": "Template Title",
                "agentTemplateID": "1122334455667788",
                "agentTemplateName": "Template Name",
                "downloadURL": "https://example.com/download.mp4",
                "hasVoice": true,
                "modelID": "model_123",
                "useOriginPrompt": false,
                "isBookmarked": false,
                "disableGenerateSimilar": false,
                "postStatus": 1,
                "userID": 123456,
                "createType": 1,
                "promptImgURL": "https://example.com/prompt.jpg",
                "aspectRatio": "16:9",
                "tags": [
                    {
                        "type": "style",
                        "tagIcon": "https://example.com/icon.png",
                        "tagText": "Cinematic"
                    }
                ],
                "humanCheckStatus": 1,
                "userIDStr": "123456"
            },
            "like": {
                "likes": 42,
                "likeStatus": 0
            },
            "author": {
                "userID": "user123",
                "name": "Author Name",
                "avatar": "https://example.com/avatar.jpg"
            },
            "cardType": 1,
            "tabID": "template"
        }
    ],
    "hasPre": false,
    "hasNext": true
}
```

**Template Details Response** (when `templateId` is provided):

```json
{
    "id": "1122334455667788",
    "createTime": 1702953600000,
    "videoAsset": {
        "id": "video_asset_id",
        "desc": "Template description",
        "coverURL": "https://example.com/cover.jpg",
        "videoURL": "https://example.com/video.mp4",
        "status": 2,
        "width": 1280,
        "height": 720,
        "duration": 10,
        "resolution": 1,
        "title": "Template Title",
        "agentTemplateID": "1122334455667788",
        "agentTemplateName": "Template Name"
    },
    "like": {
        "likes": 42,
        "likeStatus": 0
    },
    "author": {
        "userID": "user123",
        "name": "Author Name",
        "avatar": "https://example.com/avatar.jpg"
    },
    "cardType": 1,
    "tabID": "template",
    "credits": 100,
    "requirePrompt": true,
    "requireImage": true,
    "prompt": "Template prompt",
    "inputs": [
        {
            "name": "text_input",
            "type": "text",
        },
        {
            "name": "image_input", 
            "type": "image",
        }
    ]
}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**

```json
{
  "error": "The video or template you are trying to use does not exist or has been deleted."
}
```

##### Model 

```typescript
{   // TypeScript, template list response
    videoList: {
        id: string
        createTime: number
        videoAsset: {
            id: string
            desc: string
            coverURL: string
            videoURL: string
            status: number
            width: number
            height: number
            duration: number
            resolution: number
            title: string
            agentTemplateID: string
            agentTemplateName: string
            downloadURL?: string
            hasVoice?: boolean
            modelID?: string
            useOriginPrompt?: boolean
            isBookmarked?: boolean
            disableGenerateSimilar?: boolean
            postStatus?: number
            userID?: number
            createType?: number
            promptImgURL?: string
            aspectRatio?: string
            tags?: {
                type: string
                tagIcon: string
                tagText: string
            }[]
            humanCheckStatus?: number
            userIDStr?: string
        }
        like: {
            likes: number
            likeStatus: number
        }
        author: {
            userID: string
            name: string
            avatar: string
        }
        cardType: number
        tabID: string
    }[]
    hasPre: boolean
    hasNext: boolean
}

{   // TypeScript, template details response (when templateId provided)
    id: string
    createTime: number
    videoAsset: {} // Same structure as above
    like: {} // Same structure as above
    author: {} // Same structure as above
    cardType: number
    tabID: string
    credits: number
    requirePrompt: boolean
    requireImage: boolean
    prompt: string
    inputs: {
        name: string
        type: "text" | "image"
    }[]
}
```

##### Examples

**Curl**
``` bash
# Get list of templates
curl "https://api.useapi.net/v1/minimax/videos/agent-templates/?account=account&limit=10" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 

# Get specific template details
curl "https://api.useapi.net/v1/minimax/videos/agent-templates/?templateId=1122334455667788" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
// Get list of templates
const token = "API token";
const account = "Previously configured account"; 
const apiUrl = `https://api.useapi.net/v1/minimax/videos/agent-templates/?account=${account}&limit=10`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("Templates:", {response, result});

// Get specific template details
const templateId = "1122334455667788";
const detailUrl = `https://api.useapi.net/v1/minimax/videos/agent-templates/?templateId=${templateId}`;
const detailResponse = await fetch(detailUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const templateDetails = await detailResponse.json();
console.log("Template details:", {detailResponse, templateDetails});
```

**Python**
``` python
import requests

# Get list of templates
token = "API token"
account = "Previously configured account"
apiUrl = f"https://api.useapi.net/v1/minimax/videos/agent-templates/?account={account}&limit=10"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print("Templates:", response, response.json())

# Get specific template details
template_id = "1122334455667788"
detail_url = f"https://api.useapi.net/v1/minimax/videos/agent-templates/?templateId={template_id}"
detail_response = requests.get(detail_url, headers=headers)
print("Template details:", detail_response, detail_response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/get-minimax-videos-characters ===
Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-videos-characters
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> videos/characters
description: "List your saved Subject Reference characters via GET videos/characters in the useapi.net MiniMax API v1 — the same roster shown in the Hailuo 'My Characters' panel."
parent: MiniMax API v1
nav_order: 800
---
## Retrieve the list of characters
<small>January 9, 2025 (March 17, 2025)</small>

---

Use [hailuoai.video](https://hailuoai.video) account to retrieve list of generated videos, see [Setup MiniMax](/docs/start-here/setup-minimax) for details.

This endpoint returns a list of previously created characters, the same list you see when navigating to Subject Reference » Add Reference Character » My Characters.
> **https://api.useapi.net/v1/minimax/videos/characters/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](/docs/api-minimax-v1/get-minimax-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

- `page` is optional, specify the page number. Default 1.

- `pageSize` is optional, specify number of items to return. Default 50.

##### Responses 

**200**
**200 OK**  

Field `cdnUrl` contains a link to the originally uploaded file.  
Field `promptImgUrl` contains a link to the detected character face from the file mentioned above.

```json
[
    {
        "characterID": "1234567890",
        "characterType": 1,
        "file": {
            "fileID": "user:user_id-minimax:account-file:file_id",
            "cdnUrl": "https://cdn.hailuoai.video/...jpeg",
            "promptImgUrl": "https://cdn.hailuoai.video/..."
        }
    }
]
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model 
    
```typescript
{   // TypeScript, all fields are optional
    characterID: string
    characterType: number
    file: {
        fileID: string
        cdnUrl: string
        promptImgUrl: string
    }
}[]
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/minimax/videos/characters/?account=account" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const account = "Previously configured account"; 
const apiUrl = `https://api.useapi.net/v1/minimax/videos/characters/?account=${account}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
account = "Previously configured account"
apiUrl = f"https://api.useapi.net/v1/minimax/videos/characters/?account={account}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/get-minimax-videos-videoId ===
Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-videos-videoId
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> videos/`videoId`
description: "Poll the status and retrieve results of a video generation by videoId via GET videos/videoId in the useapi.net MiniMax API v1."
parent: MiniMax API v1
nav_order: 600
---
## Retrieve video 
<small>September 25, 2024 (June 26, 2026)</small>

---

Use this endpoint to retrieve status and results of

* [videos/create](/docs/api-minimax-v1/post-minimax-videos-create)
> **https://api.useapi.net/v1/minimax/videos/`videoId`**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Path parameter
- `videoId` is **required**. Specify the videoId you want to retrieve.   

##### Responses 

**200**
**200 OK**  

```json
{
  "id": "id",
  "desc": "<prompt>",
  "coverURL": "<cover url>",
  "videoURL": "<generated video with watermark url>",
  "downloadURL": "<generated video without watermark (paid accounts) url>",
  "status": 2,
  "statusLabel": "completed",
  "statusFinal": true,
  "percent": 100,
  "width": 1300,
  "height": 760,
  "originFiles": [
    {
      "id": "user:user_id-minimax:account-file:file_id",
      "url": "<file url>",
      "type": "png"
    }
  ],
  "canAppeal": false,
  "canRetry": false,
  "videoId": "user:user_id-minimax:account-video:id"
}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**404**
**404 Not Found**  

This most often means that the video was moderated and removed after it was generated.

```json
{
    "error": "Not found.",
    "code": 404
}
```

##### Model 

Known `status` values:

* **0** pending
* **1** processing
* **2** completed 
* **3** failed 
* **5** moderated
* **7** moderated
* **11** queued
* **12** processing
* **14** moderated
* **16** moderated (input reference rejected, e.g. Seedance "Face Detected")

Optional fields `message` and `percent` will contain generation progress information.
  
```typescript
{   // TypeScript, all fields are optional
    id: string
    desc: string
    coverURL: string
    videoURL: string
    downloadURL: string
    status: number
    statusLabel: string
    statusFinal: boolean
    message: string // Contains the message shown to the user while the video is being processed
    percent: number // Contains 0-100 percent while the video is being processed
    width: number
    height: number
    originFiles: {
      id: string
      url: string
      type: string
    }[]
    canAppeal: boolean    
    canRetry: boolean
    videoId: string
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/minimax/videos/videoId" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const videoId = "videoId to retrieve"; 
const apiUrl = `https://api.useapi.net/v1/minimax/videos/${videoId}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
videoId = "videoId to retrieve"
apiUrl = f"https://api.useapi.net/v1/minimax/videos/{videoId}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/get-minimax-videos ===
Document URL: https://useapi.net/docs/api-minimax-v1/get-minimax-videos
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-get">GET</code> videos
description: "List all videos you have generated via GET videos in the useapi.net MiniMax API v1 — paginated with limit and lastVideoId cursor parameters."
parent: MiniMax API v1
nav_order: 700
---
## Retrieve the list of videos you have generated
<small>September 25, 2024 (March 17, 2025)</small>

---

Use [hailuoai.video](https://hailuoai.video) account to retrieve list of generated videos, see [Setup MiniMax](/docs/start-here/setup-minimax) for details.
> **https://api.useapi.net/v1/minimax/videos/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Query Parameters

- `account` is optional when only one [account](/docs/api-minimax-v1/get-minimax-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

- `limit` is optional, specify the number of videos to return. Default 30.

- `lastVideoId` is optional, specify the video id from where to start.

##### Responses 

**200**
**200 OK**  

```json
[
    {
        "id": "video_id_#1",
        "desc": "",
        "coverURL": "",
        "videoURL": "",
        "status": 1,
        "statusLabel": "processing",
        "statusFinal": false,
        "message": "<Message from chairman Xi>",
        "width": 0,
        "height": 0,
        "originFiles": [],
        "canAppeal": false,
        "canRetry": false,
        "videoId": "user:user_id-minimax:account-video:video_id_#1"
    },
    {
        "id": "video_id_#2",
        "desc": "<prompt>",
        "coverURL": "<cover url>",
        "videoURL": "<generated video with watermark url>",
        "downloadURL": "<generated video without watermark (paid accounts) url>",
        "status": 2,
        "statusLabel": "completed",
        "statusFinal": true,
        "width": 1300,
        "height": 760,
        "originFiles": [
            {
                "id": "user:user_id-minimax:account-file:file_id",
                "url": "<file url>",
                "type": "png"
            }
        ],
        "canAppeal": false,
        "canRetry": false,
        "videoId": "user:user_id-minimax:account-video:video_id_#2"
    }
]
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model 

Known `status` values:

* **0** pending
* **1** processing
* **2** completed 
* **3** failed  
* **5** moderated
* **7** moderated
* **11** queued
* **12** processing
* **14** moderated
    
```typescript
{   // TypeScript, all fields are optional
    id: string
    desc: string
    coverURL: string
    videoURL: string
    downloadURL: string
    status: number
    statusLabel: string
    statusFinal: boolean
    message: string,
    width: number
    height: number
    originFiles: {
      id: string
      url: string
      type: string
    }[]
    canAppeal: boolean
    canRetry: boolean
    videoId: string
}[]
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/minimax/videos/?account=account" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …" 
```

**JavaScript**
``` javascript
const token = "API token";
const account = "Previously configured account"; 
const apiUrl = `https://api.useapi.net/v1/minimax/videos/?account=${account}`; 
const response = await fetch(apiUrl, {
  headers: {
    "Authorization": `Bearer ${token}`,
  },
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
account = "Previously configured account"
apiUrl = f"https://api.useapi.net/v1/minimax/videos/?account={account}"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/post-minimax-accounts-account ===
Document URL: https://useapi.net/docs/api-minimax-v1/post-minimax-accounts-account
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> accounts
description: "Create or update a MiniMax account configuration via POST accounts in the useapi.net MiniMax API v1 to enable multi-account load balancing."
parent: MiniMax API v1
nav_order: 300
---
## Create or update MiniMax API account configuration
<small>September 25, 2024 (August 17, 2026)</small>

---

See [Setup MiniMax](/docs/start-here/setup-minimax) for details.     

For your convenience, you can specify your MiniMax configuration values under your account. If you specify multiple MiniMax accounts, the API will automatically perform load balancing by randomly selecting an account with available capacity before making calls to MiniMax.
> **https://api.useapi.net/v1/minimax/accounts**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "url": "MiniMax url",
    "token": "MiniMax token",
    "maxJobs": 1-10,
}
```
- `url` and `token` are **required**. Please see [Setup MiniMax](/docs/start-here/setup-minimax) for details. 

- `maxJobs` is **required**. Currently, it should be between 1 and 10. It applies to video and image generations.  
  Music concurrency is not configurable here — MiniMax enforces its own limit and the API surfaces it, see [POST music/create](/docs/api-minimax-v1/post-minimax-music-create).  
  For **video** accounts, please set this number according to your [subscription](https://hailuoai.video/subscribe) plan. We recommend setting it to **2** (3 maximum) for Free, and **3** (4 maximum) for Standard and Unlimited plans. Although you can set it to higher values (3 for Free and 5 for Standard and Unlimited respectively), it won't make any difference since only one video can be processed at a time for Free accounts, and no more than two for Standard and Unlimited accounts. It's helpful to have a spare empty slot for cases where the MiniMax website is too busy and responds with `502` or `504` while still accepting jobs into the internal queue.  

##### Responses 

**201**
**201 Created** 

```json
{
    "account": "123456",
    "jwt": {
        "token": "abc…secured…xyz",
        "user": {
            "deviceID": "123456789",
            "id": "123456",
            "isAnonymous": true,
            "name": "<name>",
            "avatar": "<url>"
        },
        "exp": 1734858598.864,
        "iat": 1732266598.864,
        "host": "hailuoai.video",
        "searchParams": "device_platform=web&app_id=3001&version_code=22201&uuid=b5df53d1-4c0d-4c77-8422-87e3f3b1a1d6&device_id=123456789&os_name=Windows&browser_name=chrome&device_memory=8&cpu_core_num=4&browser_language=en-US&browser_platform=Win32&screen_width=1920&screen_height=1080&unix=1732266598000",
        "iat_Issued": "2024-01-01T00:00:00.000Z",
        "exp_Expire": "2024-12-01T00:00:00.000Z"
    },
    "maxJobs": 1,
    "supportVideo": true,
    "supportChat": true,
    "supportAudio": true
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": 
    "Unauthorized",
    "Wrong username/password combination.",
    "This account has been suspended."
  "code": 401
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  account: string
  jwt: {
    token: string
    user: {
      deviceID: string
      id: string
      isAnonymous: boolean
      name: string
      avatar: string
    },
    exp: number
    iat: number
    host: string
    searchParams: string
    iat_Issued: string
    exp_Expire: string
  }
  maxJobs: number
  supportMusic: boolean
  supportVideo: boolean
  supportAudio: boolean
  supportChat: boolean
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST https://api.useapi.net/v1/minimax/accounts \
     -d '{"url": "…", "token": "…", "maxJobs": …}'
```

**JavaScript**
``` javascript
const url = "MiniMax url";      
const token = "MiniMax token";      
const apiUrl = `https://api.useapi.net/v1/minimax/accounts`; 
const api_token = "API token";
const maxJobs = 1;
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${api_token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  url, token, maxJobs
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
url = "MiniMax url"
token = "MiniMax token"
apiUrl = f"https://api.useapi.net/v1/minimax/accounts" 
api_token = "API token"
maxJobs = 1
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {api_token}"
}
body = {
    "url": f"{url}", 
    "token": f"{token}", 
    "maxJobs": maxJobs
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/post-minimax-agent ===
Document URL: https://useapi.net/docs/api-minimax-v1/post-minimax-agent
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> agent
description: "Run the MiniMax AI Agent via POST agent in the useapi.net MiniMax API v1 to generate video, images, or audio using multiple models in sync or async mode."
parent: MiniMax API v1
nav_order: 2000
---
## Execute AI Agent with Multi-Model Support
<small>November 24, 2025 (February 24, 2026)</small>

---

Execute MiniMax AI Agent with support for multiple AI models including video generation ([Hailuo 2.3](https://hailuoai.video/ai-video-landing/ai-video-generator-hailuo-2-3), [02](https://www.minimax.io/news/minimax-hailuo-02), [Veo 3.1](https://deepmind.google/models/veo/) including S2V subject reference, [Sora 2](https://openai.com/sora/)), image generation ([Midjourney V7/NiJi 7](https://www.midjourney.com/), [Nano Banana 2/Pro](https://blog.google/technology/ai/nano-banana-pro/), [Seedream 4.5/5.0](https://seed.bytedance.com/en/seedream4_5), [Kontext](https://bfl.ai/models/flux-kontext), [Qwen](https://github.com/QwenLM/Qwen-Image), Kolors), and audio synthesis ([Speech 2.5](https://minimax-ai.chat/models/minimax-speech-25/), [Music 2.0](https://www.minimax.io/news/minimax-music-20)).

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](#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](/docs/api-minimax-v1/get-minimax-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](https://hailuoai.video) account to execute agent tasks, see [Setup MiniMax](/docs/start-here/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
``` yaml
Authorization: Bearer {API token}
Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

##### Request Body

Below is a [FormData](https://developer.mozilla.org/en-US/docs/Web/API/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](/docs/api-minimax-v1/get-minimax-accounts) 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:**
  - `hailuo-2.3` - Hailuo 2.3 (highest quality)
  - `hailuo-2.3-fast` - Hailuo 2.3-Fast (faster generation)
  - `hailuo-02` - Hailuo 02

  **Video Models - Veo & Sora:**
  - `veo-3.1` - Veo 3.1 (Google DeepMind)
  - `veo-3.1-fast` - Veo 3.1 Fast
  - `veo-3.1-s2v` - Veo 3.1 S2V (subject reference)
  - `veo-3.1-s2v-fast` - Veo 3.1 S2V Fast
  - `sora-2` - Sora 2 (OpenAI)

  **Image Models - MiniMax:**
  - `nano-banana-2` - Nano Banana 2/Pro
  - `nano-banana` - Nano Banana
  - `seedream` - Seedream 4.5

  **Image Models - Third Party:**
  - `midjourney-v7` - Midjourney V7
  - `midjourney-niji7` - Midjourney NiJi 7
  - `seedream-5.0` - Seedream 5.0 (ByteDance)
  - `kontext` - Kontext (Flux)
  - `qwen` - Qwen Image (Alibaba)
  - `kolors` - Kolors (Kuaishou)

  **Audio Models - TTS:**
  - `speech-2.5-hd-preview` - Speech 2.5 HD Preview
  - `speech-2.5-turbo-preview` - Speech 2.5 Turbo Preview

  **Audio Models - Music:**
  - `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. Callback URL for job completion notifications.
  API will call the provided `replyUrl` once the agent task is completed or failed.
  The callback payload format matches the response [Model](/docs/api-minimax-v1/get-minimax-agent-jobId#model) shown below.
  Maximum length 1024 characters.
  We recommend using sites like [webhook.site](https://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**
**200 OK**

Agent task completed successfully (synchronous mode).

```json
{
    "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"
                    }
                }
            }
        ]
    }
}
```

**201**
**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`](/docs/api-minimax-v1/get-minimax-agent-jobId).

```json
{
    "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**
**400 Bad Request**

Invalid request parameters.

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

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**422**
**422 Unprocessable Content**

Moderated content or invalid file.

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

**429**
**429 Too Many Requests**

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

```json
{
  "error": "Agent generation failed"
}
```

**500**
**500 Internal Server Error**

Agent execution failed.

```json
{
  "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**
**504 Gateway Timeout**

Agent task timed out after 15 minutes.

```json
{
  "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**
**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](https://discord.com/channels/1280370508373950534/1297778596236103762) 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.

```json
{
  "error": "Unusual account activities detected. Please contact customer support at contact@hailuoai.com"
}
```

##### 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 watermark
- `response.attachments[].node.agentFile.noWatermarkUrl` - alternative watermark-free URL
- `response.attachments[].node.agentFile.url` - alternative file URL

```typescript
{
  // 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

**Curl**
``` bash
# 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"
```

**JavaScript**
``` javascript
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);
```

**Python**
``` python
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'])
```

=== URL: https://useapi.net/docs/api-minimax-v1/post-minimax-files ===
Document URL: https://useapi.net/docs/api-minimax-v1/post-minimax-files
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> files
description: "Upload images, audio, or video up to 5 GB via POST files in the useapi.net MiniMax API v1 for use as reference inputs in videos/create and images/create."
parent: MiniMax API v1
nav_order: 3300
---
## Upload image, audio, or video file
<small>October 15, 2024 (May 4, 2026)</small>

---

Use [hailuoai.video](https://hailuoai.video) account to upload image, see [Setup MiniMax](/docs/start-here/setup-minimax) for details.

Upload media (images, audio, video) up to 5GB in size that you want to use as references in [POST videos/create](/docs/api-minimax-v1/post-minimax-videos-create) or [POST images/create](/docs/api-minimax-v1/post-minimax-images-create).

Supported formats:
- **Images** (`.png`, `.jpeg`, `.webp`) — first frame, end frame, character/subject reference, omni image reference. `.webp` uploads via `Content-Type: image/jpeg`.
- **Audio** (`.mp3`, `.wav`) — Seedance omni audio references (`audioFileID1`…`audioFileID3`, resolved as `@Audio1`…`@Audio3`).
- **Video** (`.mp4`) — Seedance omni video references (`videoFileID1`…`videoFileID3`, resolved as `@Video1`…`@Video3`).

Please **be patient**, on average, it takes about 1 minute per GB to upload.

[POST raw content using Make.com and similar nocode tools.](/docs/questions-and-answers#how-post-raw-content-to-runwaymlassets-and-minimaxfiles-using-makecom-and-similar-nocode-tools)
> **https://api.useapi.net/v1/minimax/files/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: select from the table below
```
- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   
- `Content-Type` is **required**, select from the table below:
  
| Content-Type | File Extension | Used for |
| ------------ | -------------- | -------- |
| image/png    | png            | Image references (all video/image models) |
| image/jpeg   | jpeg           | Image references; also `.webp` (uploaded as jpeg) |
| audio/mpeg   | mp3            | Seedance omni audio reference (`audioFileID*`) |
| audio/wav    | wav            | Seedance omni audio reference (`audioFileID*`) |
| video/mp4    | mp4            | Seedance omni video reference (`videoFileID*`) |

##### Query Parameters

- `account` is optional when only one [account](/docs/api-minimax-v1/get-minimax-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

##### Responses 

**200**
**200 OK**  

```json
{
    "ossPath": "<file url>",
    "fileID": "user:user_id-minimax:account-file:file_id"
}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

##### Model 
  
```typescript
{ // TypeScript, all fields are optional
  ossPath: string
  fileID: string
  error: string
  code: number
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/minimax/files/?account=account" \
  -H "Authorization: Bearer …" \
  -H "Content-Type: image/jpeg" \
  --data-binary /path/to/your/image.jpeg
```

**JavaScript**
``` javascript
const token = "API token";
const account = "Previously configured video account"; 
const apiUrl = `https://api.useapi.net/v1/minimax/files/?account=${account}`; 
let blob;
/*
    // Example 1: Fetch image from URL
    const imageUrl = "https://upload.wikimedia.org/wikipedia/commons/7/7d/Mona_Lisa_color_restoration.jpg";
    const responseImage = await fetch(imageUrl);
    blob = await responseImage.blob();
*/
/* 
    // Example 2: Load image from local file (Blob)
    const fsp = require('fs').promises;
    const imageFileName = "./cat.png";
    blob = new Blob([await fsp.readFile(imageFileName)]);
*/
/*
    // Example 3: Load from input file html element
    // <input id="image-file" type="file"> 
    const imageFile = document.getElementById(`image-file`);
    if (imageFile.files[0])
        blob = imageFile.files[0]);
*/
const response = await fetch(apiUrl, {
  method: "POST"
  headers: {
    "Authorization": `Bearer ${token}`,
  },
  body: blob
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
account = "Previously configured video account"
apiUrl = f"https://api.useapi.net/v1/minimax/files/?account={account}"
headers = {
    'Authorization': f'Bearer {token}',
    'Content-Type': 'image/jpeg'
}

# # Example 1: Fetch image from URL
# image_url = "https://upload.wikimedia.org/wikipedia/commons/7/7d/Mona_Lisa_color_restoration.jpg"
# response_image = requests.get(image_url)
# file_content = response_image.content

# # Example 2: Load image from local file
# image_file_path = "./image.jpg"
# with open(image_file_path, 'rb') as image_file:
#     file_content = image_file.read()

response = requests.post(api_url, headers=headers, data=file_content)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/post-minimax-images-create ===
Document URL: https://useapi.net/docs/api-minimax-v1/post-minimax-images-create
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> images/create
description: "Create AI images via POST images/create in the useapi.net MiniMax API v1 — 9 models including Midjourney V7, GPT Image 2, Nano Banana Pro, and Seedream 5.0."
parent: MiniMax API v1
nav_order: 1100
---
## Create an image using a text prompt
## Table of contents
<small>March 17, 2025 (June 26, 2026)</small>
---

Use [hailuoai.video](https://hailuoai.video) account to retrieve list of generated images, see [Setup MiniMax](/docs/start-here/setup-minimax) for details.

##### Model Comparison Matrix

| Model | Resolutions | Aspect Ratios | Ref Images | @-mention |
|:------|:------------|:--------------|:-----------|:---------:|
| image-01 | HD | 16:9 (default), 4:3, 1:1, 3:4, 9:16, 21:9 | 1 via `characterFileId` | — |
| nano-banana-2 | 512P, 1K, 2K, 4K | auto (default), 16:9, 5:4, 4:3, 3:2, 1:1, 2:3, 3:4, 4:5, 9:16, 21:9 | 1-14 via `referenceFileId1`…`14` | ✓ |
| nano-banana-pro | 1K, 2K, 4K | auto (default), 16:9, 5:4, 4:3, 3:2, 1:1, 2:3, 3:4, 4:5, 9:16, 21:9 | 1-14 via `referenceFileId1`…`14` | ✓ |
| gpt-image-1.5 | Low, Medium, High | auto (default), 1:1, 3:2, 2:3 | 1-3 via `referenceFileId1`…`3` | — |
| gpt-image-2 | 1K, 2K, 4K | 16:9 (default), 21:9, 5:4, 4:3, 3:2, 1:1, 2:3, 3:4, 4:5, 9:16 | 1-16 via `referenceFileId1`…`16` | ✓ |
| seedream-4.5 | 2K, 4K | auto (default), 16:9, 5:4, 4:3, 3:2, 1:1, 2:3, 3:4, 4:5, 9:16, 21:9 | 1-14 via `referenceFileId1`…`14` | ✓ |
| seedream-5.0 | 2K, 3K | auto (default), 21:9, 16:9, 5:4, 4:3, 3:2, 1:1, 2:3, 3:4, 4:5, 9:16 | 1-14 via `referenceFileId1`…`14` | ✓ |
| midjourney-v7 | n/a | auto (default), 21:9, 16:9, 5:4, 4:3, 3:2, 1:1, 2:3, 3:4, 4:5, 9:16 | 1-14 via `referenceFileId1`…`14` | — |
| midjourney-niji7 | n/a | auto (default), 21:9, 16:9, 5:4, 4:3, 3:2, 1:1, 2:3, 3:4, 4:5, 9:16 | 1-14 via `referenceFileId1`…`14` | — |

Models with **@-mention** support let you reference uploaded images by slot inside the `prompt` (e.g. `"@Image1 with bokeh background"`). The token is `@Image<N>` where `<N>` is the slot from `referenceFileId<N>`. Case-insensitive: `@IMAGE1`, `@image1`, `@ImAgE001` all canonicalize to `@Image1`. Unsupported models reject prompts containing `@Image<N>` tokens.

<details markdown="block">
<summary><small><b>💲 Credits estimator</b></small></summary>

Credits are charged per image. Actual costs may change, see [hailuoai.video](https://hailuoai.video) for current pricing.

| Model | Resolution | Credits per image | Quantity |
|:------|:-----------|:-----------------:|:---------|
| image-01 | HD | 1 | 1-4 |
| nano-banana-2 | 512P, 1K | 4 | 1-4 |
| nano-banana-2 | 2K | 5 | 1-4 |
| nano-banana-2 | 4K | 8 | 1-4 |
| nano-banana-pro | 1K, 2K | 6 | 1-4 |
| nano-banana-pro | 4K | 10 | 1-4 |
| gpt-image-1.5 | Low | 4 | 1-4 |
| gpt-image-1.5 | Medium | 8 | 1-4 |
| gpt-image-1.5 | High | 15 | 1-4 |
| gpt-image-2 (quality `low`) | 1K | 2 | 1-4 |
| gpt-image-2 (quality `low`) | 2K | 5 | 1-4 |
| gpt-image-2 (quality `low`) | 4K | 10 | 1-4 |
| gpt-image-2 (quality `medium`) | 1K | 8 | 1-4 |
| gpt-image-2 (quality `medium`) | 2K | 20 | 1-4 |
| gpt-image-2 (quality `medium`) | 4K | 40 | 1-4 |
| gpt-image-2 (quality `high`) | 1K | 30 | 1-4 |
| gpt-image-2 (quality `high`) | 2K | 80 | 1-4 |
| gpt-image-2 (quality `high`) | 4K | 160 | 1-4 |
| seedream-4.5 | 2K, 4K | 4 | 1-4 |
| seedream-5.0 | 2K, 3K | 4 | 1-4 |
| midjourney-v7 | n/a | 3 | 4 (fixed) |
| midjourney-niji7 | n/a | 3 | 4 (fixed) |

</details>

To retrieve generated image(s), use:
* [GET images/`imageId`](/docs/api-minimax-v1/get-minimax-images-imageId)
* [GET images](/docs/api-minimax-v1/get-minimax-images)
> **https://api.useapi.net/v1/minimax/images/create**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "account": "Optional MiniMax API account",
    "prompt": "Required text prompt",
    "promptOptimization": true,
    "model": "nano-banana-pro",
    "aspectRatio": "16:9",
    "resolution": "2K",
    "referenceFileId1": "user:…-minimax:…-file:…",
    "referenceFileId2": "user:…-minimax:…-file:…",
    "quantity": 2,
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here"
}
```

##### Parameters

- `account` is optional when only one [account](/docs/api-minimax-v1/get-minimax-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.

- `prompt` is **required**, describe your image.
  Maximum length depends on the model — 2,000 characters for `image-01`, `gpt-image-1.5`, `seedream-4.5`, and `seedream-5.0`, 5,000 for `midjourney-v7` and `midjourney-niji7`, and 7,500 for `gpt-image-2`, `nano-banana-2`, and `nano-banana-pro`.

  **@-mention syntax** (supported by `gpt-image-2`, `nano-banana-pro`, `nano-banana-2`, `seedream-4.5`, `seedream-5.0`): use `@Image1`…`@Image16` in the prompt to reference uploaded images by slot — `@Image1` binds to `referenceFileId1`, `@Image2` to `referenceFileId2`, etc. Tokens are case-insensitive (`@IMAGE1`, `@image1`, `@ImAgE001` all canonicalize to `@Image1`). Models without @-mention support (`image-01`, `gpt-image-1.5`, `midjourney-v7`, `midjourney-niji7`) reject prompts containing `@Image<N>` tokens with a 400.

- `promptOptimization` is optional.
  Supported values: `true` (default), `false`.

- `model` is optional.
  Supported values:
  * `image-01` (default) - Character-focused image generation with HD resolution. Supports character reference via `characterFileId`.
  * `nano-banana-2` - Image generation (512P/1K/2K/4K) with up to 14 reference images. Lower cost flash variant.
  * `nano-banana-pro` - High-resolution image generation (1K/2K/4K) with up to 14 reference images.
  * `gpt-image-1.5` - High-resolution image generation (Low/Medium/High) with up to 3 reference images and limited aspect ratios.
  * `gpt-image-2` - GPT Image 2 (1K/2K/4K, `quality` = low/medium/high) with 10 aspect ratios and up to 16 reference images via `referenceFileId1`…`16` (with @-mention support).
  * `seedream-4.5` - High-resolution image generation (2K/4K) with up to 14 reference images.
  * `seedream-5.0` - High-resolution image generation (2K/3K) with up to 14 reference images.
  * `midjourney-v7` - Midjourney V7 image generation. Always generates 4 images per request (ignores `quantity`). Up to 14 reference images.
  * `midjourney-niji7` - Midjourney NiJi 7 anime-focused image generation. Always generates 4 images per request (ignores `quantity`). Up to 14 reference images.

- `resolution` is optional, model-specific.
  * `image-01`: Only `HD` supported (default).
  * `nano-banana-2`: `512P` (default), `1K`, `2K`, `4K`.
  * `nano-banana-pro`: `1K` (default), `2K`, `4K`.
  * `gpt-image-1.5`: `Low` (default), `Medium`, `High`.
  * `gpt-image-2`: `1K` (default), `2K`, `4K`.
  * `seedream-4.5`: `2K` (default), `4K`.
  * `seedream-5.0`: `2K` (default), `3K`.
  * `midjourney-v7`: Not applicable (no resolution parameter).
  * `midjourney-niji7`: Not applicable (no resolution parameter).

- `aspectRatio` is optional, model-specific.
  * `image-01`: `16:9` (default), `4:3`, `1:1`, `3:4`, `9:16`, `21:9`.
  * `nano-banana-2`: `auto` (default), `16:9`, `5:4`, `4:3`, `3:2`, `1:1`, `2:3`, `3:4`, `4:5`, `9:16`, `21:9`.
  * `nano-banana-pro`: `auto` (default), `16:9`, `5:4`, `4:3`, `3:2`, `1:1`, `2:3`, `3:4`, `4:5`, `9:16`, `21:9`.
  * `gpt-image-1.5`: `auto` (default), `1:1`, `3:2`, `2:3`.
  * `gpt-image-2`: `16:9` (default), `21:9`, `5:4`, `4:3`, `3:2`, `1:1`, `2:3`, `3:4`, `4:5`, `9:16`. (No `auto` — model doesn't accept it.)
  * `seedream-4.5`: `auto` (default), `16:9`, `5:4`, `4:3`, `3:2`, `1:1`, `2:3`, `3:4`, `4:5`, `9:16`, `21:9`.
  * `seedream-5.0`: `auto` (default), `21:9`, `16:9`, `5:4`, `4:3`, `3:2`, `1:1`, `2:3`, `3:4`, `4:5`, `9:16`.
  * `midjourney-v7`: `auto` (default), `21:9`, `16:9`, `5:4`, `4:3`, `3:2`, `1:1`, `2:3`, `3:4`, `4:5`, `9:16`.
  * `midjourney-niji7`: `auto` (default), `21:9`, `16:9`, `5:4`, `4:3`, `3:2`, `1:1`, `2:3`, `3:4`, `4:5`, `9:16`.

- `quality` is optional, **only for `gpt-image-2`**.
  Supported values: `low` (default), `medium`, `high`. Credit cost varies by quality × resolution — see the credits estimator above. Other models reject the `quality` parameter with a 400.

- `characterFileId` is optional, **only for `image-01`**:
    * fileID of the character image uploaded via [POST /files](/docs/api-minimax-v1/post-minimax-files). Upload a clear front-facing photo for best result. Avoid side angles and obstructions.
    * Cannot be used with other models (use `referenceFileId1`…`16` instead).

- `referenceFileId1` … `referenceFileId16` are optional, **for all models except `image-01`**:
    * fileID(s) of reference images uploaded via [POST /files](/docs/api-minimax-v1/post-minimax-files).
    * `gpt-image-2`: Supports 1-16 reference images (`referenceFileId1`…`16`). Supports @-mention syntax in prompt.
    * `nano-banana-2`, `nano-banana-pro`, `seedream-4.5`, `seedream-5.0`: Supports 1-14 reference images. Supports @-mention syntax in prompt.
    * `midjourney-v7`, `midjourney-niji7`: Supports 1-14 reference images. Does **not** support @-mention syntax — `@ImageN` tokens in prompt return 400.
    * `gpt-image-1.5`: Supports 1-3 reference images (`referenceFileId1`…`3` only). Does **not** support @-mention syntax.
    * `image-01`: Use `characterFileId` instead.
    * Slots must be **contiguous starting at 1** — sending `referenceFileId3` without `referenceFileId1`/`2` returns 400.
    * All reference files must belong to the same account.

- `quantity` is optional. Supported range: 1…4, default 1.
  **Note:** `midjourney-v7` and `midjourney-niji7` always generate exactly 4 images per request. The `quantity` parameter is ignored for these models.

- `replyUrl` is optional. Callback URL for job completion notifications.
  API will call the provided `replyUrl` once MiniMax image completed or failed.
  Maximum length 1024 characters.
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /images/`imageId`](/docs/api-minimax-v1/get-minimax-images-imageId) response.

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

##### Responses 

**200**
**200 OK** 

Use returned in array `imageIds` values to retrieve image status and results using [GET images/`imageId`](/docs/api-minimax-v1/get-minimax-images-imageId). Check `videoURL` and/or `downloadURL` (paid account, no watermarks) for generated image with the `status` **2** (Completed).

If you specify the optional parameter [`replyUrl`](/docs/api-minimax-v1/post-minimax-images-create#request-body) the API will call the provided `replyUrl` with image progress updates until the image is complete or fails.

```json
{
    "id": "<image_id_1>",
    "task": {
        "batchID": "<batch_id>",
        "videoIDs": [
            "<image_id_1>",
            "<image_id_2>",
            "<image_id_3>",
            "<image_id_4>"
        ]
    },
    "isFirstGenerate": false,
    "imageIds": [
        "user:<user>-minimax:<account>-image:<image_id_1>",
        "user:<user>-minimax:<account>-image:<image_id_2>",
        "user:<user>-minimax:<account>-image:<image_id_3>",
        "user:<user>-minimax:<account>-image:<image_id_4>"
    ],
    "replyUrl": "https://webhook.site/…",
    "replyRef": "2025-03-11T17:23:05.795Z",
    "code": 200
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>"
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized"
}
```

**412**
**412 Insufficient credits**

Insufficient credits. Please recharge to get more credits or try again next day.

```json
{
  "error": "Insufficient credits. Please recharge to get more credits or try again next day."
}
```

**422**
**422 Unprocessable Content**

Moderated message.

```json
{
  "error": "Your prompt is too short, please provide more details"
}
```

**429**
**429 Too Many Requests**  

Wait in a loop for **at least** 10..30 seconds and retry again.

```json
{
    "error": "There are currently multiple tasks in the queue, and only <number> can be generated at once"
}
```

**596**
**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](https://discord.com/channels/1280370508373950534/1297778596236103762) 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.

```json
{
  "error": "Unusual account activities detected. Please contact customer support at contact@hailuoai.com"
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
  id: string
  task: {
    batchID: string
    videoIDs: string[]
  }
  isFirstGenerate: boolean
  imageIds: string[]
  replyUrl: string
  replyRef: string
  code: number
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST "https://api.useapi.net/v1/minimax/images/create" \
     -d '{"prompt": "…"}'
```

**JavaScript**
``` javascript
const prompt = "text prompt";      
const apiUrl = `https://api.useapi.net/v1/minimax/images/create`; 
const token = "API token";
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  prompt
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
prompt = "text prompt"      
apiUrl = f"https://api.useapi.net/v1/minimax/images/create" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
body = {
    "prompt": f"{prompt}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/post-minimax-music-create ===
Document URL: https://useapi.net/docs/api-minimax-v1/post-minimax-music-create
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> music/create
description: "Generate a song from a prompt, optional lyrics, or a reference track via POST music/create in the useapi.net MiniMax API v1 — Music-3.0 and Music-2.6, covers, instrumental mode, and an SSE stream you can play while it renders."
parent: MiniMax API v1
nav_order: 2900
---
## Create Music
<small>August 17, 2026 (August 21, 2026)</small>

---

This endpoint generates a song from a style prompt and, optionally, your own lyrics. It is powered by [MiniMax Music](https://www.minimax.io/audio/music) — [Music-3.0](https://www.minimax.io/audio/music) is the default, and Music-2.6 remains available.

It also makes covers. Pass `referenceMusicId` and the new song is built in the character of an existing track — see [Covers](#covers).

There are two ways to collect the result, and the response status tells you which one you got.

| Mode | `stream` | Response | Body |
|---|:---:|:---:|---|
| Async (default) | `false` | `201` | JSON with a `musicId` you poll or receive by webhook |
| Streaming | `true` | `200` | `text/event-stream` carrying the audio as it renders |

Streaming lets a player start well before the song is finished — see [Streaming](#streaming). Everything under [Request Body](#request-body) applies to both modes.

Configure a MiniMax account at [POST accounts/account](/docs/api-minimax-v1/post-minimax-accounts-account) before calling this endpoint.

##### Model Comparison: Music

| Feature | Music-3.0 | Music-2.6 |
|---------|:---------:|:---------:|
| Default | ✅ | ❌ |
| `prompt` max length | 2000 | 2000 |
| `lyrics` max length | 3500 | 3500 |
| `title` max length | 40 | 40 |
| Instrumental | ✅ | ✅ |
| Covers (`referenceMusicId`) | ✅ | ✅ |
| Tracks per call | 1-3 | 1-3 |
| Output | MP3 256 kbps<br>44.1 kHz stereo | MP3 256 kbps<br>44.1 kHz stereo |
> **https://api.useapi.net/v1/minimax/music/create**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
  "account": "123456789012345678",
  "prompt": "warm nylon guitar, slow bossa nova, gentle brushes, about a rainy afternoon in Lisbon",
  "lyrics": "[Verse]\nThe tram climbs up the hill\n[Chorus]\nAnd the rain keeps falling still",
  "title": "Lisbon Rain",
  "model": "music-3.0",
  "quantity": 1,
  "instrumental": false,
  "referenceMusicId": "user:12345-minimax:123456789012345678-music:987654321098766",
  "stream": false,
  "replyUrl": "https://webhook.site/abc",
  "replyRef": "your-reference-id"
}
```

- `account` is optional, if not specified API will select the [account](/docs/api-minimax-v1/get-minimax-accounts) with the fewest music generations already running.
- `prompt` is optional, the musical style **and** the subject of the song. Max length `2000`.  
  This one field does two jobs. Describe genre, mood, tempo, instruments and vocal type, and — if you want the lyrics to be about something in particular — say so in the same sentence. A prompt of `melancholic slow piano ballad, female vocals, sparse arrangement` yields lyrics about the mood itself, while the same prompt followed by `, about a lighthouse keeper who lost his dog` yields lyrics about exactly that.
- `lyrics` is optional, your own lyrics. Max length `3500`, where each letter and punctuation mark counts as one character.  
  Leave it out and the model writes the lyrics for you from `prompt`, returning them in the response. Longer lyrics produce longer songs — this is the only way to influence duration, as there is no duration parameter.  
  Structure the words with tags on their own line: `[Intro]`, `[Verse]`, `[Pre-Chorus]`, `[Chorus]`, `[Hook]`, `[Drop]`, `[Bridge]`, `[Solo]`, `[Build-up]`, `[Instrumental]`, `[Breakdown]`, `[Break]`, `[Interlude]`, `[Outro]`. The model may also use tags outside this list in lyrics it writes itself.  
  For wordless vocals, spell the syllables out — `ah, ah, ah` or `la, la, la`.
- `title` is optional, the song name. Max length `40`.
- `model` is optional. Default: `music-3.0`. Supported values: `music-3.0`, `music-2.6`.
- `quantity` is optional, how many tracks to generate from this one call. Default: `1`. Supported values: `1`, `2`, `3`.  
  Each track gets its own `musicId` and finishes independently — they do not complete together.
- `instrumental` is optional, generate music with no vocals. Default: `false`.  
  Leaving `lyrics` empty is **not** enough to get an instrumental — without this flag the model writes its own words and sings them. Cannot be combined with `lyrics` or `referenceMusicId`.
- `referenceMusicId` is optional, the `musicId` of a track the new song should follow. Turns the call into a cover — see [Covers](#covers).  
  Accepts anything on the same account: a file you uploaded with [POST music/reference](/docs/api-minimax-v1/post-minimax-music-reference), or a song this API generated earlier.
- `stream` is optional, return the audio as a Server-Sent Events stream instead of a JSON response. Default: `false`.  
  The streaming response is `200` with `Content-Type: text/event-stream`, not the `201` documented below. See [Streaming](#streaming).
- `replyUrl` is optional, we will send a POST request to this URL when generation completes. Maximum length 1024 characters. Callback body has the same JSON shape as [GET music/`musicId`](/docs/api-minimax-v1/get-minimax-music-musicId#model) response, plus `replyRef`, `replyUrl` and `code`.  
  If a track is still unfinished 15 minutes after it was submitted we stop tracking it and POST `{"code": 400, "error": "More than 15 minutes have passed, the task has expired."}` to the same URL.
- `replyRef` is optional, your own reference string, echoed back on the `replyUrl` callback. Maximum length 1024 characters.

**Notes:**

- Supply `prompt`, `lyrics`, `referenceMusicId`, or a combination. A call with none of them returns `400`.
- You cannot request a length. The model decides how long each song is, and the only way to influence it is the amount of `lyrics` you supply — more words generally means a longer song. This is true of covers too: the reference's own length has no bearing on the result.
- When `quantity` is greater than `1` the tracks are independent songs, not variations of one length. Each gets its own duration, and they finish at different times.
- Generation usually takes a few minutes, varying with the length of the song and how busy MiniMax is. Use `replyUrl` or [GET music/musicId](/docs/api-minimax-v1/get-minimax-music-musicId) rather than assuming a fixed wait.
- One generation per account at a time. MiniMax enforces this, so it counts songs you start on [minimax.io](https://www.minimax.io/audio/music) as well as those started here, and a second request returns `429` until the first finishes.
- Music is billed separately from video and images, at 300 credits a song. A new account has a small allowance to try it; beyond that, music needs a MiniMax audio subscription — covering music and speech — bought from [MiniMax](https://www.minimax.io/audio/music) directly. Without one the call returns `412 Insufficient credits`, however much video credit the account holds.

##### Responses 

**201**
**201 Created**

Returned when `stream` is `false` (the default). With `stream` set to `true` the response is `200` and an event stream instead — see [Streaming](#streaming).
```json
[
  {
    "musicId": "user:12345-minimax:123456789012345678-music:987654321098765",
    "title": "Lisbon Rain",
    "idea": "warm nylon guitar, slow bossa nova, gentle brushes, about a rainy afternoon in Lisbon",
    "lyrics": "[Verse]\nThe tram climbs up the hill\n[Chorus]\nAnd the rain keeps falling still",
    "audio_url": "",
    "cover_url": "https://cdn.hailuoai.video/moss/staging/2025-06-22-16/music_cover/1700000000000000001-other_43.png",
    "model": "music-3.0",
    "status": 1,
    "statusLabel": "processing",
    "statusFinal": false,
    "instrumental": false,
    "duration": 0,
    "create_time": 1786849532637,
    "update_time": 0,
    "is_favorite": false,
    "hasWav": false,
    "tag_list": [
      {
        "tag_name": "warm nylon guitar, slow bossa nova, gentle brushes, about a rainy afternoon in Lisbon",
        "tag_type": 1
      }
    ]
  }
]
```

**400**
**400 Bad Request**
```json
{
  "error": "Please provide prompt, lyrics, or both",
  "code": 400
}
```

`lyrics` cannot be combined with `instrumental`:

```json
{
  "error": "Parameter lyrics cannot be combined with instrumental",
  "code": 400
}
```

**422**
**422 Unprocessable Content**
```json
{
  "error": "Prompt or lyrics were rejected by content moderation",
  "code": 422
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**412**
**412 Precondition Failed**
```json
{
  "error": "Insufficient credits. Please recharge to get more credits or try again next day."
}
```

**429**
**429 Too Many Requests**
```json
{
  "error": "This account already has a music generation running. Retry once it completes.",
  "code": 429
}
```

MiniMax allows one music generation per account at a time and reports this itself, so the limit is theirs rather than ours — it applies to songs you start on [minimax.io](https://www.minimax.io/audio/music) too, not only through this API. Wait for the running track to reach `statusFinal`, or use a different `account`.

**504**
**504 Gateway Timeout**
```json
{
  "error": "No response from minimax music service",
  "code": 504
}
```

The same status covers the other socket-level failures — `Unable to open music WebSocket (HTTP nnn)`, `Music WebSocket failed before the generation was accepted`, and `Music WebSocket closed before the generation was accepted`. All mean the request never reached MiniMax; retry it.

**596**
**596 Account Error**
```json
{
  "error": "Your minimax account has pending error. Please address this issue at https://useapi.net/docs/api-minimax-v1/post-minimax-accounts-account before making any new API calls."
}
```

##### Model
```typescript
{ // TypeScript, all fields are optional
  musicId: string,       // Use with GET music/musicId
  title: string,
  idea: string,          // Echo of the prompt you supplied
  lyrics: string,        // Yours, or written by the model when you leave it empty
  audio_url: string,     // Empty until the track completes
  cover_url: string,     // Cover art, assigned immediately
  model: string,         // music-3.0 | music-2.6
  status: number,        // See the status table on GET music/musicId
  statusLabel: string,
  statusFinal: boolean,
  typeLabel: string,     // "song" here — see GET music
  referenceMusicId: string, // Present only on a cover: the track it follows
  instrumental: boolean,
  duration: number,      // Milliseconds, 0 until complete
  create_time: number,
  update_time: number,
  is_favorite: boolean,
  hasWav: boolean,
  tag_list: [{ tag_name: string, tag_type: number }]
}
```

##### Covers

A cover takes its cues from an existing track. Set `referenceMusicId` and the model reads the reference's character out of the audio itself.

How much of the reference survives depends on how much else you supply. A detailed `prompt` competes with it — the model generates from the brief instead. Given a reference and nothing else, it derives everything from the audio, down to the subject of the lyrics it writes.

The reference can be either of:

- a file you uploaded with [POST music/reference](/docs/api-minimax-v1/post-minimax-music-reference)
- a song this API generated earlier — pass its `musicId` directly, no upload needed

Both live on the same account, and the account is taken from the `referenceMusicId` itself, so `account` is redundant on a cover.

```bash
curl "https://api.useapi.net/v1/minimax/music/create" \
  -H "Authorization: Bearer …" \
  -H "Content-Type: application/json" \
  -d '{
    "referenceMusicId": "user:12345-minimax:123456789012345678-music:987654321098766",
    "prompt": "italo disco, driving synth bass, bright arpeggios",
    "title": "Last Train Italo"
  }'
```

What `lyrics` does on a cover is worth knowing:

| `lyrics` | Result |
|---|---|
| Omitted | The model writes its own words, drawn from what it hears in the reference |
| Supplied | The cover sings your words, and their volume sets the length |
| The reference's own `lyrics` | The cover keeps the original words and lands close to the reference's length — [POST music/reference](/docs/api-minimax-v1/post-minimax-music-reference) returns them, transcribed from the audio |

**Notes:**

- For the closest result, supply the reference's own `lyrics` and no `prompt`. A full style brief pulls the song away from the reference.
- `instrumental` cannot be combined with `referenceMusicId` and returns `400`. MiniMax accepts the pair and then fails the track, so it is rejected here rather than costing you the credits.
- A cover costs the same 300 credits as any other song.
- The response carries `referenceMusicId` back, so a track's origin is visible in [GET music](/docs/api-minimax-v1/get-minimax-music) and [GET music/musicId](/docs/api-minimax-v1/get-minimax-music-musicId) long after the call.
- Only make covers of material you have the rights to use.

##### Streaming

Set `stream` to `true` and the response is `200` with `Content-Type: text/event-stream`, instead of the `201` JSON documented in [Responses](#responses). The audio arrives in chunks as MiniMax renders it, so a player can begin well before the song is finished.

The response carries an `X-Music-Id` header with the `musicId` — comma-separated when `quantity` is greater than `1` — so you can identify or poll the track even if you stop reading the stream.

###### Events

| Event | Description | When Sent |
|---|---|---|
| `progress` | The track record, same shape as the [Model](#model) above | Whenever MiniMax reports a state change |
| `audio` | `{ "musicId": "...", "chunk": "<base64>" }` — a slice of the MP3 | As each chunk is rendered |
| `done` | Array of the finished track records, with `audio_url` and `duration` set | Once **every** track is complete |
| `error` | `{ "error": "...", "code": 422 }` | Moderation rejected the prompt or lyrics, or MiniMax failed mid-generation — `code` carries the mapped HTTP status (`422`, `412`, `429`, `500`) |
| `: keepalive` | An SSE comment, not an event | Every 10 seconds |

###### When the stream ends without `done`

Two cases end the stream with neither `done` nor `error`, so do not block on `done` forever. The upstream connection can drop, which closes the SSE stream where it stands; and there is a hard 10 minute cap on any single stream. In both cases the generation itself keeps going — poll [GET music/musicId](/docs/api-minimax-v1/get-minimax-music-musicId) with the `musicId` from the `X-Music-Id` header to collect the finished track.

###### Knowing when it is finished

Wait for the `done` event. It is the only signal that means the job succeeded, and it fires once every track in the call is complete. For a single track a `progress` event with `statusFinal: true` means the same thing.

Audio stops arriving before the song is finished — do not read that as completion. After the last chunk MiniMax spends up to a minute finalising the file, and only then are `audio_url` and `duration` filled in. A client that stops at the last chunk reports the song as ready while still holding `duration: 0` and an empty `audio_url`.

That gap works in your favour for playback: you have the whole song in hand before `done` arrives, so you can start playing straight away and use `done` only to confirm success and pick up the final metadata.

###### Playing while it generates

Concatenate the base64 `chunk` values in arrival order, per `musicId`. The result is a plain MP3, playable as soon as you have the first chunk.

The stream is silent for the first 20 to 50 seconds while MiniMax renders the opening. Nothing is wrong — the `: keepalive` comments are there to stop proxies closing what looks like an idle connection, and your client should not time out during this. Show the user a "generating" state until the first `audio` event.

After that, playback will not stutter. Audio arrives faster than it plays, so the buffer only ever grows — by the time the first 7 seconds have played you already hold 30 or more, and the full song lands well before playback reaches the end. You do not need to pre-buffer or throttle.

Chunk sizes are uneven — anywhere from a few kilobytes to a couple of megabytes — so append whatever arrives rather than expecting a steady feed.

###### Streaming example

```javascript
const response = await fetch("https://api.useapi.net/v1/minimax/music/create", {
  method: "POST",
  headers: {
    "Authorization": "Bearer …",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    prompt: "gentle fingerpicked acoustic guitar, warm and short",
    instrumental: true,
    stream: true
  })
});

console.log("musicId:", response.headers.get("X-Music-Id"));

const reader = response.body.getReader();
const decoder = new TextDecoder();
const chunks = [];
let buffer = "";

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  buffer += decoder.decode(value, { stream: true });
  const parts = buffer.split("\n\n");
  buffer = parts.pop();

  for (const part of parts) {
    const event = /^event: (.+)$/m.exec(part)?.[1];
    const data = /^data: (.+)$/m.exec(part)?.[1];
    if (!event || !data) continue;

    const payload = JSON.parse(data);

    if (event === "audio")
      chunks.push(Uint8Array.from(atob(payload.chunk), c => c.charCodeAt(0)));
    else if (event === "progress")
      console.log("status:", payload.statusLabel);
    else if (event === "done")
      console.log("finished:", payload[0].duration, "ms");
    else if (event === "error")
      console.error(payload.error);
  }
}

const audio = new Blob(chunks, { type: "audio/mpeg" });
document.querySelector("audio").src = URL.createObjectURL(audio);
```

###### Playing it live with MediaSource

The example above collects every chunk and plays the result at the end. To play *while* the song is still being generated, push each chunk into a [MediaSource](https://developer.mozilla.org/en-US/docs/Web/API/MediaSource) `SourceBuffer` instead.

Two details make or break this. Chunks must be appended **one at a time** — `appendBuffer` throws if the buffer is still updating — so queue them and append on `updateend`. And call `endOfStream()` when the stream finishes, otherwise the element never learns the track has ended.

```html
<audio id="player" controls></audio>
```

```javascript
const player = document.getElementById("player");
const mediaSource = new MediaSource();
player.src = URL.createObjectURL(mediaSource);

const queue = [];
let sourceBuffer = null;
let finished = false;

const pump = () => {
  if (!sourceBuffer || sourceBuffer.updating || queue.length === 0) {
    if (finished && sourceBuffer && !sourceBuffer.updating && queue.length === 0
        && mediaSource.readyState === "open")
      mediaSource.endOfStream();
    return;
  }
  sourceBuffer.appendBuffer(queue.shift());
};

mediaSource.addEventListener("sourceopen", async () => {
  sourceBuffer = mediaSource.addSourceBuffer("audio/mpeg");
  sourceBuffer.addEventListener("updateend", pump);

  const response = await fetch("https://api.useapi.net/v1/minimax/music/create", {
    method: "POST",
    headers: {
      "Authorization": "Bearer …",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      prompt: "gentle fingerpicked acoustic guitar, warm and short",
      instrumental: true,
      stream: true
    })
  });

  const reader = response.body.getReader();
  const decoder = new TextDecoder();
  let buffer = "";

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    buffer += decoder.decode(value, { stream: true });
    const parts = buffer.split("\n\n");
    buffer = parts.pop();

    for (const part of parts) {
      const event = /^event: (.+)$/m.exec(part)?.[1];
      const data = /^data: (.+)$/m.exec(part)?.[1];
      if (!event || !data) continue;

      const payload = JSON.parse(data);

      if (event === "audio") {
        queue.push(Uint8Array.from(atob(payload.chunk), c => c.charCodeAt(0)));
        pump();
        if (player.paused) player.play();
      } else if (event === "done") {
        finished = true;
        pump();
      } else if (event === "error") {
        console.error(payload.error);
        finished = true;
        pump();
      }
    }
  }
});
```

Playback starts as soon as the first chunk lands and runs to the end without stalling, because the stream stays ahead of the playhead.

Browser support. `MediaSource` with `audio/mpeg` works in Chrome, Edge, and Firefox. Safari's MSE support does not cover MP3, so check `MediaSource.isTypeSupported("audio/mpeg")` and fall back to the collect-then-play approach shown earlier.

##### Examples

**Curl**
```bash
curl -X POST "https://api.useapi.net/v1/minimax/music/create" \
  -H "Authorization: Bearer …" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "warm nylon guitar, slow bossa nova, about a rainy afternoon in Lisbon",
    "title": "Lisbon Rain",
    "quantity": 1
  }'
```

**JavaScript**
```javascript
const response = await fetch("https://api.useapi.net/v1/minimax/music/create", {
  method: "POST",
  headers: {
    "Authorization": "Bearer …",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    prompt: "warm nylon guitar, slow bossa nova, about a rainy afternoon in Lisbon",
    title: "Lisbon Rain",
    quantity: 1
  })
});

const tracks = await response.json();
console.log(tracks.map(track => track.musicId));
```

**Python**
```python
import requests

response = requests.post(
    "https://api.useapi.net/v1/minimax/music/create",
    headers={
        "Authorization": "Bearer …",
        "Content-Type": "application/json"
    },
    json={
        "prompt": "warm nylon guitar, slow bossa nova, about a rainy afternoon in Lisbon",
        "title": "Lisbon Rain",
        "quantity": 1
    }
)

for track in response.json():
    print(track["musicId"])
```

=== URL: https://useapi.net/docs/api-minimax-v1/post-minimax-music-reference ===
Document URL: https://useapi.net/docs/api-minimax-v1/post-minimax-music-reference
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> music/reference
description: "Upload an MP3 or WAV as a reference track via POST music/reference in the useapi.net MiniMax API v1 — returns a reusable musicId that POST music/create turns into a cover."
parent: MiniMax API v1
nav_order: 2950
---
## Upload Reference Music
<small>August 21, 2026</small>

---

Uploads an audio file and registers it on the MiniMax account as a reference track. The response carries a `musicId` you pass to [POST music/create](/docs/api-minimax-v1/post-minimax-music-create) as `referenceMusicId`, which produces a **cover** — a new song built in the character of the reference.

Upload once and reuse. A reference is a permanent record on the account, so the same `musicId` can back any number of covers — there is no need to re-send the file per song.

MiniMax transcribes the lyrics from the audio during upload and returns them, which is how you get the original words if you want the cover to keep them.
> **https://api.useapi.net/v1/minimax/music/reference?account={account}&name={name}**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: audio/mpeg
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.
- `Content-Type` is **required** and must match the file you are sending. Supported values: `audio/mpeg`, `audio/mp3`, `audio/wav`, `audio/wave`, `audio/x-wav`.

##### Request Body

The raw bytes of the audio file — not JSON, and not `multipart/form-data`.

##### Query Parameters

- `account` is optional when only one account is configured. If you have several MiniMax accounts configured, this parameter becomes **required**.
- `name` is optional, the title the reference is stored under. Max length `40`. Defaults to a timestamp.

**Notes:**

- Both MP3 and WAV are accepted. MiniMax re-encodes whatever you send to MP3 and serves it back from its own CDN, so the `audio_url` in the response is a re-hosted copy rather than your original file.
- There is no length limit worth planning around. A 20-second excerpt and a full 3-minute song both upload and both work as references.
- The reference does not set the cover's length — `lyrics` does, exactly as it does for an ordinary song. To get a cover close to the reference's length, pass the reference's own `lyrics` back in.
- How strongly the reference comes through varies, and a detailed `prompt` competes with it. Omit `prompt` entirely and the model takes its cues from the audio alone.
- Uploading does not generate anything and costs no credits. Only [POST music/create](/docs/api-minimax-v1/post-minimax-music-create) does.
- References appear in [GET music](/docs/api-minimax-v1/get-minimax-music) under `type=reference`, and are hidden from the default `type=song` listing.
- You do not have to upload at all to make a cover. Any song already on the account works as a reference — pass its `musicId` straight to `referenceMusicId`.
- Only upload audio you have the rights to use.

##### Responses 

**201**
**201 Created**

The reference is ready immediately — `statusLabel` is already `completed` and `audio_url` already points at the stored copy.
```json
{
  "musicId": "user:12345-minimax:123456789012345678-music:987654321098766",
  "title": "Last Train 20s",
  "idea": "",
  "lyrics": "[Chorus]\nin my ear.\n\n[Verse]",
  "audio_url": "https://cdn.hailuoai.video/moss/prod/2026-08-21-09/moss-audio/user_music/1700000000000000000-987654321098766.mp3",
  "cover_url": "https://cdn.hailuoai.video/moss/staging/2025-06-22-16/music_cover/1700000000000000002-other_44.png",
  "model": "",
  "status": 2,
  "statusLabel": "completed",
  "statusFinal": true,
  "typeLabel": "reference",
  "instrumental": false,
  "duration": 20036,
  "create_time": 1787276488868,
  "update_time": 1787276488868,
  "is_favorite": false,
  "tag_list": []
}
```

**400**
**400 Bad Request**

An unsupported `Content-Type`:

```json
{
  "error": "Content-Type (image/png) not supported. Valid values: audio/mpeg,audio/mp3,audio/wav,audio/wave,audio/x-wav",
  "code": 400
}
```

An empty body:

```json
{
  "error": "Content is empty",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**596**
**596 Account Error**
```json
{
  "error": "Your minimax account has pending error. Please address this issue at https://useapi.net/docs/api-minimax-v1/post-minimax-accounts-account before making any new API calls.",
  "code": 596
}
```

##### Model
```typescript
{ // TypeScript, all fields are optional
  musicId: string,       // Pass to POST music/create as referenceMusicId
  title: string,         // The name you supplied
  idea: string,          // Always empty on a reference
  lyrics: string,        // Transcribed from the audio by MiniMax
  audio_url: string,     // MiniMax's re-hosted copy of your file
  cover_url: string,     // Cover art, assigned automatically
  model: string,         // Always empty on a reference
  status: number,        // 2 — a reference is complete on arrival
  statusLabel: string,
  statusFinal: boolean,
  typeLabel: string,     // Always "reference" here
  instrumental: boolean,
  duration: number,      // Milliseconds
  create_time: number,
  update_time: number,
  is_favorite: boolean,
  tag_list: [{ tag_name: string, tag_type: number }]
}
```

##### Examples

**Curl**
```bash
curl "https://api.useapi.net/v1/minimax/music/reference?name=Last%20Train%2020s" \
  -H "Authorization: Bearer …" \
  -H "Content-Type: audio/mpeg" \
  --data-binary "@reference.mp3"
```

**JavaScript**
```javascript
import { readFile } from "node:fs/promises";

const file = await readFile("reference.mp3");

const response = await fetch("https://api.useapi.net/v1/minimax/music/reference?name=Last Train 20s", {
  method: "POST",
  headers: {
    "Authorization": "Bearer …",
    "Content-Type": "audio/mpeg"
  },
  body: file
});

const reference = await response.json();

console.log(reference.musicId, reference.duration, reference.lyrics);
```

**Python**
```python
import requests

with open("reference.mp3", "rb") as file:
    response = requests.post(
        "https://api.useapi.net/v1/minimax/music/reference",
        headers={
            "Authorization": "Bearer …",
            "Content-Type": "audio/mpeg"
        },
        params={"name": "Last Train 20s"},
        data=file.read()
    )

reference = response.json()

print(reference["musicId"], reference["duration"])
print(reference["lyrics"])
```

Then turn it into a cover:

```bash
curl "https://api.useapi.net/v1/minimax/music/create" \
  -H "Authorization: Bearer …" \
  -H "Content-Type: application/json" \
  -d '{
    "referenceMusicId": "user:12345-minimax:123456789012345678-music:987654321098766",
    "prompt": "italo disco, driving synth bass, bright arpeggios",
    "title": "Last Train Italo"
  }'
```

=== URL: https://useapi.net/docs/api-minimax-v1/post-minimax-speech-clone-voice ===
Document URL: https://useapi.net/docs/api-minimax-v1/post-minimax-speech-clone-voice
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> speech/clone-voice
description: "Clone a voice from uploaded samples via POST speech/clone-voice in the useapi.net MiniMax API v1, then narrate with it by passing the returned voice id to any speech call."
parent: MiniMax API v1
nav_order: 1892
---
## Clone a voice using uploaded audio samples
<small>December 27, 2024 (August 24, 2026)</small>

---

Builds a new voice from audio samples uploaded with [POST speech/upload-sample](/docs/api-minimax-v1/post-minimax-speech-upload-sample). The voice it returns can be passed as `voice_id` to any of the speech endpoints.

Cloned voices occupy a slot, and how many an account gets depends on its MiniMax plan. [GET speech/equity](/docs/api-minimax-v1/get-minimax-speech-equity) reports `used` and `total`, and [POST speech/delete-voice](/docs/api-minimax-v1/post-minimax-speech-delete-voice) frees one. Treat the count as advisory rather than as a gate — MiniMax lets `used` exceed `total`, and the authoritative refusal is error `2600010` on the clone itself. If you need more slots than a plan allows, configure another [www.minimax.io/audio](https://www.minimax.io/audio) account.

Please be patient, voice cloning can take up to 60 seconds. This endpoint can only support one or two parallel tasks maximum, so organize internal queuing if you need to clone many voices in bulk.
> **https://api.useapi.net/v1/minimax/speech/clone-voice**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "files": "user:user_id-minimax:account-file:file_id1,user:user_id-minimax:account-file:file_id2",
    "voice_name": "Doctor Who",
    "language_tag": "English"
}
```
- `voice_name` is **required**.   
  Maximum length: 30 characters.

- `language_tag` is **required**. Use tag_name from array `voice_tag_language` of [GET speech/config](/docs/api-minimax-v1/get-minimax-speech-config). 

- `files` is **required**. Provide up to 10 comma-separated `fileID` values of audio samples uploaded via [POST speech/upload-sample](/docs/api-minimax-v1/post-minimax-speech-upload-sample). Each audio sample should be between 10 to 60 seconds long. 

- `need_noise_reduction` is optional.   
  Supported values: `true` (default), `false`.  

##### Responses 

**200**
**200 OK** 

```json
{
    "voice_id": "user:user_id-minimax:account_id-voice:voice_id",
    "parent_voice_id": "0",
    "voice_name": "Doctor Who",
    "tag_list": [
        "English"
    ],
    "file_id": "1234567890",
    "cover_url": "https://cdn.hailuoai.video/...png",
    "create_time": 1122334455667,
    "update_time": 1122334455667,
    "collected": false,
    "voice_status": 2,
    "sample_audio": "https://cdn.hailuoai.video/...mp3",
    "uniq_id": "<uniq_id>",
    "group_id": "<group_id>"
}
```

**400**
**400 Bad Request**

```json
{
  "error": "<Error message>"
}
```

**401**
**401 Unauthorized**

```json
{
  "error": "Unauthorized"
}
```

**596**
**596 Account Error**
```json
{
  "error": "Your minimax account has pending error. Please address this issue at https://useapi.net/docs/api-minimax-v1/post-minimax-accounts-account before making any new API calls.",
  "code": 596
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
    voice_id: string
    parent_voice_id: string
    voice_name: string
    tag_list: string[]
    file_id: string
    cover_url: string
    create_time: number 
    update_time: number 
    collected: boolean
    voice_status: number
    sample_audio: string
    uniq_id: string
    group_id: string
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST https://api.useapi.net/v1/minimax/speech/clone-voice \
     -d '{"voice_name": "…", "language_tag": "…", "files": …}'
```

**JavaScript**
``` javascript
const voice_name = "Voice Name";      
const language_tag = "Voice Language";      
const files = "fileID1,fileID2";      
const apiUrl = `https://api.useapi.net/v1/minimax/speech/clone-voice`; 
const api_token = "API token";
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${api_token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  voice_name, language_tag, files
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
voice_name = "Voice Name"
language_tag = "Voice Language"
files = "fileID1,fileID2" 
apiUrl = f"https://api.useapi.net/v1/minimax/speech/clone-voice" 
api_token = "API token"
maxJobs = 1
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {api_token}"
}
body = {
    "voice_name": f"{voice_name}", 
    "language_tag": f"{language_tag}", 
    "files": files
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/post-minimax-speech-create-mp3 ===
Document URL: https://useapi.net/docs/api-minimax-v1/post-minimax-speech-create-mp3
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> speech/create-mp3
description: "Generate speech and get the MP3 back in a single call via POST speech/create-mp3 in the useapi.net MiniMax API v1 — up to 3,000 characters, ten voice models, word timings."
parent: MiniMax API v1
nav_order: 1860
---
## Create text-to-speech audio 
<small>December 23, 2024 (August 24, 2026)</small>

---

This endpoint creates an mp3 audio from the provided text and returns it in one call.

For longer text use [POST speech/create](/docs/api-minimax-v1/post-minimax-speech-create), which takes 5,000 characters, or 10,000 on a `turbo` model.

600+ pre-built voices provided by [GET speech/voices](/docs/api-minimax-v1/get-minimax-speech-voices), tagged for filtering with `tag_list`:
* Languages: 40, from English, Chinese (Mandarin and Cantonese), Japanese and Korean through to Thai, Hindi, Tamil and Afrikaans
* Emotions: happy, sad, angry, fearful, disgusted, surprised, neutral, fluent
* Accents: `EN-US (General)`, `EN-Australian`, `EN-British`, `EN-Indian`, `CN-Northern`, `CN-Southern`
* Ages: `Child`, `Young`, `Middle-aged`, `Elderly`
* Genders: `Male`, `Female`

`tag_list` matches these strings exactly, including case. A tag it does not recognise is ignored rather than rejected, so a typo silently *widens* the result instead of narrowing it — `Female,Middle-Aged` returns the same 310 voices as `Female` alone, spanning every age. Check the count when you add a filter. [GET speech/config](/docs/api-minimax-v1/get-minimax-speech-config) returns the tags the picker UI offers, updated as MiniMax adds to them. Voices carry others besides — `Documentary`, `Calm` and `Adult` all match voices without appearing there.
> **https://api.useapi.net/v1/minimax/speech/create-mp3**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "account": "Optional MiniMax www.minimax.io/audio API account",
    "text": "Required text",
    "voice_id": "Required voice id"
}
```
- `account` is optional when only one [account](/docs/api-minimax-v1/get-minimax-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

- `text` is **required**, the words to speak. Maximum `3000` characters whatever the model allows, which is around four minutes of speech. Supports [inline markup](/docs/api-minimax-v1/post-minimax-speech-create#text-markup) for emotion, sounds and pauses — for example `<#0.5#>` inserts a half-second pause.  

- `voice_id` is **required**. Use [GET speech/voices](/docs/api-minimax-v1/get-minimax-speech-voices) to get list of all available voices.  

- `model` is optional. Default: `speech-2.8-hd`. See [Model Comparison](#model-comparison-speech) below for the ten models, their character ceilings and their credit ratios.

- `language_boost` is optional. Use tag_name from array `voice_tag_language` of [GET speech/config](/docs/api-minimax-v1/get-minimax-speech-config).  
  Default value `Auto`.

- `emotion` is optional. Use value from array `t2a_emotion` of [GET speech/config](/docs/api-minimax-v1/get-minimax-speech-config).  
  Default value `Auto`.

- `vol` is optional.  
  Default 1.

- `speed` is optional.  
  Valid range: 0.5…2, default 1.

- `pitch` is optional.  
  Valid range: -12…12, default 0.

- `deepen_lighten` is optional.  
  Valid range: -100…100, default 0.

- `stronger_softer` is optional.  
  Valid range: -100…100, default 0.

- `nasal_crisp` is optional.  
  Valid range: -100…100, default 0.

- `spacious_echo` is optional.   
  Supported values: `true`, `false` (default).  

- `lofi_telephone` is optional.   
  Supported values: `true`, `false` (default).  
   
- `robotic` is optional.   
  Supported values: `true`, `false` (default).  

- `auditorium_echo` is optional.   
  Supported values: `true`, `false` (default).  

##### Model Comparison: Speech

| Model | Max characters | Credits per character | Status |
|---|---|---|---|
| `speech-2.8-hd` | 5,000 | 1 | Current, and the default |
| `speech-2.8-turbo` | 10,000 | 0.6 | Current |
| `speech-2.6-hd` | 5,000 | 1 | Previous generation |
| `speech-2.6-turbo` | 10,000 | 0.6 | Previous generation |
| `speech-2.5-hd-preview` | 5,000 | 1 | Superseded by 2.6 |
| `speech-2.5-turbo-preview` | 10,000 | 0.6 | Superseded by 2.6 |
| `speech-02-hd` | 5,000 | 1 | Legacy |
| `speech-02-turbo` | 10,000 | 0.6 | Legacy |
| `speech-01-hd` | 5,000 | 1 | Legacy |
| `speech-01-turbo` | 10,000 | 0.6 | Legacy |

Use `speech-2.8-hd` unless you have a reason not to. The older models stay selectable because they are still live at MiniMax, and because regenerating audio to match something made earlier needs the model that made it — not because they are worth picking for new work.

Within a generation, `hd` and `turbo` are the same model tuned differently. `turbo` costs 40% less per character and accepts twice the text in a single call. It is not measurably faster — on identical 990-character text the two came out level — so pick `turbo` for the cheaper rate and the higher ceiling, and `hd` when voice quality matters most.

Sending more than a model accepts returns `400` before anything is generated, so an oversized request never costs credits. The message names the model and its limit — `Parameter text length (5001) exceeds 5000 characters for model speech-2.8-hd` — except at the absolute 10,000 ceiling, which is checked first and reports the limit without the model.

On this endpoint the per-model ceiling never comes into play — `text` is capped at 3,000 characters whichever model you pick, because the connection is held open for the whole generation and 3,000 characters is about as long as a caller should be asked to wait. The ceilings above apply to [POST speech/create](/docs/api-minimax-v1/post-minimax-speech-create).

##### Responses 

**200**
**200 OK** 

Use returned `audio_url` to download generated mp3 audio file.   
Use returned `audio_id` to retrieve full details using [GET speech/`audio_id`](/docs/api-minimax-v1/get-minimax-speech_audio_id).

```json
{
    "audio_id": "user:user_id-minimax:account_id-audio:audio_id",
    "audio_length": 0,
    "audio_sample_rate": 0,
    "audio_size": 0,
    "bitrate": 0,
    "word_count": 0,
    "invisible_character_ratio": 0,
    "usage_characters": 22,
    "input_sensitive": false,
    "trace_id": "<trace id>",
    "chunks": 2,
    "subtitles": [
        { "text": "Phase one verification", "time_begin": 0, "time_end": 2245.2, "text_begin": 0, "text_end": 22, "timestamped_words": [] }
    ],
    "audio_review": 0,
    "user_id": "123456789012345678",
    "audio_title": "<autogenerated title>",
    "audio_url": "https://cdn.hailuoai.video/...mp3",
    "update_time": 123456789,
    "text": "Phase one verification",
    "voice_name": "Deep Storyteller",
    "status": 0,
    "async": 0,
    "has_srt": true,
    "has_wav": true
}
```

Only `usage_characters` is populated on the size fields — `audio_length`, `audio_sample_rate`, `audio_size` and `bitrate` all come back `0`, which is what MiniMax sends.

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>"
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized"
}
```

**412**
**412 Precondition Failed**

The account cannot pay for the generation. MiniMax reports this two different ways, and both mean the same thing — check the speech balance with [GET features](/docs/api-minimax-v1/get-minimax-features), where `audio.total_credit` is the MiniMax audio wallet the API bills against.

```json
{
  "error": "Insufficient credits. Please recharge to get more credits or try again next day."
}
```

```json
{
  "error": "MiniMax rejected the generation — the account is out of speech credits. Confirm with GET /features (audio.total_credit) and top up at https://www.minimax.io/audio/subscribe."
}
```

**429**
**429 Too Many Requests**

The account already has its maximum number of speech generations in flight. The running generations are unaffected — retry once one finishes. The ceiling depends on the MiniMax plan. A free account allows three.

```json
{
  "error": "This account already has the maximum number of speech generations running. Retry once one completes.",
  "code": 429
}
```

**504**
**504 Gateway Timeout**

The generation did not finish inside the 90 second ceiling this endpoint waits:

```json
{
  "error": "minimax did not finish within 90 seconds. Use POST /v1/minimax/speech/create for text this long.",
  "code": 504
}
```

Or it finished but had not appeared in the account history in time:

```json
{
  "error": "Audio was generated but did not appear in history in time. Call GET /v1/minimax/speech/ to retrieve it.",
  "code": 504
}
```

**596**
**596 Account Error**
```json
{
  "error": "Your minimax account has pending error. Please address this issue at https://useapi.net/docs/api-minimax-v1/post-minimax-accounts-account before making any new API calls.",
  "code": 596
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
    audio_id: string
    audio_length: number
    audio_sample_rate: number
    audio_size: number
    bitrate: number
    word_count: number
    invisible_character_ratio: number
    usage_characters: number
    input_sensitive: boolean
    trace_id: string
    chunks: number         // Non-heartbeat frames received, 2 for a short generation
    subtitles: {           // Per-phrase timings, milliseconds
        text: string
        time_begin: number
        time_end: number
        text_begin: number
        text_end: number
        timestamped_words: []
    }[]
    audio_review: number
    user_id: string        // The MiniMax account id
    audio_title: string
    audio_url: string
    update_time: number
    text: string
    voice_name: string
    status: number
    async: number
    has_srt: boolean       // Word timings are available for this recording
    has_wav: boolean       // A WAV rendition exists alongside the MP3
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST "https://api.useapi.net/v1/minimax/speech/create-mp3" \
     -d '{"text": "…", "voice_id": "…"}'
```

**JavaScript**
``` javascript
const text = "text";      
const voice_id = "voice_id";      
const apiUrl = `https://api.useapi.net/v1/minimax/speech/create-mp3`; 
const token = "API token";
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  text, voice_id
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
text = "text"
voice_id = "voice_id"
apiUrl = f"https://api.useapi.net/v1/minimax/speech/create-mp3" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
body = {
    "text": f"{text}",
    "voice_id": f"{voice_id}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/post-minimax-speech-create ===
Document URL: https://useapi.net/docs/api-minimax-v1/post-minimax-speech-create
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> speech/create
description: "Generate speech from text via POST speech/create in the useapi.net MiniMax API v1 — ten models, emotion and pause markup, word timings, a replyUrl callback or an SSE stream."
parent: MiniMax API v1
nav_order: 1850
---
## Create Speech
<small>August 24, 2026</small>

---

Converts text to speech and returns an `audioId` immediately. Generation continues at MiniMax, and you either wait for the [replyUrl](#request-body) callback or poll [GET speech/`audioId`](/docs/api-minimax-v1/get-minimax-speech_audio_id).

Use it for anything longer than a sentence or two. [POST speech/create-mp3](/docs/api-minimax-v1/post-minimax-speech-create-mp3) holds the connection open until the audio is finished, so it stops at `3,000` characters. This one takes `5,000`, or `10,000` on a `turbo` model — roughly a quarter of an hour of speech.

##### Model Comparison: Speech

| Model | Max characters | Credits per character | Status |
|---|---|---|---|
| `speech-2.8-hd` | 5,000 | 1 | Current, and the default |
| `speech-2.8-turbo` | 10,000 | 0.6 | Current |
| `speech-2.6-hd` | 5,000 | 1 | Previous generation |
| `speech-2.6-turbo` | 10,000 | 0.6 | Previous generation |
| `speech-2.5-hd-preview` | 5,000 | 1 | Superseded by 2.6 |
| `speech-2.5-turbo-preview` | 10,000 | 0.6 | Superseded by 2.6 |
| `speech-02-hd` | 5,000 | 1 | Legacy |
| `speech-02-turbo` | 10,000 | 0.6 | Legacy |
| `speech-01-hd` | 5,000 | 1 | Legacy |
| `speech-01-turbo` | 10,000 | 0.6 | Legacy |

Use `speech-2.8-hd` unless you have a reason not to. The older models stay selectable because they are still live at MiniMax, and because regenerating audio to match something made earlier needs the model that made it — not because they are worth picking for new work.

Within a generation, `hd` and `turbo` are the same model tuned differently. `turbo` costs 40% less per character and accepts twice the text in a single call. It is not measurably faster — on identical 990-character text the two came out level — so pick `turbo` for the cheaper rate and the higher ceiling, and `hd` when voice quality matters most.

Sending more than a model accepts returns `400` before anything is generated, so an oversized request never costs credits. The message names the model and its limit — `Parameter text length (5001) exceeds 5000 characters for model speech-2.8-hd` — except at the absolute 10,000 ceiling, which is checked first and reports the limit without the model.

600+ pre-built voices provided by [GET speech/voices](/docs/api-minimax-v1/get-minimax-speech-voices), tagged for filtering with `tag_list`:
* Languages: 40, from English, Chinese (Mandarin and Cantonese), Japanese and Korean through to Thai, Hindi, Tamil and Afrikaans
* Emotions: happy, sad, angry, fearful, disgusted, surprised, neutral, fluent
* Accents: `EN-US (General)`, `EN-Australian`, `EN-British`, `EN-Indian`, `CN-Northern`, `CN-Southern`
* Ages: `Child`, `Young`, `Middle-aged`, `Elderly`
* Genders: `Male`, `Female`

`tag_list` matches these strings exactly, including case. A tag it does not recognise is ignored rather than rejected, so a typo silently *widens* the result instead of narrowing it — `Female,Middle-Aged` returns the same 310 voices as `Female` alone, spanning every age. Check the count when you add a filter. [GET speech/config](/docs/api-minimax-v1/get-minimax-speech-config) returns the tags the picker UI offers, updated as MiniMax adds to them. Voices carry others besides — `Documentary`, `Calm` and `Adult` all match voices without appearing there.
> **https://api.useapi.net/v1/minimax/speech/create**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.

##### Request Body
```json
{
  "account": "123456789012345678",
  "text": "Good morning. Here is the weather for the week ahead.",
  "voice_id": "380426458095854",
  "model": "speech-2.8-hd",
  "speed": 1,
  "vol": 1,
  "pitch": 0,
  "emotion": "happy",
  "language_boost": "English",
  "stream": false,
  "replyUrl": "https://webhook.site/abc",
  "replyRef": "your-reference-id"
}
```

- `account` is optional when only one account is configured. If you have several MiniMax accounts configured, this parameter becomes **required**.
- `text` is **required**, the words to speak. Max length depends on the model — `5000` for `hd`, `10000` for `turbo`. Supports [inline markup](#text-markup) for emotion, sounds and pauses.
- `voice_id` is **required**, from [GET speech/voices](/docs/api-minimax-v1/get-minimax-speech-voices). Accepts a MiniMax voice id or the `voiceId` of a voice you cloned with [POST speech/clone-voice](/docs/api-minimax-v1/post-minimax-speech-clone-voice).
- `model` is optional. Default: `speech-2.8-hd`. See [Model Comparison](#model-comparison-speech) for the full list.
- `speed` is optional, playback rate. Default: `1`. Range `0.5` to `2`.
- `vol` is optional, volume. Default: `1`. Minimum `1`.
- `pitch` is optional. Default: `0`. Range `-12` to `12`.
- `emotion` is optional. Default: `Auto`. Use a value from the `t2a_emotion` array of [GET speech/config](/docs/api-minimax-v1/get-minimax-speech-config), or leave it out and mark up the text instead.
- `language_boost` is optional, biases pronunciation toward one language. Default: `Auto`.
- `deepen_lighten`, `stronger_softer`, `nasal_crisp` are optional voice effects. Default: `0`. Range `-100` to `100`.
- `spacious_echo`, `lofi_telephone`, `robotic`, `auditorium_echo` are optional effect switches. Default: `false`.
- `stream` is optional, return the audio as Server-Sent Events instead of a JSON response. Default: `false`.  
  The streaming response is `200` with `Content-Type: text/event-stream`, not the `201` documented below. See [Streaming](#streaming).
- `replyUrl` is optional, we will send a POST request to this URL when generation completes. Maximum length 1024 characters. Callback body has the same JSON shape as one row of [GET speech](/docs/api-minimax-v1/get-minimax-speech#model), minus `audio_id`, plus `audioId`, `replyRef`, `replyUrl`, `code`, `statusLabel` and `statusFinal`.  
  It is built from the account history, so it is the lighter list shape — `voice_info`, `model`, `cost_credit` and `effects` are only on [GET speech/`audioId`](/docs/api-minimax-v1/get-minimax-speech_audio_id#model).  
  If a generation is still unfinished 10 minutes after it was submitted we stop tracking it and POST `{"code": 400, "error": "More than 10 minutes have passed, the task has expired."}` to the same URL.
- `replyRef` is optional, your own reference string, echoed back on the `replyUrl` callback. Maximum length 1024 characters.

**Notes:**

- Store the `audioId`. MiniMax assigns no identifier at submit time, so it is the only handle on the generation. It resolves for 7 days.
- Speech is billed per character, 1 credit on an `hd` model and 0.6 on a `turbo` one, rounded up. [GET speech/`audioId`](/docs/api-minimax-v1/get-minimax-speech_audio_id) reports what was charged as `cost_credit`. [POST speech/create-mp3](/docs/api-minimax-v1/post-minimax-speech-create-mp3) reports `usage_characters` instead, the character count before the ratio.
- Generation time scales with the length of the text, from a few seconds up to about 80 seconds at the 10,000-character ceiling. Use `replyUrl` or poll rather than assuming a fixed wait.
- Speech bills against the MiniMax audio subscription, the same one music uses. Without it the call returns `412`, however much video credit the account holds.

##### Responses 

**201**
**201 Created**

```json
{
  "audioId": "user:12345-minimax:123456789012345678-audio:178737039436895391",
  "replyRef": "your-reference-id",
  "replyUrl": "https://webhook.site/abc",
  "status": 0,
  "statusLabel": "pending",
  "statusFinal": false
}
```

**400**
**400 Bad Request**

Text longer than the chosen model accepts:

```json
{
  "error": "Parameter text length (6000) exceeds 5000 characters for model speech-2.8-hd",
  "code": 400
}
```

An unknown `voice_id`:

```json
{
  "error": "Incorrect voice_id (2600006)"
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**412**
**412 Precondition Failed**

The account cannot pay for the generation. MiniMax reports this two different ways, and both mean the same thing — check the speech balance with [GET features](/docs/api-minimax-v1/get-minimax-features), where `audio.total_credit` is the MiniMax audio wallet the API bills against.

```json
{
  "error": "Insufficient credits. Please recharge to get more credits or try again next day."
}
```

```json
{
  "error": "MiniMax rejected the generation — the account is out of speech credits. Confirm with GET /features (audio.total_credit) and top up at https://www.minimax.io/audio/subscribe."
}
```

**429**
**429 Too Many Requests**

The account already has its maximum number of speech generations in flight. The running generations are unaffected — retry once one finishes. The ceiling depends on the MiniMax plan. A free account allows three.

```json
{
  "error": "This account already has the maximum number of speech generations running. Retry once one completes.",
  "code": 429
}
```

**504**
**504 Gateway Timeout**

MiniMax accepted the connection but sent nothing back within 30 seconds.

```json
{
  "error": "minimax did not respond within 30 seconds",
  "code": 504
}
```

**596**
**596 Account Error**
```json
{
  "error": "Your minimax account has pending error. Please address this issue at https://useapi.net/docs/api-minimax-v1/post-minimax-accounts-account before making any new API calls.",
  "code": 596
}
```

##### Model
```typescript
{ // TypeScript, all fields are optional
  audioId: string,       // Pass to GET speech/audioId
  replyRef: string,
  replyUrl: string,
  status: number,        // 0 while pending
  statusLabel: string,   // pending
  statusFinal: boolean   // false until the generation completes
}
```

##### Text markup

Three kinds of markup can be embedded directly in `text`, and they can be combined. Only emotion tags are excluded from billing — sound and pause markup counts toward the character total like any other text.

| Markup | Example | Values |
|---|---|---|
| Emotion | `{happy}Great news!{/happy}` | `happy`, `sad`, `angry`, `fearful`, `disgusted`, `surprised`, `neutral`, `fluent`. Max 15 spans per request |
| Sound | `That's wonderful (chuckle)` | `laughs`, `chuckle`, `coughs`, `clear-throat`, `groans`, `breath`, `pant`, `inhale`, `exhale`, `gasps`, `sniffs`, `sighs`, `snorts`, `burps`, `lip-smacking`, `humming`, `hissing`, `emm`, `sneezes` |
| Pause | `Wait for it <#0.5#> there!` | Seconds, from `0.01` to `99.99` |

```json
{
  "text": "{happy}The results are in{/happy} (chuckle) <#0.5#> and we did it."
}
```

##### Word timings

Word timings come back as a `subtitles` array with millisecond boundaries per phrase, which is what captions or a karaoke-style display need.

They reach you on two paths only: the SSE `done` event, and [POST speech/create-mp3](/docs/api-minimax-v1/post-minimax-speech-create-mp3). MiniMax does not store them, so neither [GET speech/`audioId`](/docs/api-minimax-v1/get-minimax-speech_audio_id) nor the `replyUrl` callback can return them — those report `has_srt` to tell you timings existed, but not the timings themselves. If you need captions for text over 3,000 characters, use `stream` and keep the `done` payload.

```json
"subtitles": [
  { "text": "The results are in", "time_begin": 0, "time_end": 1211.9, "text_begin": 0, "text_end": 18, "timestamped_words": [] }
]
```

Use `time_begin` and `time_end`. The `text_begin` and `text_end` fields are reported by MiniMax but do not reliably index into either the full text or the phrase, so they are passed through rather than interpreted.

##### Streaming

Set `stream` to `true` and the response is `200` with `Content-Type: text/event-stream`, instead of the `201` JSON documented in [Responses](#responses). The response carries an `X-Audio-Id` header with the `audioId`.

Streaming trades the callback for a shorter wait — the first audio arrives about four seconds in, rather than after the whole generation. The MP3 arrives in pieces that have to be joined, so buffer them as they come.

###### Events

| Event | Description | When Sent |
|---|---|---|
| `audio` | `{ "audioId": "...", "format": "mp3" \| "wav", "complete": false, "chunk": "<base64>" }` | As each piece is rendered |
| `done` | `{ "audioId": "...", "subtitles": [...], "usage_characters": 112 }` | When the generation finishes |
| `error` | `{ "error": "...", "code": 412 }` | MiniMax rejected the generation, the connection closed before any audio arrived (`502`), or the 5 minute cap fired (`504`) — `code` carries the HTTP status |
| `: keepalive` | An SSE comment, not an event | Every 10 seconds |

###### Handling the `audio` events

Two different things arrive on this event, and `format` tells them apart.

`format: "mp3"` events are **chunks**, and `complete` is `false`. Append them in arrival order and the result is a plain MP3. Short text sends a single chunk, but a 10,000-character generation sends around 40 of them over a minute or two, so treat it as a stream rather than assuming one.

`format: "wav"` with `complete: true` is the same speech again as a whole WAV file, delivered after the MP3 chunks. It is roughly four times the size and is not part of the MP3 — do not append it. It arrives reliably on short text, and on very long generations the stream may end after the MP3 chunks without it.

The simplest correct client keeps the MP3 chunks, ignores the WAV, and assembles once the stream ends — using `done` for the subtitles when it arrives, rather than as the trigger to assemble.

###### How the stream ends

Every stream terminates with exactly one of `done` or `error`, so you never have to treat a closed connection as ambiguous.

- `done` — the audio is finished. On a long generation MiniMax stops after the last MP3 chunk and drops the connection without sending its final frame, so `done` arrives with no `subtitles`. Read those from [GET speech/`audioId`](/docs/api-minimax-v1/get-minimax-speech_audio_id), which is also where to confirm the recording if you need certainty.
- `error` with `502` — the connection closed before any audio arrived.
- `error` with `504` — the generation ran past the 5 minute cap.

None of these lose the recording. A streamed generation is registered with the scheduler exactly like the default mode, so it still reconciles, `replyUrl` still fires, and the `audioId` from the `X-Audio-Id` header still resolves through [GET speech/`audioId`](/docs/api-minimax-v1/get-minimax-speech_audio_id). Hanging up mid-stream is safe for the same reason.

##### Examples

**Curl**
```bash
curl "https://api.useapi.net/v1/minimax/speech/create" \
  -H "Authorization: Bearer …" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Good morning. Here is the weather for the week ahead.",
    "voice_id": "380426458095854",
    "model": "speech-2.8-turbo",
    "replyUrl": "https://webhook.site/abc"
  }'
```

**JavaScript**
```javascript
const response = await fetch("https://api.useapi.net/v1/minimax/speech/create", {
  method: "POST",
  headers: {
    "Authorization": "Bearer …",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    text: "Good morning. Here is the weather for the week ahead.",
    voice_id: "380426458095854",
    model: "speech-2.8-turbo",
    replyUrl: "https://webhook.site/abc"
  })
});

const { audioId } = await response.json();

console.log(audioId);
```

**Python**
```python
import requests

response = requests.post(
    "https://api.useapi.net/v1/minimax/speech/create",
    headers={
        "Authorization": "Bearer …",
        "Content-Type": "application/json"
    },
    json={
        "text": "Good morning. Here is the weather for the week ahead.",
        "voice_id": "380426458095854",
        "model": "speech-2.8-turbo",
        "replyUrl": "https://webhook.site/abc"
    }
)

print(response.json()["audioId"])
```

###### Streaming example

Set `stream` and the response is an event stream rather than JSON. Two pieces: read the events, then play the chunks. Both are folded up — open what you need.

<details markdown="block">

<summary>Read the stream — collect the MP3 chunks and the subtitles</summary>

```javascript
const response = await fetch("https://api.useapi.net/v1/minimax/speech/create", {
  method: "POST",
  headers: {
    "Authorization": "Bearer …",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    text: "Good morning. Here is the weather for the week ahead.",
    voice_id: "380426458095854",
    stream: true
  })
});

const audioId = response.headers.get("X-Audio-Id");
const reader = response.body.getReader();
const decoder = new TextDecoder();

let buffer = "";
const chunks = [];
let subtitles = null;

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  buffer += decoder.decode(value, { stream: true });
  const parts = buffer.split("\n\n");
  buffer = parts.pop();

  for (const part of parts) {
    const event = part.match(/^event: (.+)$/m)?.[1];
    const data = part.match(/^data: (.+)$/m)?.[1];
    if (!event || !data) continue;

    const payload = JSON.parse(data);

    if (event === "audio" && payload.format === "mp3")
      chunks.push(Uint8Array.from(atob(payload.chunk), c => c.charCodeAt(0)));

    if (event === "done")
      subtitles = payload.subtitles;

    if (event === "error")
      console.error(payload.error);
  }
}

const mp3 = new Blob(chunks, { type: "audio/mpeg" });

console.log(audioId, mp3.size, subtitles);
```

</details>

That collects the whole recording and plays it at the end. To hear it while it is still rendering, feed each chunk to a `MediaSource` — it splices MP3 frames correctly, which decoding chunks individually does not:

<details markdown="block">

<summary>Progressive player — play the stream as it arrives</summary>

```javascript
const audio = document.querySelector("audio");
const mediaSource = new MediaSource();
audio.src = URL.createObjectURL(mediaSource);

const ready = new Promise(resolve =>
  mediaSource.addEventListener("sourceopen", resolve, { once: true }));

await ready;

const sourceBuffer = mediaSource.addSourceBuffer("audio/mpeg");
const pending = [];

const flush = () => {
  if (sourceBuffer.updating || !pending.length) return;
  sourceBuffer.appendBuffer(pending.shift());
};

sourceBuffer.addEventListener("updateend", flush);

/* inside the event loop above, instead of collecting into `chunks` */
if (event === "audio" && payload.format === "mp3") {
  pending.push(Uint8Array.from(atob(payload.chunk), c => c.charCodeAt(0)));
  flush();
  if (audio.paused) audio.play().catch(() => {});
}

/* once the stream ends, after the queue has drained */
if (event === "done") {
  const close = () => (pending.length || sourceBuffer.updating)
    ? setTimeout(close, 50)
    : mediaSource.endOfStream();
  close();
}
```

Two things worth knowing. **Append, do not decode.** Only the first chunk carries an MP3 header and the rest are bare frames, so decoding them individually and splicing the results produces gaps and overlaps — `MediaSource` handles the frame boundaries for you. And **`appendBuffer` is asynchronous**: appending again while `updating` is true throws, hence the queue and the `updateend` handler.

Check `MediaSource.isTypeSupported("audio/mpeg")` first and fall back to assembling a `Blob` at the end, as in the example above.

</details>

=== URL: https://useapi.net/docs/api-minimax-v1/post-minimax-speech-delete-voice ===
Document URL: https://useapi.net/docs/api-minimax-v1/post-minimax-speech-delete-voice
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> speech/delete-voice
description: "Delete a cloned voice via POST speech/delete-voice in the useapi.net MiniMax API v1, freeing one of the account's limited voice cloning slots."
parent: MiniMax API v1
nav_order: 1894
---
## Delete cloned voice
<small>December 27, 2024 (August 24, 2026)</small>

---

This endpoint deletes a voice cloned via [POST speech/clone-voice](/docs/api-minimax-v1/post-minimax-speech-clone-voice).  

This endpoint returns `200` for a cloned voice that does not exist or has already been deleted. An error from MiniMax is passed through, so check the status rather than assuming it always succeeds.
> **https://api.useapi.net/v1/minimax/speech/delete-voice**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "voice_id": "user:1234-minimax:1234567890123456789-voice:abcdef"
}
```

- `voice_id` is **required**, use value of field voice_id returned by [POST speech/clone-voice](/docs/api-minimax-v1/post-minimax-speech-clone-voice) or [GET speech/voices/?is_system=false](/docs/api-minimax-v1/get-minimax-speech-voices) 

This endpoint takes no `account` parameter. Cloned voice ids are returned in a wrapped form that already names the account, so it is read from `voice_id` — including when several accounts are configured. Sending `account` returns `400 Parameter account not supported`.

##### Responses 

**200**
**200 OK** 

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>",
  "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": 
    "Unauthorized",
    "Wrong username/password combination.",
    "This account has been suspended."
  "code": 401
}
```

**596**
**596 Account Error**
```json
{
  "error": "Your minimax account has pending error. Please address this issue at https://useapi.net/docs/api-minimax-v1/post-minimax-accounts-account before making any new API calls.",
  "code": 596
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST https://api.useapi.net/v1/minimax/speech/delete-voice \
     -d '{"voice_id": "…"}'
```

**JavaScript**
``` javascript
const voice_id = "voice id";      
const apiUrl = `https://api.useapi.net/v1/minimax/speech/delete-voice`; 
const api_token = "API token";
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${api_token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  voice_id
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
voice_id = "voice id"
apiUrl = f"https://api.useapi.net/v1/minimax/speech/delete-voice" 
api_token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {api_token}"
}
body = {
    "voice_id": f"{voice_id}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/post-minimax-speech-upload-sample ===
Document URL: https://useapi.net/docs/api-minimax-v1/post-minimax-speech-upload-sample
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> speech/upload-sample
description: "Upload an MP3 or WAV sample for voice cloning via POST speech/upload-sample in the useapi.net MiniMax API v1, returning the file id POST speech/clone-voice consumes."
parent: MiniMax API v1
nav_order: 1890
---
## Upload audio samples for voice cloning  
<small>December 27, 2024 (August 24, 2026)</small>

---

Upload `.mp3` and `.wav` audio samples that you want to use for your voice cloning via [POST speech/clone-voice](/docs/api-minimax-v1/post-minimax-speech-clone-voice). Each audio sample should be between 10 to 60 seconds long.  

[POST raw content using Make.com and similar nocode tools.](/docs/questions-and-answers#how-post-raw-content-to-runwaymlassets-and-minimaxfiles-using-makecom-and-similar-nocode-tools)
> **https://api.useapi.net/v1/minimax/speech/upload-sample/?…**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: select from the table below
```
- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   
- `Content-Type` is **required**, select from the table below:
  
| Content-Type | File Extension |
| ------------ | -------------- |
| audio/mpeg   | mp3            |
| audio/wav    | wav            |
| audio/wave   | wav            |

##### Query Parameters

- `account` is optional when only one [account](/docs/api-minimax-v1/get-minimax-accounts) configured. However, if you have multiple accounts configured, this parameter becomes **required**.  

##### Responses 

**200**
**200 OK**  

```json
{
    "ossPath": "<file url>",
    "fileID": "user:user_id-minimax:account-file:file_id"
}
```

**400**

**400 Bad Request**

```json
{
    "error": "<Error message>",
    "code": 400
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized",
  "code": 401
}
```

**596**
**596 Account Error**
```json
{
  "error": "Your minimax account has pending error. Please address this issue at https://useapi.net/docs/api-minimax-v1/post-minimax-accounts-account before making any new API calls.",
  "code": 596
}
```

##### Model 
  
```typescript
{ // TypeScript, all fields are optional
  ossPath: string
  fileID: string
  error: string
  code: number
}
```

##### Examples

**Curl**
``` bash
curl "https://api.useapi.net/v1/minimax/speech/upload-sample/?account=account" \
  -H "Authorization: Bearer …" \
  -H "Content-Type: audio/mpeg" \
  --data-binary /path/to/your/voice-sample.mp3
```

**JavaScript**
``` javascript
const token = "API token";
const account = "Previously configured account"; 
const apiUrl = `https://api.useapi.net/v1/minimax/speech/upload-sample/?account=${account}`; 
let blob;
/*
    // Example 1: Fetch audio from URL
    const audioUrl = "https://upload.wikimedia.org/wikipedia/commons/voice-sample.mp3";
    const responseAudio = await fetch(audioUrl);
    blob = await responseAudio.blob();
*/
/* 
    // Example 2: Load audio from local file (Blob)
    const fsp = require('fs').promises;
    const audioFileName = "./voice-sample.mp3";
    blob = new Blob([await fsp.readFile(audioFileName)]);
*/
/*
    // Example 3: Load from input file html element
    // <input id="audio-file" type="file"> 
    const audioFile = document.getElementById(`audio-file`);
    if (audioFile.files[0])
        blob = audioFile.files[0]);
*/
const response = await fetch(apiUrl, {
  method: "POST"
  headers: {
    "Authorization": `Bearer ${token}`,
  },
  body: blob
});
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
token = "API token"
account = "Previously configured account"
apiUrl = f"https://api.useapi.net/v1/minimax/speech/upload-sample/?account={account}"
headers = {
    'Authorization': f'Bearer {token}',
    'Content-Type': 'audio/mpeg'
}

# # Example 1: Fetch audio from URL
# audio_url = "https://upload.wikimedia.org/wikipedia/commons/voice-sample.mp3"
# response_audio = requests.get(audio_url)
# file_content = response_audio.content

# # Example 2: Load audio from local file
# audio_file_path = "./voice-sample.mp3"
# with open(audio_file_path, 'rb') as audio_file:
#     file_content = audio_file.read()

response = requests.post(api_url, headers=headers, data=file_content)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/post-minimax-videos-agent-create ===
Document URL: https://useapi.net/docs/api-minimax-v1/post-minimax-videos-agent-create
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/agent-create
description: "Create videos from predefined agent templates with real-time server-sent event (SSE) streaming via POST videos/agent-create in the useapi.net MiniMax API v1."
parent: MiniMax API v1
nav_order: 501
---
## Create a video using an agent template
## Table of contents
<small>June 30, 2025 (August 21, 2025)</small>
---

Create videos using MiniMax agent templates with predefined prompts and input requirements. On average, it takes 2 to 7 minutes for the agent to complete generation. The longer the duration of the result video, the longer it will take to generate. Videos longer than 15 seconds on average can take up to 15 minutes to generate.

**Note:** This endpoint returns a **real-time streaming response** (`Content-Type: multipart/form-data`) that provides live progress updates during video generation.

Use [hailuoai.video](https://hailuoai.video) account to generate videos, see [Setup MiniMax](/docs/start-here/setup-minimax) for details.

To browse available templates use [GET videos/agent-templates](/docs/api-minimax-v1/get-minimax-videos-agent-templates).
> **https://api.useapi.net/v1/minimax/videos/agent-create**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

##### Response Headers
``` yaml
Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "account": "Optional MiniMax API account",
    "templateId": "Required template ID",
    "prompt": "Optional text prompt",
    "fileID": "user:user_id-minimax:account-file:file_id",
    "ossPath": "Required OSS path when using fileID",
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here",
    "maxJobs": 1
}
```

- `account` is optional, if not specified API will randomly select account from available [accounts](/docs/api-minimax-v1/get-minimax-accounts).  

- `templateId` is **required**, the ID of the agent template to use. Get available templates from [GET videos/agent-templates](/docs/api-minimax-v1/get-minimax-videos-agent-templates).

- `prompt` is optional, text input for templates that require text prompts. Check template requirements using [GET videos/agent-templates/?templateId=`templateId`](/docs/api-minimax-v1/get-minimax-videos-agent-templates) with the specific `templateId`.

- `fileID` is optional, required for templates that need image inputs:
    * fileID of image uploaded via [POST /files](/docs/api-minimax-v1/post-minimax-files) 
    * fileID of previously uploaded image retrieved via [GET /files](/docs/api-minimax-v1/get-minimax-files) 
    * fileID of previously uploaded character retrieved via [GET videos/characters](/docs/api-minimax-v1/get-minimax-videos-characters)
    * fileID of image generated via [POST images/create](/docs/api-minimax-v1/post-minimax-images-create).

- `ossPath` is **required** when using `fileID`, the OSS path / url for the uploaded file. Cannot be provided without `fileID`.

- `replyUrl` is optional. Callback URL for job completion notifications.
  API will call the provided `replyUrl` once MiniMax video completed or failed.  
  Maximum length 1024 characters.
  Callback body has the same JSON shape as [GET /videos/`videoId`](/docs/api-minimax-v1/get-minimax-videos-videoId) response.

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

- `maxJobs` is optional, if not specified value from [accounts/account](/docs/api-minimax-v1/get-minimax-accounts-account) will be used.  
  Valid range: 1…10.  

##### Responses 

**200**
**200 OK** 

Returns a **streaming response** (`Content-Type: text/event-stream`) with real-time progress updates. The stream contains multiple data events showing the video generation process from start to finish.

See [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events) to learn more about events format.

```bash
data: {"status":"created","videoId":"user:1234-minimax:1234567-video:7654321","projectID":"…","chatID":"…","message":{"msgContent":"Futuristic sports car","msgType":1},"code":200,"timestamp":1755800001000}

data: {"status":"connected","videoId":"user:1234-minimax:1234567-video:7654321","projectID":"…","chatID":"…","code":200,"timestamp":1755800002000}

data: {"status":"heartbeat","timestamp":1755800012000}

data: {"status":"progress","type":1,"message":{"msgContent":"Generating image...","msgType":2},"timestamp":1755800015000}

data: {"status":"progress","type":2,"message":{"attachmentInfo":{"attachments":[{"file":{"fileName":"processing"},"status":2}]}},"timestamp":1755800017000}

data: {"status":"progress","type":2,"message":{"attachmentInfo":{"attachments":[{"file":{"fileName":"car.png","fileUrl":"https://cdn.hailuoai.video/moss/prod/.../car.png"},"status":3}]}},"timestamp":1755800025000}

data: {"status":"progress","type":1,"message":{"msgContent":"Generating video...","msgType":2},"timestamp":1755800026000}

data: {"status":"progress","type":2,"message":{"attachmentInfo":{"type":3,"attachments":[{"file":{"fileName":"processing"},"status":2}]}},"timestamp":1755800028000}

data: {"status":"progress","type":2,"message":{"attachmentInfo":{"type":3,"attachments":[{"file":{"fileName":"final_video.mp4","fileUrl":"https://cdn.hailuoai.video/moss/prod/.../final.mp4"},"status":3}]}},"timestamp":1755800055000}

data: {"status":"progress","type":3,"isFinished":true,"recTemplateList":[{"id":"template_vlog_1","name":"Vlog Interview"},{"id":"template_tf_2","name":"Transformers"}],"timestamp":1755800056000}

data: {"status":"finished","videoId":"user:1234-minimax:1234567-video:7654321","projectID":"…","chatID":"…","message":{"msgContent":"Futuristic sports car","msgType":1},"code":200,"timestamp":1755800057000}
```

Use the `videoId` from the stream event with `"status":"finished"` or `"status":"created"` to retrieve video status and results using [GET /videos/`videoId`](/docs/api-minimax-v1/get-minimax-videos-videoId).

**400**
**400 Bad Request**

```json
{
  "error": "<Error message>"
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized"
}
```

**404**
**404 Not Found**

```json
{
  "error": "The video or template you are trying to use does not exist or has been deleted."
}
```

##### Model `Content-Type: text/event-stream`

See [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events) to learn more about events format.

```bash
data:<JSON Data>

data:<JSON Data>

…
```

###### JSON Data Model
```typescript
{ // TypeScript, all fields are optional
  status?: 'created' | 'connected' | 'heartbeat' | 'progress' | 'finished' // Event status
  videoId?: string                     // Use GET /videos/<videoId> to retrieve results
  timestamp?: number                   // Event timestamp in milliseconds
  projectID?: string                   // Project identifier
  sectionID?: string                   // Section identifier within the project
  chatID?: string                      // Chat session identifier
  code?: number                        // Response code, e.g., 200
  type?: 1 | 2 | 3                     // Progress type. 1: Text/Tool, 2: Attachment, 3: Recommendations
  needUserInput?: boolean              // Flag indicating if user input is required
  isFinished?: boolean                 // Flag indicating if the entire process is complete
  errCode?: number                     // Error code, 0 for success
  errMsg?: string                      // Error message string
  /** The main message payload, can be null during certain events */
  message?: {
    msgId: string                      // Unique message ID
    parentMsgId?: string               // ID of the parent message
    msgType?: 1 | 2                    // Message type. 1: User, 2: System
    isQuota?: boolean                  // Quota usage flag
    timestamp?: number                 // Message creation timestamp
    msgContent?: string                // Text content of the message
    files?: {                          // User-uploaded files
      fileName: string
      fileUrl: string
      posterUrl: string
      type: string
      extra: Record<string, never>
    }[]
    toolCall?: {                       // System tool call details
      toolName: string
      toolCallStatus: 1 | 2            // Tool status. 1: Started, 2: Finished
      toolCallArgs: string             // Tool arguments as a JSON string
    }
    attachmentInfo?: {                 // Generated media attachments
      attachmentInfoID: string
      type?: 1 | 2 | 3                 // Attachment type. 1: Image, 2: Video, 3: Final Composite
      attachments: {
        attachmentID: string
        type?: number
        file: {
          fileName: string
          fileUrl: string
          posterUrl: string
          type: string
          extra?: {
            height?: string
            width?: string
            url?: string
            path?: string
            no_watermark_url?: string
            watermark_url?: string
            duration?: string
            fps?: string
            frames?: string            // A JSON string of frame URLs
            task_id?: string
            vendor?: string
          } | Record<string, never>
        }
        text?: string
        status?: 2 | 3                 // Generation status. 2: Processing, 3: Complete
        extra?: Record<string, never>
        subAttachments?: []
      }[]
      createTime?: number
      attachmentInfoUrl?: string
      extra?: Record<string, never>
      status?: number
    }
  } | null
}
```

##### Examples

**JavaScript**

<details markdown="block">

<summary>Expand <code class="language-plaintext highlighter-rouge"><b>JavaScript Streaming Example</b></code></summary>

``` javascript
const templateId = "1122334455667788";
const prompt = "text prompt";      
const token = "API token";

const response = await fetch('https://api.useapi.net/v1/minimax/videos/agent-create', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`
  },
  body: new FormData([['templateId', templateId], ['prompt', prompt]])
});

if (!response.ok) {
  const errorText = await response.text();
  throw new Error(`HTTP ${response.status}: ${errorText}`);
}

let videoId = null;
const reader = response.body.getReader();
const decoder = new TextDecoder("utf-8");
let buffer = "";

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  
  buffer += decoder.decode(value, { stream: true });
  const lines = buffer.split("\n");
  buffer = lines.pop();
  
  for (const line of lines) {
    if (line.startsWith("data:")) {
      try {
        const json = JSON.parse(line.slice(5).trim());
        console.log("Stream event:", json);
        
        if (json.videoId && !videoId) {
          videoId = json.videoId;
          console.log("Video ID:", videoId);
        }
        
        if (json.status === 'finished') {
          console.log("Generation completed!");
          break;
        }
        
      } catch (e) {
        console.error("Failed to parse JSON:", e);
      }
    }
  }
}

console.log("Final video ID:", videoId);
```

</details>

**Python**

<details markdown="block">

<summary>Expand <code class="language-plaintext highlighter-rouge"><b>Python Streaming Example</b></code></summary>

``` python
import requests
import json

template_id = "1122334455667788"
prompt = "text prompt"      
token = "API token"

data = {
    'templateId': template_id,
    'prompt': prompt
}

response = requests.post(
    'https://api.useapi.net/v1/minimax/videos/agent-create',
    headers={'Authorization': f'Bearer {token}'},
    data=data,
    stream=True
)

if not response.ok:
    print(f"HTTP Error {response.status_code}: {response.text}")
    exit(1)

video_id = None

for line in response.iter_lines(decode_unicode=True):
    if line and line.startswith("data:"):
        try:
            json_data = json.loads(line[5:].strip())
            print("Stream event:", json_data)
            
            if json_data.get("videoId") and not video_id:
                video_id = json_data["videoId"]
                print(f"Video ID: {video_id}")
            
            if json_data.get("status") == "finished":
                print("Generation completed!")
                break
                
        except json.JSONDecodeError as e:
            print(f"Failed to parse JSON: {e}")

print(f"Final video ID: {video_id}")
```

</details>

**Curl**
``` bash
curl -H "Accept: text/event-stream" \
     -H "Authorization: Bearer …" \
     -X POST "https://api.useapi.net/v1/minimax/videos/agent-create" \
     -d "templateId=1122334455667788" \
     -d "prompt=text prompt" \
     --no-buffer
```

=== URL: https://useapi.net/docs/api-minimax-v1/post-minimax-videos-cancel ===
Document URL: https://useapi.net/docs/api-minimax-v1/post-minimax-videos-cancel
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/cancel
description: "Cancel an in-progress video generation by videoId via POST videos/cancel in the useapi.net MiniMax API v1."
parent: MiniMax API v1
nav_order: 900
---
## Cancel the currently generated video
## Table of contents
<small>January 9, 2025</small>
---

Attempt to cancel a currently generated video created via [POST videos/create](/docs/api-minimax-v1/post-minimax-videos-create).
> **https://api.useapi.net/v1/minimax/videos/cancel**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body
```json
{
    "videoId": "user:user_id-minimax:account-file:video_id",
}
```

- `videoId` is **required**. Specify the videoId you want to cancel.   

##### Responses 

**200**
**200 OK** 

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>"
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized"
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST "https://api.useapi.net/v1/minimax/videos/cancel" \
     -d '{"videoId": "…"}'
```

**JavaScript**
``` javascript
const videoId = "videoId you want to cancel";      
const apiUrl = `https://api.useapi.net/v1/minimax/videos/cancel`; 
const token = "API token";
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  videoId
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
videoId = "videoId you want to cancel"   
apiUrl = f"https://api.useapi.net/v1/minimax/videos/cancel" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
body = {
    "videoId": f"{videoId}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== URL: https://useapi.net/docs/api-minimax-v1/post-minimax-videos-create ===
Document URL: https://useapi.net/docs/api-minimax-v1/post-minimax-videos-create
---
layout: default
title: <code class="language-plaintext highlighter-rouge background-method-post">POST</code> videos/create
description: "Generate AI video from text or image via POST videos/create in the useapi.net MiniMax API v1 — 19 models including Hailuo 3.0 at 768p/2K with native audio, Hailuo 02/2.3, Veo 3.1, Sora 2, and Seedance 2.0."
parent: MiniMax API v1
nav_order: 500
---
## Create a video using a text and image prompt
## Table of contents
<small>September 25, 2024 (August 6, 2026)</small>
---

Use [hailuoai.video](https://hailuoai.video) account to generate videos, see [Setup MiniMax](/docs/start-here/setup-minimax) for details.

To upload prompt image use [POST /files](/docs/api-minimax-v1/post-minimax-files).

##### Model Comparison Matrix

###### Hailuo 01 — Legacy models, 720p 6sec, no `options`

| Model | Type | Notes |
|:------|:-----|:------|
| T2V-01 | Text-to-Video | Default for text prompts |
| I2V-01 | Image-to-Video | Default for image prompts |
| I2V-01-live | Image-to-Video | Live photo effect |
| I2V-01-Director | Image-to-Video | Camera movement control |
| T2V-01-Director | Text-to-Video | Camera movement control |
| S2V-01 | Subject Reference | Character/subject consistency |

###### Hailuo 02/2.3 — Resolution and duration `options`

| Model | Type | Options | End Frame |
|:------|:-----|:--------|:----------|
| 02 | Text/Image-to-Video | 512p-6/10sec, 768p-6/10sec, 1080p-6sec | Yes (768p/1080p) |
| T2V-2.3 | Text-to-Video | 768p-6/10sec, 1080p-6sec | No |
| I2V-2.3 | Image-to-Video | 768p-6/10sec, 1080p-6sec | No |
| I2V-2.3-Fast | Image-to-Video | 768p-6/10sec, 1080p-6sec | No |

###### Sora & Veo — `aspectRatio` (16:9, 9:16), higher resolution `options`

| Model | Type | Options | End Frame | Notes |
|:------|:-----|:--------|:----------|:------|
| Sora-2 | Text/Image-to-Video | 720p-4/8/12sec | No | OpenAI, exact 1280x720 or 720x1280 images |
| Veo-3.1 | Text/Image-to-Video | veo-720p/1080p/4k-8sec | Yes | Google DeepMind, native audio |
| Veo-3.1-Fast | Text/Image-to-Video | veo-720p/1080p/4k-8sec | Yes | Faster generation |
| Veo-3.1-S2V | Subject Reference | veo-720p/1080p/4k-8sec | No | Up to 14 ref images |
| Veo-3.1-S2V-Fast | Subject Reference | veo-720p/1080p/4k-8sec | No | Up to 14 ref images, faster |

###### Seedance 2.0 — Independent `resolution` + `duration`, `aspectRatio` (7 ratios incl. Auto), omni multi-modal references

| Model | Type | Resolutions | Duration | Aspect Ratios | Notes |
|:------|:-----|:-----------:|:--------:|:--------------|:------|
| Seedance-2.0 | Text/Image-to-Video | 480, 720, 1080, 4K | 4–15 sec | Auto, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 | ByteDance, omni reference + start/end frames, only tier with 4K |
| Seedance-2.0-Fast | Text/Image-to-Video | 480, 720 | 4–15 sec | Same as above | Faster, lower cost |
| Seedance-2.0-Mini | Text/Image-to-Video | 480, 720 | 4–15 sec | Same as above | Cheapest tier |

Seedance models do not use `options`. Set `resolution` and `duration` directly. `end_frame_fileID` is mutually exclusive with omni references (`fileID2`…`fileID9`, `videoFileID*`, `audioFileID*`).

###### Hailuo 3.0 — 768p and 2K output, native stereo audio on every generation, omni multi-modal references

| Model | Type | Resolution | Duration | Aspect Ratios | Notes |
|:------|:-----|:----------:|:--------:|:--------------|:------|
| Hailuo-3.0 | Text/Image-to-Video | 768, 1440 (2K) | 4–15 sec | Auto, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16 | MiniMax H3, omni reference + start/end frames, native audio |

Hailuo 3.0 takes the same shape as Seedance 2.0 — set `resolution` and `duration` directly, no `options`. Output is 24 fps and every generation includes native stereo audio. Pixel dimensions follow the chosen `aspectRatio`, so a 2K clip is larger at 16:9 than at 21:9.

A few rules are specific to this model:

- `resolution` accepts `1440` (2K, the default) and `768`. 768p costs 7 credits per second against 12 for 2K.
- `prompt` is required on every request, including image-to-video.
- Omni references are capped at 12 files in total — up to 9 images, 3 videos, and 3 audio clips, so the three buckets cannot all be filled at once.
- An audio reference must be accompanied by at least one image or video reference.
- Each reference file is capped at 30 MB for images, 50 MB for video, and 15 MB for audio.
- `end_frame_fileID` works without `fileID`, so you can supply an end frame alone.
- With no `aspectRatio`, text-to-video defaults to 16:9 and any request carrying references defaults to `Auto` (match the input).

<details markdown="block">
<summary><small><b>💲 Credits estimator</b></small></summary>

Credits are charged per video. Actual costs may change, see [hailuoai.video](https://hailuoai.video) for current pricing.

| Model | Option | Credits |
|:------|:-------|:-------:|
| T2V-01, I2V-01, I2V-01-live, S2V-01, T2V-01-Director, I2V-01-Director | - | 25 |
| 02, T2V-2.3, I2V-2.3 | 768p-6sec | 25 |
| 02, T2V-2.3, I2V-2.3 | 768p-10sec | 50 |
| 02, T2V-2.3, I2V-2.3 | 1080p-6sec | 80 |
| 02 | 512p-6sec | 12 |
| 02 | 512p-10sec | 25 |
| I2V-2.3-Fast | 768p-6sec | 15 |
| I2V-2.3-Fast | 768p-10sec | 30 |
| I2V-2.3-Fast | 1080p-6sec | 50 |
| Sora-2 | 720p-4sec | 40 |
| Sora-2 | 720p-8sec | 80 |
| Sora-2 | 720p-12sec | 120 |
| Veo-3.1, Veo-3.1-S2V | veo-720p-8sec | 120 |
| Veo-3.1, Veo-3.1-S2V | veo-1080p-8sec | 120 |
| Veo-3.1, Veo-3.1-S2V | veo-4k-8sec | 180 |
| Veo-3.1-Fast, Veo-3.1-S2V-Fast | veo-720p-8sec | 60 |
| Veo-3.1-Fast, Veo-3.1-S2V-Fast | veo-1080p-8sec | 60 |
| Veo-3.1-Fast, Veo-3.1-S2V-Fast | veo-4k-8sec | 90 |

Seedance 2.0 and Hailuo 3.0 are billed per second rather than per clip. Multiply the output rate by your chosen `duration` (4–15) for the base cost.

| Model | Resolution | Credits/sec | 4-sec clip | Credits/sec of video reference |
|:------|:----------:|:-----------:|:----------:|:------------------------------:|
| Seedance-2.0 | 480p | 10 | 40 | 6 |
| Seedance-2.0 | 720p | 21 | 84 | 14 |
| Seedance-2.0 | 1080p | 50 | 200 | 30 |
| Seedance-2.0 | 4K | 100 | 400 | 60 |
| Seedance-2.0-Fast | 480p | 8 | 32 | 4 |
| Seedance-2.0-Fast | 720p | 17 | 68 | 11 |
| Seedance-2.0-Mini | 480p | 5 | 20 | 3 |
| Seedance-2.0-Mini | 720p | 11 | 44 | 7 |
| Hailuo-3.0 | 768p | 7 | 28 | 7 |
| Hailuo-3.0 | 2K (1440) | 12 | 48 | 12 |

A video reference is billed on its own length, on top of the generated clip. A 4-second Hailuo-3.0 clip costs 48 credits on its own, and about 168 credits when it carries a 10-second video reference (4 × 12 for the output plus 10 × 12 for the reference). Image and audio references do not add a per-second charge.

</details>
> **https://api.useapi.net/v1/minimax/videos/create**

##### Request Headers
``` yaml
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
```

- `API token` is **required**, see [Setup useapi.net](/docs/start-here/setup-useapi) for details.   

##### Request Body

```json
{
    "account": "1234567890",
    "model": "Seedance-2.0-Fast",
    "fileID": "user:1234-minimax:1234567890-file:1234567890",
    "prompt": "Cinematic shot of @Image1 walking through a neon-lit alley at night, rain reflections on wet pavement, slow tracking",
    "resolution": "720",
    "duration": 5,
    "aspectRatio": "16:9",
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "shot-042"
}
```

- `account` is optional, if not specified API will randomly select account from available [accounts](/docs/api-minimax-v1/get-minimax-accounts).  

- `prompt` is optional, describe your shot. Maximum length 2,000 characters (7,500 for Seedance models, 7,000 for `Hailuo-3.0`). `Hailuo-3.0` requires a prompt on every request, including image-to-video. How to prompt [tutorial](https://ageofllms.com/ai-howto-prompts/ai-fun/hailuo-minimax-tutorial).

  **Omni `@`-mentions** (Seedance 2.0 and `Hailuo-3.0`)**.** When omni references are uploaded, you can refer to them in the prompt using `@Image1`…`@Image9`, `@Video1`…`@Video3`, `@Audio1`…`@Audio3` (case-insensitive — `@image1`, `@IMAGE1`, `@Image01` all resolve to the same slot). Unresolved tokens (e.g. `@Image5` when only 2 images are provided) return a 400 error. If no omni references are uploaded, `@`-tokens pass through as literal text.

  **Seedance omni audio.** To make a referenced voice audible in the output, spell out the spoken line and state it is heard, for example *She speaks out loud, clearly saying "your line" in the voice from @Audio1, audible throughout*. A bare `@Audio1` mention (no explicit "says … audible" wording) often returns a silent track, even though the request is accepted.

- `promptOptimization` is optional.
  Supported values: `true`, `false`. Default: `false` (no optimization).

- `fileID` — image/character reference. Upload via [POST /files](/docs/api-minimax-v1/post-minimax-files), retrieve via [GET /files](/docs/api-minimax-v1/get-minimax-files), [GET videos/characters](/docs/api-minimax-v1/get-minimax-videos-characters), or use fileID from [POST images/create](/docs/api-minimax-v1/post-minimax-images-create).

  | `model` | `fileID` | `end_frame_fileID` | `fileID2`…`fileID14` | `aspectRatio` |
  |:------|:---------|:-------------------|:---------------------|:--------------|
  | `T2V-01`, `T2V-01-Director`, `T2V-2.3` | Not supported | - | - | - |
  | `I2V-01`, `I2V-01-live`, `I2V-01-Director` | Required | - | - | - |
  | `S2V-01` | Required | - | - | - |
  | `02` | Optional | Yes (768p/1080p only) | - | - |
  | `I2V-2.3`, `I2V-2.3-Fast` | Required | - | - | - |
  | `Sora-2` | Optional (exact 1280x720 or 720x1280) | - | - | `16:9`, `9:16` |
  | `Veo-3.1`, `Veo-3.1-Fast` | Optional | Yes | - | `16:9`, `9:16` |
  | `Veo-3.1-S2V`, `Veo-3.1-S2V-Fast` | Required | - | Up to 14 total | `16:9`, `9:16` |
  | `Seedance-2.0`, `Seedance-2.0-Fast`, `Seedance-2.0-Mini`, `Hailuo-3.0` | Optional | Yes (mutually exclusive with `fileID2`…`fileID9` and omni `videoFileID*`/`audioFileID*`) | Up to 9 (`fileID`…`fileID9`, resolved as `@Image1`…`@Image9`) | 7 ratios (see below) |

- `end_frame_fileID` is optional. The `end_frame_fileID` and `fileID` cannot be the same, reupload the end frame via [POST /files](/docs/api-minimax-v1/post-minimax-files) if needed.

- `fileID2` … `fileID14` are optional. **For S2V models** (`Veo-3.1-S2V`, `Veo-3.1-S2V-Fast`) — additional subject/character reference images, up to 14 total. **For Seedance models and `Hailuo-3.0`** — additional omni image references `@Image2`…`@Image9` (up to 9 total, `fileID10`…`fileID14` rejected). `Hailuo-3.0` additionally caps all references combined at 12 files. Requires `fileID` first. Slots must be filled consecutively (no gaps). All files must belong to the same account.

- `videoFileID1` … `videoFileID3` are optional, **for Seedance models and `Hailuo-3.0`**. Omni video references resolved as `@Video1`…`@Video3` in the prompt. Upload mp4 via [POST /files](/docs/api-minimax-v1/post-minimax-files). Each video reference must be 2–15 seconds, and all video references together cannot exceed 15 seconds. Slots must be filled consecutively (no gaps). Mutually exclusive with `end_frame_fileID`.

  A video reference that shows a recognizable real human face is rejected by Seedance's content filter — the job ends with status `moderated` ("Face Detected"). Blur the face, or use footage without a clear face. A real face in an **image** reference (`fileID`) is allowed — the restriction applies to video material only.

- `audioFileID1` … `audioFileID3` are optional, **for Seedance models and `Hailuo-3.0`**. Omni audio references resolved as `@Audio1`…`@Audio3` in the prompt. Upload mp3 or wav via [POST /files](/docs/api-minimax-v1/post-minimax-files). Each audio reference must be 2–15 seconds, and all audio references together cannot exceed 15 seconds — video and audio are totalled separately, 15 seconds each. Slots must be filled consecutively (no gaps). Mutually exclusive with `end_frame_fileID`. On `Hailuo-3.0` an audio reference must be accompanied by at least one image or video reference. To hear the voice in the output, prompt it explicitly (see `prompt` above).

- `resolution` is optional, **for Seedance models and `Hailuo-3.0`**. Supported values: `480`, `720`, `1080` (Seedance-2.0 only), `4K` (Seedance-2.0 only), `768` and `1440` (`Hailuo-3.0` only). `Seedance-2.0-Fast` and `Seedance-2.0-Mini` support `480` and `720` only. Default: `720` for Seedance, `1440` for `Hailuo-3.0`.

- `duration` is optional, **for Seedance models and `Hailuo-3.0`**. Integer seconds in range 4–15. Default: `5`.

- `aspectRatio` is optional. Supported by:
  - `Sora-2`, `Veo-3.1`, `Veo-3.1-Fast`, `Veo-3.1-S2V`, `Veo-3.1-S2V-Fast` — values: `16:9` (default), `9:16`.
  - `Seedance-2.0`, `Seedance-2.0-Fast`, `Seedance-2.0-Mini` — values: `Auto` (default), `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`.

- `model` is optional. Supported values:

  **Hailuo 01** — 720p, 6 sec
  * `T2V-01` (default) text-to-video
  * `I2V-01` (default) image-to-video
  * `I2V-01-live` image-to-video, live photo effect
  * `S2V-01` subject reference, character/subject consistency
  * `T2V-01-Director` text-to-video, camera movement control via `[<movement>]` in prompt (instructions)
  * `I2V-01-Director` image-to-video, camera movement control via `[<movement>]` in prompt (instructions)

  **Hailuo 02/2.3** — resolution and duration `options`
  * `02` text/image-to-video, native 1080p
  * `T2V-2.3` text-to-video
  * `I2V-2.3` image-to-video
  * `I2V-2.3-Fast` image-to-video, faster generation

  **Sora & Veo** — `aspectRatio` support, higher resolution `options`
  * `Sora-2` OpenAI Sora 2, text/image-to-video, 720p only. Image: exact 1280x720 (16:9) or 720x1280 (9:16)
  * `Veo-3.1` Google DeepMind Veo 3.1, text/image-to-video with native audio, 720p/1080p/4K
  * `Veo-3.1-Fast` Veo 3.1 Fast, text/image-to-video, 720p/1080p/4K
  * `Veo-3.1-S2V` Veo 3.1 Subject Reference, up to 14 reference images via `fileID`…`fileID14`, 720p/1080p/4K
  * `Veo-3.1-S2V-Fast` Veo 3.1 Subject Reference Fast, up to 14 reference images, 720p/1080p/4K

  **Seedance 2.0** — independent `resolution` + `duration`, omni multi-modal references, 7 aspect ratios
  * `Seedance-2.0` ByteDance Seedance 2.0, text/image-to-video, 480p/720p/1080p/4K, 4–15 sec
  * `Seedance-2.0-Fast` Seedance 2.0 Fast, text/image-to-video, 480p/720p, 4–15 sec, lower cost
  * `Seedance-2.0-Mini` Seedance 2.0 Mini, text/image-to-video, 480p/720p, 4–15 sec, cheapest tier

- `options` is optional. Sets resolution and duration. Hailuo 01 and Seedance models do not support `options` (Seedance uses `resolution` and `duration` directly).

  | `model` | `options` | `end_frame` |
  |:------|:-------------------|:-----------|
  | `02` | `512p-6sec`, `512p-10sec` (I2V only), `768p-6sec`, `768p-10sec`, `1080p-6sec` | Yes (768p/1080p only) |
  | `T2V-2.3` | `768p-6sec`, `768p-10sec`, `1080p-6sec` | No |
  | `I2V-2.3` | `768p-6sec`, `768p-10sec`, `1080p-6sec` | No |
  | `I2V-2.3-Fast` | `768p-6sec`, `768p-10sec`, `1080p-6sec` | No |
  | `Sora-2` | `720p-4sec`, `720p-8sec`, `720p-12sec` | No |
  | `Veo-3.1` | `veo-720p-8sec`, `veo-1080p-8sec`, `veo-4k-8sec` | Yes |
  | `Veo-3.1-Fast` | `veo-720p-8sec`, `veo-1080p-8sec`, `veo-4k-8sec` | Yes |
  | `Veo-3.1-S2V` | `veo-720p-8sec`, `veo-1080p-8sec`, `veo-4k-8sec` | No |
  | `Veo-3.1-S2V-Fast` | `veo-720p-8sec`, `veo-1080p-8sec`, `veo-4k-8sec` | No |

- `replyUrl` is optional. Callback URL for job completion notifications.
  API will call the provided `replyUrl` once MiniMax video completed or failed.  
  Maximum length 1024 characters.  
  We recommend using sites like [webhook.site](https://webhook.site) to test callback URL functionality.
  Callback body has the same JSON shape as [GET /videos/`videoId`](/docs/api-minimax-v1/get-minimax-videos-videoId) response.

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

- `maxJobs` is optional, if not specified value from [accounts/account](/docs/api-minimax-v1/get-minimax-accounts-account) will be used.  
  Valid range: 1…10.  
  Please set this number according to your [subscription](https://hailuoai.video/subscribe) plan. We recommend setting it to **2** (3 maximum) for Free, and **3** (4 maximum) for Standard and Unlimited plans. Although you can set it to higher values (3 for Free and 5 for Standard and Unlimited respectively), it won't make any difference since only one video can be processed at a time for Free accounts, and no more than two for Standard and Unlimited accounts. It's helpful to have a spare empty slot for cases where the MiniMax website is too busy and responds with `502` or `504` while still accepting jobs into the internal queue.  

##### Responses 

**200**
**200 OK** 

Use returned `videoId` to retrieve video status and results using [GET /videos/`videoId`](/docs/api-minimax-v1/get-minimax-videos-videoId). Check `videoURL` and/or `downloadURL` (paid account, no watermarks) for generated video with the `status` **2** (Completed).

If you specify the optional parameter [`replyUrl`](/docs/api-minimax-v1/post-minimax-videos-create#request-body) the API will call the provided `replyUrl` with video progress updates until the video is complete or fails.

```json
{
    "id": "1122334455667798899",
    "task": {
        "batchID": "998877665544332211",
        "videoIDs": [
            "1122334455667798899"
        ]
    },
    "videoId": "user:1234-minimax:987654321-video:998877665544332211",
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>"
}
```

**400**
**400 Bad Request**
```json
{
  "error": "<Error message>"
}
```

**401**
**401 Unauthorized**
```json
{
  "error": "Unauthorized"
}
```

**412**
**412 Insufficient credits**

Insufficient credits. Please recharge to get more credits or try again next day.

```json
{
  "error": "Insufficient credits. Please recharge to get more credits or try again next day."
}
```

**422**
**422 Unprocessable Content**

Moderated message.

```json
{
  "error": "Your prompt is too short, please provide more details"
}
```

**429**
**429 Too Many Requests**  

Wait in a loop for **at least** 10..30 seconds and retry again.

There are two possible cases for API response 429:

1. API query is full and can not accept new videos/create requests. Size of query defined by [`maxJobs` optional parameter](#request-body).
```json
{
    "error": "Account <MiniMax account> is busy executing <Account maxJobs> videos",
    "runningVideos": {
        "<MiniMax account>": [
            {
                "account": "<MiniMax account>",
                "id": "id1",
                "scheduledVideo": "<scheduled video id1>",
                "videoId": "user:user_id-minimax:account-video:id1",
                "started": "2024-09-25T01:55:16.128Z",
                "replyUrl": "<optional callback URL>",
                "replyRef": "<optional reference>"
            },
            {
                "account": "<MiniMax account>",
                "id": "idN",
                "scheduledVideo": "<scheduled video idN>",
                "videoId": "user:user_id-minimax:account-video:idN",
                "started": "2024-09-25T01:55:16.128Z",
                "replyUrl": "<optional callback URL>",
                "replyRef": "<optional reference>"
            }
        ]
    }
}
```
2. The API received an HTTP response status 429 from MiniMax. Please refer to your [subscription](https://hailuoai.video/subscribe) plan for the maximum allowed tasks in the queue.
```json
{
  "error": "YOU CAN QUEUE 3 JOBS AT ONCE"
}
```

**596**
**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](https://discord.com/channels/1280370508373950534/1297778596236103762) 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.

```json
{
  "error": "Unusual account activities detected. Please contact customer support at contact@hailuoai.com"
}
```

##### Model 
```typescript
{ // TypeScript, all fields are optional
    videoId: string
    id: string
    task: {
        batchID: string
        videoIDs: string[]
    }
    runningVideos: {
      [account: string]: {
        account: string
        id: string
        scheduledVideo: string
        videoId: string
        started: string 
        replyUrl: string 
        replyRef: string 
      }[]
    }
    replyUrl: string
    replyRef: string
    error: string
}
```

##### Examples

**Curl**
``` bash
curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST "https://api.useapi.net/v1/minimax/videos/create" \
     -d '{"prompt": "…"}'
```

**JavaScript**
``` javascript
const prompt = "text prompt";      
const apiUrl = `https://api.useapi.net/v1/minimax/videos/create`; 
const token = "API token";
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  prompt
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});
```

**Python**
``` python
import requests
prompt = "text prompt"      
apiUrl = f"https://api.useapi.net/v1/minimax/videos/create" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
body = {
    "prompt": f"{prompt}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())
```

=== Cross-reference: General Q&A ===
For cross-cutting tips (rate limiting, prompt moderation, common patterns)
see https://useapi.net/assets/aibot/qa.txt

WARNING: Q&A items are general-purpose and may reference deprecated APIs,
sunsetted services, or scenarios not applicable to the API documented above.
Cross-check against this service's endpoint documentation before applying
any Q&A guidance.