MLMux API

Schnellstart

1. 01

   API-Schlüssel erstellen

   Erstellen Sie einen Schlüssel unter Konsole → API-Schlüssel. Der vollständige Schlüssel wird nur einmal angezeigt; speichern Sie ihn daher sofort, beispielsweise als MLMUX_API_KEY.

2. 02

   Anfrage senden

   Rufen Sie einen Bild- oder Video-Endpunkt mit einer Modell-ID und einem Prompt auf. Die Nutzung wird dem Konto des Schlüsselinhabers berechnet.

3. 03

   Ergebnis abrufen

   Bildanfragen geben URLs in der Antwort zurück. Videoanfragen geben einen Task zurück: Rufen Sie dessen poll_url regelmäßig ab oder abonnieren Sie einen Webhook.

Authentifizierung

Senden Sie Ihren Schlüssel im Header Authorization: Bearer bei jeder Anfrage an https://api.mlmux.com. Schlüssel beginnen mit sk-. Die API akzeptiert keine Schlüssel in anderen Headern oder im Query-String.

Um zu prüfen, ob ein Schlüssel funktioniert, listen Sie die aufrufbaren Modelle auf:

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

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

Endpunkte

Alle Endpunkte befinden sich unter https://api.mlmux.com. Sofern nicht anders angegeben, sind Request- und Response-Bodys im JSON-Format.

Routing-Modus

Legen Sie route_mode im Request-Body fest, um das Upstream-Tier auszuwählen. Eine Anfrage verbleibt in ihrem Tier und wechselt nie stillschweigend zu einem anderen; ist das Tier für das Modell deaktiviert, schlägt die Anfrage mit route_mode_disabled fehl. Wird das Feld ausgelassen, verwendet MLMux die für den API-Key konfigurierten Route-Modi und danach den Modell-Standardwert, welcher official-cheap ist.

Abrechnung

Die Nutzung wird in Credits abgerechnet, wobei 1 Credit 1 US-Dollar entspricht. Videomodelle werden pro Output-Token abgerechnet; Bildmodelle je nach Modell pro Upstream-Token oder pro Bild. Tarife für jede Route finden Sie auf der Preisseite.

Task-Antworten zeigen bei der Erstellung des Tasks estimated_charge_credits und nach erfolgreichem Abschluss actual_charge_credits an, beides in Credits. Webhook-Nutzdaten enthalten actual_charge_nano_credits als Ganzzahl, wobei 1.000.000.000 Nano-Credits 1 Credit entsprechen.

Prüfen Sie Ihr verbleibendes Guthaben mit GET /v1/account/balance.

Tasks und Polling

Videoanfragen sowie Bildanfragen mit "async": true geben HTTP 202 mit einem Task zurück. Rufen Sie die poll_url des Tasks alle paar Sekunden ab, bis der Status succeeded, failed, expired oder canceled lautet.

Task abbrechen

Tasks mit dem Status queued, submitted oder running können abgebrochen werden; die reservierten Credits werden freigegeben. Die Antwort lautet {"id": "task_…", "status": "canceled"}. Bei allen anderen Status wird 409 task_not_cancelable zurückgegeben.

Sichere Wiederholungsversuche

Asynchrone Video- und Bildgenerierungsanfragen akzeptieren einen Idempotency-Key-Header mit bis zu 160 Zeichen. Wird derselbe Schlüssel mit demselben Body erneut gesendet, wird der ursprüngliche Task zurückgegeben, anstatt einen neuen zu erstellen. Wird derselbe Schlüssel mit einem anderen Body gesendet, wird 409 idempotency_key_reused zurückgegeben. Synchrone Anfragen und Bildbearbeitungen akzeptieren diesen Header nicht.

Uploads

Um eine lokale Datei als Referenz zu verwenden, laden Sie sie als Multipart-Feld file hoch. Bilder, Videos und Audiodateien bis zu 50 MB werden akzeptiert und 3 Tage lang gespeichert. Übergeben Sie die zurückgegebene url in einem beliebigen URL-Feld einer Generierungsanfrage.

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

Erstellen Sie einen Endpunkt unter Console → Webhooks und wählen Sie die zu empfangenden Events aus. Wenn eine Anfrage oder ein Task abgeschlossen ist, sendet MLMux eine POST-Anfrage mit einem JSON-Body an Ihre 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": "model/seedance-2.5-max",
    "api_method": "videos.generations.create",
    "image_count": 0,
    "image_resolution": "",
    "video_seconds": 8,
    "video_resolution": "720p",
    "actual_charge_nano_credits": 1790000000,
    "latency_ms": 94210
  }
}

Signaturen überprüfen

Jede Zustellung wird mit dem Signiergeheimnis des Endpunkts (whsec_…) signiert, das einmalig beim Erstellen oder Rotieren angezeigt wird. Der Header X-MLMux-Signature enthält einen Unix-Zeitstempel t und eine Signatur v1: den Hex-HMAC-SHA256 des Zeitstempels, eines Punkts und des Roh-Request-Bodys. Berechnen Sie denselben Wert, vergleichen Sie ihn und weisen Sie alte Zeitstempel zurück.

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 ?? ""));
}

Geben Sie innerhalb von 10 Sekunden einen beliebigen 2xx-Status zurück. MLMux unternimmt bis zu 6 Zustellversuche über etwa 11 Stunden. Verwenden Sie X-MLMux-Event-ID, um doppelte Zustellungen zu ignorieren.

Fehler

Fehler teilen dasselbe JSON-Format. Verzweigen Sie basierend auf code statt message. Geben Sie die request_id an, die auch im Header X-Request-ID zurückgegeben wird, wenn Sie den Support kontaktieren.

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

429-Antworten enthalten einen Retry-After-Header. Warten Sie diese Anzahl von Sekunden, bevor Sie es erneut versuchen, und wiederholen Sie 5xx-Fehler mit exponentiellem Backoff.