get_balance
Read-onlyGet the remaining credit balance of the account.
Arguments
No arguments.
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "get_balance",
"arguments": {}
}
}One endpoint, 10 tools. Send JSON-RPC 2.0 requests with your API key to check credits, browse models and generate images, videos and music. It is the same server AI apps connect to over MCP.
Endpoint
https://minimaxh3image.com/api/mcpSend your API key as a Bearer token. Keys start with sk_ and spend credits from your account, so keep them secret. Deleting a key revokes it at once.
Authorization: Bearer sk_...
Apps such as Claude and ChatGPT can sign in with OAuth instead. They find it from the 401 response and the metadata at https://minimaxh3image.com/.well-known/oauth-protected-resource/api/mcp
Each POST carries one JSON-RPC message. No session or initialize call is needed. Call tools/list to read the tool list, and tools/call to run a tool.
curl -X POST https://minimaxh3image.com/api/mcp \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_balance","arguments":{}}}'The reply is a one-shot event stream. Read the data: line. The tool result is in result.structuredContent, and also as text in result.content.
event: message
data: {"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"{\"credits\":1200}"}],"structuredContent":{"credits":1200}}}Generating returns an id right away. Poll it until the result is ready.
1estimate_cost
Optional. See how many credits a job will cost before running it.
2generate_*
Start the job. You get a generation id and the credits it cost.
3wait_for_generation
Waits up to 50 seconds per call. Call again while status is not success, failed or canceled.
4url
When status is success, the result has a url to the image, video or song.
401Missing or invalid API key. The WWW-Authenticate header points OAuth clients to sign-in.429Over 120 requests per minute per IP or account. Wait for the Retry-After seconds. Request bodies are capped at 200 KB.isErrorThe tool ran but failed, for example not enough credits or an unknown model. HTTP 200 with result.isError true and the reason in result.content.errorThe request itself is invalid, such as an unknown tool or bad arguments. The reply has a JSON-RPC error object instead of result.Read live from the server, so this list always matches what the API accepts. Tools marked "Spends credits" charge your account.
Get the remaining credit balance of the account.
Arguments
No arguments.
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "get_balance",
"arguments": {}
}
}List the available generation models (slug, name, vendor, starting price). Use the slug with get_model, estimate_cost and generate_*.
Arguments
| Name | Type | Description |
|---|---|---|
type | "image" | "video" | "audio" |
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "list_models",
"arguments": {
"type": "image"
}
}
}Get every parameter a model accepts (names, types, allowed values, defaults) so generate_* options can be filled in correctly.
Arguments
| Name | Type | Description |
|---|---|---|
modelrequired | string | Model slug from list_models |
mediaTyperequired | "image" | "video" | "music" |
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "get_model",
"arguments": {
"model": "minimax-h3-image",
"mediaType": "image"
}
}
}Estimate how many credits a generation will cost without running it.
Arguments
| Name | Type | Description |
|---|---|---|
mediaTyperequired | "image" | "video" | "music" | |
modelrequired | string | Model slug from list_models |
prompt | string | ≤ 10000 chars |
imageUrls | string[] | ≤ 10 items |
videoUrls | string[] | ≤ 10 items |
audioUrls | string[] | ≤ 10 items |
options | object | Model parameters such as aspect_ratio, resolution, duration. Call get_model to see what a model accepts. |
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "estimate_cost",
"arguments": {
"mediaType": "video",
"model": "minimax-h3",
"prompt": "A red sports car drifting through a neon city at night"
}
}
}Generate an image from a prompt, or edit / combine reference images (imageUrls). Spends credits.
Arguments
| Name | Type | Description |
|---|---|---|
modelrequired | string | Model slug from list_models |
promptrequired | string | ≤ 10000 chars |
imageUrls | string[] | Optional reference images≤ 10 items |
options | object | Model parameters such as aspect_ratio, resolution, duration. Call get_model to see what a model accepts. |
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "generate_image",
"arguments": {
"model": "minimax-h3-image",
"prompt": "A banana-shaped yellow sofa in a sunny living room"
}
}
}Generate a video from a prompt, a start image (imageUrls) or a reference video. Spends credits; call estimate_cost first.
Arguments
| Name | Type | Description |
|---|---|---|
modelrequired | string | Model slug from list_models |
prompt | string | ≤ 10000 chars |
imageUrls | string[] | ≤ 10 items |
videoUrls | string[] | ≤ 10 items |
audioUrls | string[] | ≤ 10 items |
options | object | Model parameters such as aspect_ratio, resolution, duration. Call get_model to see what a model accepts. |
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "generate_video",
"arguments": {
"model": "minimax-h3",
"prompt": "A red sports car drifting through a neon city at night"
}
}
}Generate a song or instrumental from a prompt (style, mood, lyrics). Spends credits.
Arguments
| Name | Type | Description |
|---|---|---|
modelrequired | string | Model slug from list_models |
promptrequired | string | ≤ 10000 chars |
options | object | Model parameters such as aspect_ratio, resolution, duration. Call get_model to see what a model accepts. |
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "generate_music",
"arguments": {
"model": "suno-v6",
"prompt": "Upbeat synth-pop about a summer road trip"
}
}
}Get the status of one generation and its result url once it succeeded.
Arguments
| Name | Type | Description |
|---|---|---|
idrequired | string | ≤ 128 chars |
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "get_generation",
"arguments": {
"id": "GENERATION_ID"
}
}
}Wait (up to timeoutSeconds) until a generation finishes, then return its status and url. Call again if it is still running.
Arguments
| Name | Type | Description |
|---|---|---|
idrequired | string | ≤ 128 chars |
timeoutSeconds | integer | default 45 · 5–50 |
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "wait_for_generation",
"arguments": {
"id": "GENERATION_ID",
"timeoutSeconds": 45
}
}
}List the most recent generations of the account.
Arguments
| Name | Type | Description |
|---|---|---|
mediaType | "image" | "video" | "music" | |
limit | integer | default 10 · 1–50 |
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "list_generations",
"arguments": {
"mediaType": "video",
"limit": 5
}
}
}