API MLMux

Démarrage rapide

1. 01

   Créer une clé API

   Créez une clé dans Console → Clés API. La clé complète n'est affichée qu'une seule fois, enregistrez-la donc immédiatement, par exemple sous MLMUX_API_KEY.

2. 02

   Envoyer une requête

   Appelez un endpoint d'image ou de vidéo avec un identifiant de modèle et un prompt. L'utilisation est facturée au compte propriétaire de la clé.

3. 03

   Obtenir le résultat

   Les requêtes d'image renvoient des URL dans la réponse. Les requêtes de vidéo renvoient une tâche : interrogez son poll_url ou abonnez-vous à un webhook.

Authentification

Envoyez votre clé dans l'en-tête Authorization: Bearer de chaque requête vers https://api.mlmux.com. Les clés commencent par sk-. L'API n'accepte pas les clés dans d'autres en-têtes ou dans la query string.

Pour vérifier qu'une clé fonctionne, listez les modèles qu'elle peut appeler :

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" }
  ]
}

Endpoints

Tous les endpoints se trouvent sous https://api.mlmux.com. Les corps de requête et de réponse sont en JSON, sauf indication contraire.

Mode de routage

Définissez route_mode dans le corps de la requête pour choisir le niveau en amont. Une requête reste dans son niveau et ne bascule jamais silencieusement vers un autre ; si le niveau est désactivé pour le modèle, la requête échoue avec route_mode_disabled. Lorsque le champ est omis, MLMux utilise les modes de routage définis sur la clé API, puis la valeur par défaut du modèle, qui est official-cheap.

Facturation

L'utilisation est facturée en crédits, où 1 crédit équivaut à 1 dollar américain. Les modèles vidéo sont facturés par token de sortie ; les modèles d'image sont facturés par token en amont ou par image, selon le modèle. Consultez la page des tarifs pour connaître les prix de chaque route.

Les réponses de tâche indiquent estimated_charge_credits lors de la création de la tâche et actual_charge_credits après sa réussite, tous deux exprimés en crédits. Les payloads de webhook indiquent actual_charge_nano_credits sous forme d'entier, où 1 000 000 000 nano-crédits équivalent à 1 crédit.

Consultez votre solde restant avec GET /v1/account/balance.

Tâches et polling

Les requêtes vidéo et les requêtes d'image envoyées avec "async": true renvoient un code HTTP 202 avec une tâche. Interrogez le poll_url de la tâche toutes les quelques secondes jusqu'à ce que son statut soit succeeded, failed, expired ou canceled.

Annuler une tâche

Les tâches aux statuts queued, submitted ou running peuvent être annulées, et leurs crédits réservés sont libérés. La réponse est {"id": "task_…", "status": "canceled"}. Les tâches dans tout autre statut renvoient 409 task_not_cancelable.

Nouvelles tentatives sécurisées

Les requêtes asynchrones de génération d'images et de vidéos acceptent un en-tête Idempotency-Key d'un maximum de 160 caractères. Envoyer à nouveau la même clé avec le même corps renvoie la tâche d'origine au lieu d'en créer une nouvelle. Envoyer la même clé avec un corps différent renvoie une erreur 409 idempotency_key_reused. Les requêtes synchrones et les modifications d'image n'acceptent pas cet en-tête.

Téléversements

Pour utiliser un fichier local comme référence, téléversez-le dans le champ multipart file. Les images, vidéos et fichiers audio jusqu'à 50 MB sont acceptés et conservés pendant 3 jours. Transmettez l'url renvoyée dans n'importe quel champ d'URL d'une requête de génération.

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

Créez un point de terminaison dans Console → Webhooks et choisissez les événements à recevoir. Lorsqu'une requête ou une tâche se termine, MLMux envoie une requête POST avec un corps JSON à votre 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
  }
}

Vérifier les signatures

Chaque envoi est signé avec le secret de signature du point de terminaison (whsec_…), qui n'est affiché qu'une seule fois lors de sa création ou de son renouvellement. L'en-tête X-MLMux-Signature contient un horodatage Unix t et une signature v1 : le HMAC-SHA256 hexadécimal de l'horodatage, d'un point et du corps brut de la requête. Calculez la même valeur, comparez-la et rejetez les horodatages trop anciens.

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

Renvoyez n'importe quel statut 2xx dans les 10 secondes. MLMux effectue jusqu'à 6 tentatives d'envoi sur une durée d'environ 11 heures. Utilisez X-MLMux-Event-ID pour ignorer les envois en double.

Erreurs

Les erreurs partagent une structure JSON unique. Fondez vos conditions sur code plutôt que sur message. Incluez request_id, qui est également renvoyé dans l'en-tête X-Request-ID, lorsque vous contactez l'assistance.

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

Les réponses 429 incluent un en-tête Retry-After. Attendez ce nombre de secondes avant de réessayer, et réessayez les erreurs 5xx avec un intervalle exponentiel.