MLMux API

Quickstart

1. 01

   Create an API key

   Create a key in Console → API keys. The full key is shown only once, so store it right away, for example as MLMUX_API_KEY.

2. 02

   Send a request

   Call an image or video endpoint with a model ID and a prompt. Usage is charged to the account that owns the key.

3. 03

   Get the result

   Image requests return URLs in the response. Video requests return a task: poll its poll_url or subscribe to a webhook.

Authentication

Send your key in the Authorization: Bearer header on every request to https://api.mlmux.com. Keys start with sk-. The API does not accept keys in other headers or in the query string.

To check that a key works, list the models it can call:

curl https://api.mlmux.com/v1/models \
  -H "Authorization: Bearer $MLMUX_API_KEY"

{
  "object": "list",
  "data": [
    { "id": "google/nano-banana-2", "object": "model", "owned_by": "platform" },
    { "id": "bytedance/seedance-2.5", "object": "model", "owned_by": "platform" }
  ]
}

Endpoints

All endpoints are under https://api.mlmux.com. Request and response bodies are JSON unless noted.

Route mode

Set route_mode in the request body to choose the upstream tier. A request stays in its tier and never silently moves to another one; if the tier is turned off for the model, the request fails with route_mode_disabled. When the field is omitted, MLMux uses the route modes set on the API key, then the model default, which is official-cheap.

Billing

Usage is charged in credits, and 1 credit equals 1 US dollar. Video models are billed per output token; image models are billed per upstream token or per image, depending on the model. See the pricing page for rates on each route.

Task responses show estimated_charge_credits when the task is created and actual_charge_credits after it succeeds, both in credits. Webhook payloads show actual_charge_nano_credits as an integer, where 1,000,000,000 nano-credits equal 1 credit.

Check your remaining balance with GET /v1/account/balance.

Tasks and polling

Video requests, and image requests sent with "async": true, return HTTP 202 with a task. Poll the task's poll_url every few seconds until its status is succeeded, failed, expired, or canceled.

Cancel a task

Tasks that are queued, submitted, or running can be canceled, and their held credits are released. The response is {"id": "task_…", "status": "canceled"}. Tasks in any other status return 409 task_not_cancelable.

Safe retries

Async video and image generation requests accept an Idempotency-Key header of up to 160 characters. Sending the same key with the same body again returns the original task instead of creating a new one. Sending the same key with a different body returns 409 idempotency_key_reused. Synchronous requests and image edits do not accept this header.

Uploads

To use a local file as a reference, upload it as the multipart field file. Images, videos, and audio up to 50 MB are accepted and kept for 3 days. Pass the returned url in any URL field of a generation request.

curl https://api.mlmux.com/v1/uploads \
  -H "Authorization: Bearer $MLMUX_API_KEY" \
  -F "file=@start-frame.jpg"

{
  "url": "https://.../uploads/3f8a....jpg",
  "asset_id": 1024,
  "mime_type": "image/jpeg",
  "size_bytes": 482113,
  "asset_type": "image"
}

Webhooks

Create an endpoint in Console → Webhooks and choose the events to receive. When a request or task finishes, MLMux sends a POST request with a JSON body to your URL.

{
  "event_id": "evt_5b0d...",
  "event_type": "request.succeeded",
  "created_at": "2026-10-26T08:00:00Z",
  "data": {
    "request_id": "task_task_01a9...",
    "task_id": "task_01a9...",
    "public_model_id": "bytedance/seedance-2.5",
    "api_method": "videos.generations.create",
    "image_count": 0,
    "image_resolution": "",
    "video_seconds": 8,
    "video_resolution": "720p",
    "actual_charge_nano_credits": 1790000000,
    "latency_ms": 94210
  }
}

Verify signatures

Each delivery is signed with the endpoint's signing secret (whsec_…), which is shown once when you create or rotate it. The X-MLMux-Signature header holds a Unix timestamp t and a signature v1: the hex HMAC-SHA256 of the timestamp, a period, and the raw request body. Compute the same value, compare it, and reject old timestamps.

import crypto from "node:crypto";

// header: X-MLMux-Signature: t=1767225600,v1=5f8c...
export function verifyMLMuxSignature(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((part) => part.split("=")));
  const expected = crypto.createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
  return fresh && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1 ?? ""));
}

Return any 2xx status within 10 seconds. MLMux makes up to 6 delivery attempts over about 11 hours. Use X-MLMux-Event-ID to ignore duplicate deliveries.

Errors

Errors share one JSON shape. Branch on code rather than message. Include request_id, which is also returned in the X-Request-ID header, when you contact support.

{
  "error": {
    "message": "Invalid API key",
    "type": "invalid_request_error",
    "code": "invalid_api_key",
    "request_id": "req_9f2c..."
  }
}

429 responses include a Retry-After header. Wait that many seconds before retrying, and retry 5xx errors with exponential backoff.