API de MLMux

Inicio rápido

1. 01

   Crear una clave de API

   Crea una clave en Consola → Claves API. La clave completa solo se muestra una vez, así que guárdala de inmediato, por ejemplo como MLMUX_API_KEY.

2. 02

   Enviar una solicitud

   Llama a un endpoint de imagen o video con un ID de modelo y un prompt. El uso se cobra a la cuenta propietaria de la clave.

3. 03

   Obtener el resultado

   Las solicitudes de imagen devuelven URLs en la respuesta. Las solicitudes de video devuelven una tarea: consulta periódicamente su poll_url o suscríbete a un webhook.

Autenticación

Envía tu clave en el encabezado Authorization: Bearer en cada solicitud a https://api.mlmux.com. Las claves comienzan con sk-. La API no acepta claves en otros encabezados ni en la cadena de consulta.

Para comprobar que una clave funciona, lista los modelos a los que puede llamar:

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

Todos los endpoints están bajo https://api.mlmux.com. Los cuerpos de solicitud y respuesta son JSON a menos que se indique lo contrario.

Modo de ruta

Define route_mode en el cuerpo de la solicitud para elegir el nivel upstream. Una solicitud permanece en su nivel y nunca pasa a otro de forma silenciosa; si el nivel está desactivado para el modelo, la solicitud falla con route_mode_disabled. Cuando se omite el campo, MLMux utiliza los modos de enrutamiento configurados en la clave de API y, luego, el valor predeterminado del modelo, que es official-cheap.

Facturación

El uso se cobra en créditos, y 1 crédito equivale a 1 dólar estadounidense. Los modelos de video se facturan por token de salida; los modelos de imagen se facturan por token del proveedor o por imagen, según el modelo. Consulta la página de precios para ver las tarifas de cada ruta.

Las respuestas de las tareas muestran estimated_charge_credits cuando se crea la tarea y actual_charge_credits después de completarse con éxito, ambos en créditos. Los payloads de webhook muestran actual_charge_nano_credits como un entero, donde 1,000,000,000 de nano-créditos equivalen a 1 crédito.

Consulta tu saldo restante con GET /v1/account/balance.

Tareas y sondeo

Las solicitudes de video y las solicitudes de imagen enviadas con "async": true devuelven HTTP 202 con una tarea. Sondea el poll_url de la tarea cada pocos segundos hasta que su estado sea succeeded, failed, expired o canceled.

Cancelar una tarea

Las tareas en estado queued, submitted o running se pueden cancelar, y sus créditos retenidos se liberan. La respuesta es {"id": "task_…", "status": "canceled"}. Las tareas en cualquier otro estado devuelven 409 task_not_cancelable.

Reintentos seguros

Las solicitudes asíncronas de generación de imagen y video admiten un encabezado Idempotency-Key de hasta 160 caracteres. Enviar la misma clave con el mismo cuerpo nuevamente devuelve la tarea original en lugar de crear una nueva. Enviar la misma clave con un cuerpo diferente devuelve 409 idempotency_key_reused. Las solicitudes síncronas y las ediciones de imagen no admiten este encabezado.

Cargas

Para usar un archivo local como referencia, cárguelo como el campo multipart file. Se admiten imágenes, videos y audio de hasta 50 MB, los cuales se conservan durante 3 días. Pase la url devuelta en cualquier campo URL de una solicitud de generación.

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

Cree un endpoint en Console → Webhooks y elija los eventos que desea recibir. Cuando finaliza una solicitud o tarea, MLMux envía una solicitud POST con un cuerpo JSON a su 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
  }
}

Verificar firmas

Cada entrega se firma con el secreto de firma del endpoint (whsec_…), que se muestra una sola vez al crearlo o rotarlo. El encabezado X-MLMux-Signature contiene una marca de tiempo Unix t y una firma v1: el HMAC-SHA256 en hexadecimal de la marca de tiempo, un punto y el cuerpo sin procesar de la solicitud. Calcule el mismo valor, compárelo y rechace marcas de tiempo antiguas.

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

Devuelva cualquier estado 2xx en un plazo de 10 segundos. MLMux realiza hasta 6 intentos de entrega a lo largo de unas 11 horas. Use X-MLMux-Event-ID para ignorar entregas duplicadas.

Errores

Los errores comparten una misma estructura JSON. Condicione la lógica en función de code y no de message. Incluya request_id, que también se devuelve en el encabezado X-Request-ID, al ponerse en contacto con soporte.

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

Las respuestas 429 incluyen un encabezado Retry-After. Espere esa cantidad de segundos antes de reintentar, y reintente los errores 5xx con retroceso exponencial.