MLMux API

Início rápido

1. 01

   Criar uma chave de API

   Crie uma chave em Console → Chaves de API. A chave completa é exibida apenas uma vez, portanto, armazene-a imediatamente, por exemplo, como MLMUX_API_KEY.

2. 02

   Envie uma requisição

   Chame um endpoint de imagem ou vídeo com um ID de modelo e um prompt. O uso é cobrado na conta proprietária da chave.

3. 03

   Obtenha o resultado

   Requisições de imagem retornam URLs na resposta. Requisições de vídeo retornam uma tarefa: faça polling da sua poll_url ou assine um webhook.

Autenticação

Envie sua chave no cabeçalho Authorization: Bearer em todas as requisições para https://api.mlmux.com. As chaves começam com sk-. A API não aceita chaves em outros cabeçalhos ou na query string.

Para verificar se uma chave funciona, liste os modelos que ela pode chamar:

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 os endpoints estão em https://api.mlmux.com. Os corpos de requisição e resposta são em JSON, a menos que indicado.

Modo de rota

Defina route_mode no corpo da requisição para escolher o nível upstream. Uma requisição permanece em seu nível e nunca muda silenciosamente para outro; se o nível estiver desativado para o modelo, a requisição falhará com route_mode_disabled. Quando o campo é omitido, o MLMux usa os modos de rota definidos na chave de API e, em seguida, o padrão do modelo, que é official-cheap.

Faturamento

O uso é cobrado em créditos, e 1 crédito equivale a 1 dólar americano. Os modelos de vídeo são cobrados por token de saída; os modelos de imagem são cobrados por token upstream ou por imagem, dependendo do modelo. Consulte a página de preços para ver as tarifas de cada rota.

As respostas de tarefas exibem estimated_charge_credits quando a tarefa é criada e actual_charge_credits após sua conclusão bem-sucedida, ambos em créditos. Os payloads de webhook exibem actual_charge_nano_credits como um número inteiro, em que 1,000,000,000 nano-créditos equivalem a 1 crédito.

Consulte seu saldo restante com GET /v1/account/balance.

Tarefas e polling

Requisições de vídeo e requisições de imagem enviadas com "async": true retornam HTTP 202 com uma tarefa. Faça polling da poll_url da tarefa a cada poucos segundos até que seu status seja succeeded, failed, expired ou canceled.

Cancelar uma tarefa

Tarefas que estejam queued, submitted ou running podem ser canceladas, e seus créditos retidos são liberados. A resposta é {"id": "task_…", "status": "canceled"}. Tarefas em qualquer outro status retornam 409 task_not_cancelable.

Retentativas seguras

Solicitações assíncronas de geração de vídeo e imagem aceitam um cabeçalho Idempotency-Key de até 160 caracteres. Enviar a mesma chave com o mesmo corpo novamente retorna a tarefa original em vez de criar uma nova. Enviar a mesma chave com um corpo diferente retorna 409 idempotency_key_reused. Solicitações síncronas e edições de imagem não aceitam este cabeçalho.

Uploads

Para usar um arquivo local como referência, faça o upload dele como o campo multipart file. Imagens, vídeos e áudios de até 50 MB são aceitos e mantidos por 3 dias. Passe a url retornada em qualquer campo de URL de uma solicitação de geração.

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

Crie um endpoint em Console → Webhooks e escolha os eventos a receber. Quando uma solicitação ou tarefa for concluída, o MLMux enviará uma solicitação POST com um corpo JSON para a sua 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 assinaturas

Cada entrega é assinada com o segredo de assinatura do endpoint (whsec_…), que é exibido apenas uma vez ao criá-lo ou alterná-lo. O cabeçalho X-MLMux-Signature contém um timestamp Unix t e uma assinatura v1: o HMAC-SHA256 em hexadecimal do timestamp, um ponto e o corpo bruto da solicitação. Calcule o mesmo valor, compare-o e rejeite timestamps antigos.

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

Retorne qualquer status 2xx em até 10 segundos. O MLMux faz até 6 tentativas de entrega ao longo de aproximadamente 11 horas. Use X-MLMux-Event-ID para ignorar entregas duplicadas.

Erros

Os erros compartilham o mesmo formato JSON. Faça o tratamento com base em code em vez de message. Inclua o request_id, que também é retornado no cabeçalho X-Request-ID, ao entrar em contato com o suporte.

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

Respostas 429 incluem um cabeçalho Retry-After. Aguarde esse número de segundos antes de tentar novamente e repita erros 5xx com backoff exponencial.