Documentação da API Makernice: início rápido

Autenticação

Toda requisição precisa de uma chave de API no cabeçalho Authorization, exceto GET /v1/models e GET /v1/pricing. As chaves começam com mn-, seguido de 48 letras e dígitos.

curl https://api.makernice.com/v1/generations \
  -H "Authorization: Bearer $MAKERNICE_API_KEY"

• A chave completa aparece uma única vez, quando você a cria. Guardamos só uma impressão digital, então uma chave perdida não pode ser recuperada: crie uma nova e exclua a antiga.
• Uma chave ausente, malformada, desconhecida, desativada, expirada ou excluída sempre recebe a mesma resposta 401 invalid_api_key. Desativar ou excluir uma chave vale a partir da próxima requisição.
• Chame a API a partir do seu servidor. Ela não aceita requisições de navegador entre origens (sem CORS); nunca coloque uma chave no código front-end.
• Todas as chaves de uma conta enxergam as mesmas gerações: qualquer chave pode consultar, listar e cancelar todas as gerações da conta, inclusive as criadas no console.
• Todas as chaves de uma conta usam o mesmo saldo pré-pago. Hoje, cada conta da Makernice tem um único login; equipes compartilham um saldo por meio de várias chaves de API.
• A página Chaves de API mostra o gasto total de cada chave, e a página Uso detalha o gasto da API por chave e por modelo.
• No console, você pode definir uma data de expiração e um limite de gastos para cada chave. O gasto de uma chave é a soma do valor cobrado e do valor reservado no momento das gerações que ela criou; uma requisição de criação que ultrapasse o limite recebe 402 key_spend_limit_reached. Gerações com falha e canceladas não entram na conta.

Preços e cobrança

• A cobrança é em dólares americanos. Todos os valores são strings de inteiros em micro-USD (milionésimos de dólar): 1,000,000 = $1.00. Leia-os como inteiros ou decimais, não como números de ponto flutuante.
• Vídeos têm preço por segundo (a quantidade é a duração pedida; num template com clipe de vídeo de referência, inclui os segundos do clipe); imagens, por requisição (uma imagem por geração). Preço = preço unitário × quantidade.
• A cotação trava o preço por 12 minutos (expires_at). A geração é cobrada pelo valor cotado, mesmo que os preços mudem nesse intervalo.

GET /v1/pricing lista os preços unitários da versão atual da tabela de preços. Não exige chave de API e pode ficar em cache por até 60 segundos. official_unit_price, quando presente, é o preço de tabela oficial da mesma combinação e serve só para comparação; a cobrança é sempre pelo unit_price.

{
  "price_version": 3,
  "data": [
    { "model": "seedance-2.5", "mode": "t2v", "resolution": "720p", "unit": "second", "unit_price": "100000", "unit_price_usd": "0.10", "official_unit_price": "120000" }
  ]
}

Gerações com falha são cobradas?

Não. A reserva é liberada por completo: você nunca é cobrado por uma geração com falha. Observação: se um resultado concluído for bloqueado pela moderação por violar a política, a execução ainda é cobrada; você pode pedir revisão manual ao suporte.

Quando você cria uma geração, reservamos o valor cotado. A reserva vira cobrança quando a execução é concluída; gerações com falha e tempo esgotado a liberam por completo, e o mesmo vale para cancelamentos ainda na fila. Uma reserva liberada não é um reembolso: o dinheiro nunca saiu do seu saldo.

Exemplos de cobrança

Obter uma cotação

Envie a entrada da geração; a resposta informa exatamente quanto a geração vai custar. Cada cotação vale para uma geração.

Os cinco últimos campos são extras opcionais. Cada modelo aceita só alguns deles: GET /v1/models lista os disponíveis para cada modo e resolução em prices[].options, com os valores permitidos e os padrões. Um campo que nenhuma rota do modelo consegue aplicar retorna 400 invalid_request; alterar um campo opcional exige uma nova cotação, como qualquer outro campo.

As imagens são URLs https públicas (até 2.048 caracteres). Campos que o modo não usa e campos desconhecidos são recusados com 400 invalid_request; para os campos de entrada, error.details lista cada problema como { path, message } (outros erros invalid_request podem ter details em outro formato ou não ter). Uma combinação sem preço retorna 422 price_unavailable.

Cada imagem deve ser uma URL https acessível publicamente que entregue uma imagem estática JPEG, PNG ou WebP (WebP animado e GIF não são aceitos), de até 10 MB, diretamente nessa URL: redirecionamentos não são seguidos. Buscamos cada imagem uma vez e guardamos uma cópia; a moderação de conteúdo e o modelo usam essa cópia. Se uma imagem não puder ser usada, a geração falha com invalid_request, error.input indica a imagem e a reserva é liberada.

curl https://api.makernice.com/v1/generations/quote \
  -H "Authorization: Bearer $MAKERNICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"seedance-2.5","mode":"t2v","prompt":"Travelling lento por dentro de uma estufa","duration":5,"resolution":"720p"}'

{
  "id": "qt_6f1c…",
  "amount": "500000",
  "price_version": 3,
  "expires_at": "2026-10-09T09:24:41.000Z",
  "facts": { "model": "seedance-2.5", "mode": "t2v", "resolution": "720p", "variant": "default", "unit": "second", "quantity": 5 }
}

Por quanto tempo uma cotação trava o preço?

Cada cotação trava o preço por 12 minutos, e a geração é sempre cobrada exatamente pelo valor cotado.

Criar uma geração

Crie a geração com a cotação e a mesma entrada. O cabeçalho Idempotency-Key é obrigatório (veja Idempotência).

curl https://api.makernice.com/v1/generations \
  -H "Authorization: Bearer $MAKERNICE_API_KEY" \
  -H "Idempotency-Key: 7c1e9a2b-order-1842" \
  -H "Content-Type: application/json" \
  -d '{"quote_id":"qt_6f1c…","input":{"model":"seedance-2.5","mode":"t2v","prompt":"Travelling lento por dentro de uma estufa","duration":5,"resolution":"720p"}}'

• Responde 202 com a geração (status: queued, billing: held). Uma nova tentativa com a mesma Idempotency-Key responde 200 com a geração original.
• Você pode alterar o prompt, mas alterar qualquer coisa que afete o preço (modelo, modo, resolução, duração) retorna 422 quote_mismatch.
• Uma cotação já usada retorna 409 quote_already_used; uma expirada, 410 quote_expired; e uma que não está na sua conta, 404 quote_not_found.
• Saldo insuficiente retorna 402 insufficient_balance; ultrapassar o limite de gastos da chave retorna 402 key_spend_limit_reached.
• callback_url opcional no nível superior (https, até 2048 caracteres, sem credenciais na URL, sem endereço privado ou reservado): quando a geração terminar, fazemos um POST dela para esse endereço. Ele tem prioridade sobre o endereço de webhook da sua conta. Veja Webhooks.

Consultar status

Consulte a geração até ela chegar a um status final. Consultar a cada poucos segundos não tem problema; veja o limite de leitura em Limites de taxa. Uma geração de vídeo pode levar alguns minutos, e mais ainda em clipes longos ou de alta resolução. Se uma execução passar do tempo máximo, ela falha e a reserva é liberada por completo.

O error.code de uma geração com falha é um destes: invalid_request (o modelo recusou a requisição; ajuste o prompt ou as configurações), content_rejected (recusado pela moderação de conteúdo ou pela política de segurança do provedor do modelo; a reserva é liberada), timeout, upstream_unavailable ou generation_failed. Em content_rejected, error.reason diz o que foi recusado: prompt (o prompt), input_image (uma imagem de referência) ou model (a política de segurança do provedor do modelo). O mesmo reason aparece na resposta 422 quando um prompt enviado é bloqueado. Quando o invalid_request é causado por uma imagem de referência que não pode ser usada, error.input indica qual: image_url, last_image_url ou reference_images[0] (índice a partir de zero). Troque essa imagem e crie uma nova geração.

{
  "id": "gen_3b9e…",
  "type": "video",
  "model": "seedance-2.5",
  "mode": "t2v",
  "status": "succeeded",
  "prompt": "Travelling lento por dentro de uma estufa",
  "params": { "duration": 5, "resolution": "720p", "aspectRatio": null },
  "amount": "500000",
  "billing": "charged",
  "price_version": 3,
  "outputs": [
    {
      "index": 0,
      "url": "/v1/generations/gen_3b9e…/outputs/0",
      "state": "stored",
      "contentType": "video/mp4",
      "expiresAt": "2026-11-08T09:14:03.000Z"
    }
  ],
  "error": null,
  "created_at": "2026-10-09T09:12:41.000Z",
  "finished_at": "2026-10-09T09:14:03.000Z"
}

90 dias depois que uma geração termina, o conteúdo da requisição é apagado conforme a nossa política de retenção de dados: prompt vira uma string vazia. Os dados de cobrança (model, params, amount, status e os horários) são mantidos.

GET /v1/generations/{id}/events retorna a linha do tempo da geração. Códigos: created, submitted, generating, delivered, failed_refunded, canceled_refunded, checking, requeued.

{
  "data": [
    { "code": "created", "at": "2026-10-09T09:12:41.000Z" },
    { "code": "submitted", "at": "2026-10-09T09:12:43.000Z" },
    { "code": "generating", "at": "2026-10-09T09:12:50.000Z" },
    { "code": "delivered", "at": "2026-10-09T09:14:03.000Z" }
  ]
}

Baixar resultados

Cada item de outputs tem uma url como /v1/generations/gen_…/outputs/0, relativa a https://api.makernice.com. Faça a requisição com a sua chave de API; a resposta é um redirecionamento 302 para um link temporário do arquivo. Sempre que precisar do arquivo, chame o endpoint de novo em vez de guardar o destino do redirecionamento.

curl -L -o video.mp4 https://api.makernice.com/v1/generations/gen_…/outputs/0 \
  -H "Authorization: Bearer $MAKERNICE_API_KEY"

• Adicione ?download=1 para receber o arquivo como anexo. Isso funciona quando o arquivo está stored; enquanto estiver pending ou degraded, o redirecionamento vai para o arquivo original e o parâmetro não tem efeito.
• O curl -L não envia o seu cabeçalho Authorization ao host do redirecionamento, então a sua chave fica só com a gente.
• Só existem resultados quando a geração está em succeeded; caso contrário, o endpoint retorna 404 output_not_found.
• state: pending (ainda sendo salvo; o link já funciona), stored (salvo até expiresAt), degraded (o salvamento não foi concluído; o link pode parar de funcionar antes — baixe logo), expired (o arquivo salvo expirou; o endpoint retorna 410 output_expired), blocked (o resultado não passou na moderação de conteúdo; url é uma string vazia — peça revisão manual ao suporte).

Cancelar

Só é possível cancelar gerações em queued; a reserva é liberada por inteiro e a resposta é a geração cancelada. Depois que a geração entra em generating, ela não pode ser interrompida, e o cancelamento retorna 409 not_cancelable.

curl -X POST https://api.makernice.com/v1/generations/gen_…/cancel \
  -H "Authorization: Bearer $MAKERNICE_API_KEY"

# → { "id": "gen_…", "status": "canceled", "billing": "released", … }

Listar gerações

Lista as gerações da sua conta, das mais recentes para as mais antigas — inclusive as criadas no console.

curl "https://api.makernice.com/v1/generations?status=queued,generating&limit=50" \
  -H "Authorization: Bearer $MAKERNICE_API_KEY"

# → { "data": [ …gerações… ], "next_cursor": "gen_…" | null, "total": 12 }

total conta todas as gerações que correspondem aos filtros. Quando next_cursor é null, você chegou à última página.

Webhooks

Em vez de consultar, você pode pedir que a gente faça um POST da geração para o seu servidor quando ela chegar a um status final. Enviamos para a callback_url informada ao criar a geração; se não houver, para o endereço de webhook da sua conta (defina nas configurações do console). Sem nenhum dos dois, nada é enviado.

Requisição

POST /your/webhook/path HTTP/1.1
Content-Type: application/json
Makernice-Signature: t=1791364443,v1=5f0c2d…e81a
Makernice-Event-Id: evt_1b7f…

{
  "id": "evt_1b7f…",
  "type": "generation.succeeded",
  "created_at": "2026-10-09T09:14:03.000Z",
  "data": {
    "id": "gen_3b9e…",
    "status": "succeeded",
    "billing": "charged",
    "outputs": [
      { "index": 0, "url": "https://api.makernice.com/v1/generations/gen_3b9e…/outputs/0", "state": "stored", … }
    ],
    …
  }
}

• data é o mesmo objeto de geração de GET /v1/generations/{id}, exceto que outputs[].url é uma URL absoluta.
• Makernice-Event-Id é igual ao id do corpo e não muda entre as tentativas. Use-o para ignorar duplicatas.

Verifique a assinatura

Makernice-Signature tem o formato t=<segundos unix>,v1=<hex>, em que v1 é o HMAC-SHA256, com o seu segredo de assinatura, de t + "." + corpo bruto. Calcule sobre os bytes brutos que você recebeu, compare em tempo constante e recuse requisições cujo t esteja a mais de 5 minutos do seu relógio. O segredo de assinatura fica nas configurações do console; as entregas para callback_url são assinadas com o mesmo segredo. Depois que você o trocar, as entregas ainda não enviadas são assinadas com o novo.

import { createHmac, timingSafeEqual } from "node:crypto";

// rawBody: the body exactly as received (Buffer). Don't re-serialize parsed JSON.
export function verifyWebhook(rawBody, signatureHeader, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(signatureHeader.split(",").map((p) => [p.slice(0, p.indexOf("=")), p.slice(p.indexOf("=") + 1)]));
  const t = Number(parts.t);
  if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
  const expected = createHmac("sha256", secret).update(`${t}.`).update(rawBody).digest();
  const given = Buffer.from(parts.v1 ?? "", "hex");
  return given.length === expected.length && timingSafeEqual(given, expected);
}

import hashlib
import hmac
import time


# raw_body: the body exactly as received (bytes). Don't re-serialize parsed JSON.
def verify_webhook(raw_body: bytes, signature_header: str, secret: str, tolerance_seconds: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in signature_header.split(",") if "=" in p)
    try:
        t = int(parts["t"])
    except (KeyError, ValueError):
        return False
    if abs(time.time() - t) > tolerance_seconds:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

Entrega e novas tentativas

• Só HTTPS. Redirecionamentos não são seguidos. Cada tentativa expira após 10 segundos.
• Qualquer resposta 2xx conta como entregue. Responda rápido e faça o trabalho pesado depois.
• Caso contrário, tentamos de novo após 1 min, 5 min, 30 min, 2 h, 6 h, 12 h — 7 tentativas no total — e então marcamos a entrega como falha. As entregas recentes e a última resposta de cada uma aparecem nas configurações do console.
• Normalmente cada geração envia um evento, e uma entrega pode chegar mais de uma vez (por exemplo, depois de um timeout do seu lado). Se um resultado retido pela revisão de conteúdo for liberado depois, enviamos a geração de novo com um novo id de evento, então você pode receber dois eventos para ela; vale o mais recente.

Modelos

GET /v1/models lista os modelos e os modos, resoluções e durações que você pode usar. Só aparecem os modos que têm preço, com os preços em modes[].prices. Não exige chave de API e pode ficar em cache por até 60 segundos.

• resolutions / defaultResolution: valores permitidos para resolution. Uma lista vazia significa que o modelo tem resolução fixa e você deve omitir resolution (enviá-lo, mesmo com o valor fixo, retorna 400 invalid_request). A faixa fixa é a que aparece em modes[].prices[].resolution: por exemplo, seedance-2.0-fast sempre renderiza em 720p. Uma resolução listada pode não ter preço em alguns modos: confira modes[].prices; pedir cotação para ela retorna 422 price_unavailable.
• durations: { min, max, default } em segundos para vídeos, null para imagens.
• modes[].needs: quais imagens o modo exige (image → image_url, lastImage → last_image_url, references → reference_images, até maxReferences).
• modes[].aspectRatios: valores permitidos de aspect_ratio. modes[].prices: preço unitário por resolução.

{
  "data": [
    {
      "id": "seedance-2.5",
      "type": "video",
      "resolutions": ["480p", "720p", "1080p", "4k"],
      "defaultResolution": "720p",
      "durations": { "min": 4, "max": 30, "default": 5 },
      "modes": [
        {
          "mode": "t2v",
          "needs": { "image": false, "lastImage": false, "references": false },
          "maxReferences": null,
          "aspectRatios": ["adaptive", "16:9", "9:16", "1:1", "4:3", "3:4", "21:9", "9:21"],
          "prices": [{ "resolution": "720p", "unit": "second", "unitPrice": "100000" }]
        }
      ]
    }
  ]
}

Quais modelos posso chamar?

Uma só chave de API chama todos os 17 modelos: 13 de vídeo e 4 de imagem da ByteDance, Kuaishou, MiniMax e Alibaba, entre eles Seedance, Kling, Wan e MiniMax H3. Todos os modelos usam o mesmo formato de requisição; defina model com o id de modelo da API indicado abaixo.

Modelos por tarefa, com os modos aceitos e exemplos de preço: image to video (em inglês), AI video generator (em inglês) e AI image generator (em inglês).

Erros

Os erros vêm em JSON: { "error": { "code", "message", "reason"?, "details"?, "request_id" } }. Tome decisões com base em code; as mensagens podem mudar. Toda resposta traz o cabeçalho x-request-id (mesmo valor de request_id); informe-o ao falar com o suporte para que a gente encontre a requisição.

Em respostas 5xx inesperadas ou erros de rede, tente de novo com backoff. Ao repetir uma requisição de criação, reutilize a mesma Idempotency-Key para nunca ser cobrado duas vezes.

Limites de taxa

Os limites são por minuto. Ultrapassá-los retorna 429 rate_limited com o cabeçalho Retry-After (em segundos).

Uma chave também pode ter no máximo 4 requisições de criação em andamento ao mesmo tempo; as que passarem disso também recebem 429. Os limites podem ser ajustados.

Cada conta também tem dois limites de uso: por padrão, 2 gerações em andamento ao mesmo tempo e US$100 de gasto por dia UTC. Ultrapassá-los retorna 429 concurrency_limit_reached (com Retry-After) ou 402 daily_spend_limit_reached. Fale com o suporte para aumentá-los. Uma geração conta para o limite de gerações em andamento enquanto estiver em queued, generating ou checking, seja qual for o modelo ou a chave que a criou. Ela deixa de contar ao chegar a moderating, succeeded, failed ou canceled. As gerações que você inicia no app web contam para o mesmo limite.

Idempotência

• POST /v1/generations exige o cabeçalho Idempotency-Key: de 1 a 200 caracteres ASCII imprimíveis, sem espaços. Use um valor novo, como um UUID, para cada nova geração.
• As chaves são únicas dentro da sua conta e compartilhadas por todas as chaves de API dela.
• Repetir uma requisição com a mesma chave, a mesma cotação e a mesma entrada devolve a geração original com 200 e não cobra de novo.
• Usar a mesma chave com outro quote_id, outro input (inclusive o prompt e as URLs das imagens) ou outra callback_url retorna 422 idempotency_conflict.
• Cotações e cancelamentos não usam Idempotency-Key. Repetir um cancelamento que já deu certo retorna 409 not_cancelable; confira o status com GET.

Perguntas frequentes