API Reference

MuAPI follows a simple submit-then-poll pattern. All endpoints are under https://api.muapi.ai/api/v1.

Authentication

Include your API key in every request:

x-api-key: YOUR_API_KEY

Get your API key from Dashboard → API Keys.

Request Pattern

1. Submit a Job

POST https://api.muapi.ai/api/v1/{endpoint}
x-api-key: YOUR_API_KEY
Content-Type: application/json

{ ...model-specific parameters... }

Response:

{
  "request_id": "abc123xyz",
  "status": "processing",
  "cost": {
    "amount_usd": 0.0042,
    "amount_credits": 1,
    "bonus_credits_used": 0,
    "refunded": false
  }
}

2. Poll for Result

GET https://api.muapi.ai/api/v1/predictions/{request_id}/result
x-api-key: YOUR_API_KEY

Response (completed):

{
  "id": "abc123xyz",
  "status": "completed",
  "outputs": ["https://cdn.muapi.ai/...output.png"],
  "cost": {
    "amount_usd": 0.0042,
    "amount_credits": 1,
    "bonus_credits_used": 0,
    "refunded": false
  }
}

Per-Request Cost

Every submit and result response includes a cost object with the actual wallet charge for that request — no need to look up pricing tables out-of-band:

Field	Type	Meaning
`amount_usd`	float	Charged amount in USD (post-bonus, post-discount).
`amount_credits`	int	Same charge expressed in muapi credits.
`bonus_credits_used`	int	Portion paid from a bonus pool (Suno, Seedance, etc.).
`refunded`	bool	`true` only after a failed task has been refunded.

The same values are also emitted as response headers on every /api/v1/* response, so agents can read cost without parsing the body:

X-MuAPI-Cost-USD:           0.004200
X-MuAPI-Cost-Credits:       1
X-MuAPI-Cost-Bonus-Credits: 0       (only when non-zero)
X-MuAPI-Cost-Refunded:      true    (only when refunded)
X-Account-Balance:          18.7234 (remaining wallet balance, USD)

Status Values

Status	Description
`queued`	Job is waiting to start
`pending`	Job accepted, not yet running
`processing`	Generation in progress
`completed`	Output is ready
`failed`	Generation failed
`cancelled`	Job was cancelled

Account Endpoints

# Check balance
GET /api/v1/account/balance

# Top up credits
POST /api/v1/account/topup
{ "amount": 20 }

API Key Management

# List keys
GET /api/v1/keys

# Create key
POST /api/v1/keys
{ 
  "name": "my-app",
  "is_test": true 
}

Sandbox (Testing) Mode

Sandbox mode allows you to test your integration without consuming credits or performing actual background tasks.

Features

Zero Cost: No credits are deducted from your account.
Instant Response: Jobs are completed immediately with mock data.
No Side Effects: Background workers are not triggered; no actual generation occurs.

How to use

Create a key with "is_test": true via the API or select the Sandbox checkbox in the dashboard.
Use this key in any submit-then-poll workflow.
The API will return successful mock responses immediately.

Behavior by Model Type

Images: Returns the model's example/thumbnail URL.
Videos/Audio: Returns the model's example media URL.

Delete key

DELETE /api/v1/keys/{key_id}


## File Upload

Upload media to use as inputs:

```bash
POST /api/v1/upload_file
x-api-key: YOUR_API_KEY
Content-Type: multipart/form-data

file=@image.jpg

Returns a hosted URL to pass as image_url in generation requests.

OpenAPI Spec

The full machine-readable spec is available at:

GET https://api.muapi.ai/openapi.json

Or via CLI:

muapi docs openapi
muapi docs open