POST /v1/video/generations

Endpoint assíncrono para geração de vídeo a partir de texto ou imagem. Suporta 31 modelos de 8 provedores diferentes (Google, OpenAI, ByteDance, Alibaba, Runway, MiniMax, xAI, HeyGen e FLUX).

Fluxo completo

  1. Envie POST /v1/video/generations com modelo e prompt
  2. A Tokia estima o custo e reserva esse valor no seu saldo antes de chamar o provedor
  3. Receba o ID do vídeo (vid_...) e a URL de polling (status 202)
  4. Faça GET /v1/video/generations/:id a cada 5–10 segundos
  5. Quando status: "completed", cobramos o custo real, devolvemos a diferença da reserva e entregamos o link
  6. Baixe o vídeo antes de available_until

Reserva no saldo

Como num hotel que pré-autoriza o cartão, cada vídeo reserva o valor estimado (preço do provedor para a duração e a resolução pedidas, com margem de segurança) antes de ir ao provedor. A reserva aparece no extrato como Reserva de vídeo e não é cobrança. Quando o vídeo conclui, a reserva volta inteira (Reserva devolvida) e o custo real entra no consumo do dia. Se o vídeo falhar ou expirar (2 horas), a reserva volta inteira e nada é cobrado.

  • Sem duration ou resolution, usamos o padrão do modelo e enviamos esse valor explícito ao provedor.
  • No máximo 3 vídeos em andamento por conta ao mesmo tempo.
  • Se o custo real passar da reserva, a diferença sai do saldo livre. O que não couber fica como pendência de vídeo, quitada na próxima recarga; até lá, um novo vídeo precisa de saldo para a pendência e a nova reserva. Chat, imagem e áudio continuam funcionando.
  • Se a chave tiver limite de gasto, as reservas abertas contam contra esse limite.

Request body

CampoTipoObrigatórioNotas
modelstringsimID do modelo de vídeo (ver tabela abaixo)
promptstringsimDescrição do vídeo desejado
image_urlstringnãoURL de imagem de referência (image-to-video)
durationnumbernãoDuração em segundos (default: modelo define)
resolutionstringnão720p, 1080p, 4k
aspect_ratiostringnão16:9, 9:16, 1:1

Exemplo — submeter vídeo

bash
curl -X POST https://api.usetokia.com/v1/video/generations \
  -H "Authorization: Bearer $TOKIA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3-1-fast",
    "prompt": "um gato feliz usando uma bandana do Brasil, cena ensolarada, câmera lenta",
    "duration": 5,
    "resolution": "720p"
  }'

Response (202 Accepted)

json
{
  "id": "vid_8HqZ2kLmN4pQrS6tUvWx9yAb",
  "object": "video.generation",
  "model": "veo-3-1-fast",
  "status": "pending",
  "polling_url": "/v1/video/generations/vid_8HqZ2kLmN4pQrS6tUvWx9yAb",
  "created_at": "2026-11-12T15:00:00.000Z",
  "duration": 5,
  "resolution": "720p",
  "reserved_brl": 12.96
}

O ID é opaco e só vale para a conta que criou o vídeo: outra conta recebe 404 video_job_not_found. Qualquer chave ativa da mesma conta pode consultar.

Exemplo — consultar status

bash
curl https://api.usetokia.com/v1/video/generations/vid_8HqZ2kLmN4pQrS6tUvWx9yAb \
  -H "Authorization: Bearer $TOKIA_KEY"

Response — em progresso

json
{
  "id": "vid_8HqZ2kLmN4pQrS6tUvWx9yAb",
  "status": "in_progress",
  "progress": 40,
  "reserved_brl": 12.96,
  "polling_url": "/v1/video/generations/vid_8HqZ2kLmN4pQrS6tUvWx9yAb"
}

Response — concluído

json
{
  "id": "vid_8HqZ2kLmN4pQrS6tUvWx9yAb",
  "status": "completed",
  "cost_brl": 7.40,
  "refunded_brl": 5.56,
  "video_url": "https://api.usetokia.com/v1/video/generations/vid_8HqZ.../content?expires=1792421715&signature=...",
  "urls": ["https://api.usetokia.com/v1/video/generations/vid_8HqZ.../content?expires=1792421715&signature=..."],
  "content_url": "https://api.usetokia.com/v1/video/generations/vid_8HqZ.../content",
  "expires_at": 1792421715,
  "available_until": "2026-10-22T16:35:15.000Z",
  "notice": "Baixe o vídeo assim que ficar pronto: o link expira. ...",
  "polling_url": "/v1/video/generations/vid_8HqZ2kLmN4pQrS6tUvWx9yAb"
}

Outros status: billing_pending (vídeo pronto, cobrança sendo finalizada: responde 503 sem link, tente de novo em instantes), failed e expired (reserva devolvida inteira, nada cobrado).

Baixar o vídeo

GET /v1/video/generations/:id/content devolve o arquivo do vídeo. Funciona de dois jeitos: com a sua chave no cabeçalho Authorization (só para vídeos da sua conta), ou sem chave, pelo link assinado de video_url enquanto ele valer. Respostas: 409 video_not_ready (vídeo ainda não pronto), 403 video_link_expired ou video_link_invalid (consulte o vídeo de novo para um link novo), 410 video_link_expired (o provedor não guarda mais o vídeo) e 502 video_download_failed (tente de novo em instantes).

Listar seus vídeos

GET /v1/video/generations?limit=20&before=<next_cursor> devolve os vídeos da conta, do mais recente para o mais antigo, sem os links (consulte cada um pelo ID). Use para recuperar um ID perdido.

Modelos disponíveis

O preço segue a mesma composição dos outros modelos (veja Preços); o valor cobrado em reais vem em cost_brl quando o vídeo conclui. Preço em BRL calculado com câmbio do dia.

Em destaque

ModeloProvedorCusto upstream (5s)Preço Tokia (5s, ≈R$)Resolução maxÁudio
veo-3-1-fastGoogle$0.40~R$ 8,964KSim
veo-3-1Google$1.00~R$ 22,404KSim
sora-2-proOpenAI$1.50~R$ 33,601080pSim
seedance-2-5ByteDance~$0.50~R$ 11,20720pSim
kling-v3-proKuaishou$0.56~R$ 12,54720pSim
gen-4-5Runway$0.60~R$ 13,44720pNão
hailuo-3-maxMiniMax$0.25~R$ 5,60768pNão
wan-3-primeAlibaba$0.34~R$ 7,621080pSim

Todos os modelos

ID TokiaNomeProvedorPreço/s (USD)DuraçãoÁudio
heygen-video-1HeyGen VideoHeyGen$0.02–0.065–15sNão
flux-video-editFLUX Video EditBFL$0.03—Não
hailuo-3-maxHailuo 3 MaxMiniMax$0.05–0.085–15sNão
wan-3-primeWan 3.0 PrimeAlibaba$0.068–0.282–30sSim
wan-3Wan 3.0Alibaba$0.05–0.202–30sSim
avatar-ivAvatar IVHeyGen$0.05—Não
flux-video-upscaleFLUX UpscaleBFL$0.075–0.105—Não
seedance-2-miniSeedance 2.0 MiniByteDance~$0.0344–15sSim
seedance-2-5Seedance 2.5ByteDance~$0.104–30sSim
flux-3-videoFLUX.3 VideoBFL$0.17–0.535–20sSim
hailuo-3Hailuo 3MiniMax$0.135–15sSim
aleph-2Aleph 2.0Runway$0.28—Não
gen-4-5Gen-4.5 TurboRunway$0.122–10sNão
grok-imagine-video-1-5Grok Video 1.5xAI$0.08–0.251–15s—
happyhorse-1-1HappyHorse 1.1Alibaba$0.099–0.1283–15s—
happyhorse-1-0HappyHorse 1.0Alibaba$0.099–0.1693–15s—
grok-imagine-videoGrok VideoxAI$0.05–0.071–15s—
kling-v3-proKling v3.0 ProKuaishou$0.1123–15sSim
kling-v3-stdKling v3.0 StdKuaishou$0.0843–15sSim
veo-3-1-fastVeo 3.1 FastGoogle$0.08–0.304–8sSim
veo-3-1-liteVeo 3.1 LiteGoogle$0.03–0.084–8sSim
kling-video-o1Kling Video O1Kuaishou$0.1125, 10sSim
hailuo-2-3Hailuo 2.3MiniMax$0.0826, 10sNão
wan-2-7Wan 2.7Alibaba$0.102–10sSim
seedance-2-0Seedance 2.0ByteDance~$0.0674–15sSim
seedance-2-0-fastSeedance 2.0 FastByteDance~$0.0404–15sSim
wan-2-6Wan 2.6Alibaba$0.04–0.155, 10sSim
seedance-1-5-proSeedance 1.5 ProByteDance~$0.0234–12sSim
sora-2-proSora 2 ProOpenAI$0.30–0.504–20sSim
veo-3-1Veo 3.1Google$0.20–0.604–8sSim
kling-falKling Video (Fal)Fal.ai$0.065——

Erros comuns

CódigoSignificadoAção
400Campos obrigatórios faltando (missing_required_fields)Inclua model e prompt
401API key inválidaVerifique sua chave em /dashboard/keys
402insufficient_balance_for_video: saldo menor que a reservaA mensagem diz quanto precisa ser reservado; adicione saldo
402video_pending_balance: há diferença pendente de um vídeo anteriorAdicione saldo para a pendência e a nova reserva
402key_budget_exhausted: a reserva passa do limite da chaveAumente o limite da chave ou use outra
404video_job_not_found ou modelo inexistenteConfira o ID (ele só vale para a conta que criou)
422invalid_video_params: duração ou resolução não aceitasA resposta lista os valores aceitos em accepted
422not_a_video_model, video_content_rejected, video_upstream_rejected_paramsNada foi cobrado; ajuste o pedido
429too_many_video_jobs (3 vídeos em andamento) ou rate limitEspere um vídeo terminar ou o tempo de retry-after
502video_upstream_errorNada foi cobrado; tente novamente ou use outro modelo
503model_without_price, cost_guard_unavailable ou video_billing_pendingTente de novo em alguns minutos
504video_upstream_timeoutA reserva voltou; tente novamente

Exemplo Python

python
import requests
import time

TOKIA_KEY = "sk-..."
BASE = "https://api.usetokia.com"

"""Submeter"""
r = requests.post(f"{BASE}/v1/video/generations", json={
    "model": "seedance-2-0-fast",
    "prompt": "cachorro golden retriever correndo na praia ao pôr do sol",
    "duration": 5,
}, headers={"Authorization": f"Bearer {TOKIA_KEY}"})
job = r.json()
print(f"Job: {job['id']}")

"""Polling"""
while True:
    r = requests.get(f"{BASE}/v1/video/generations/{job['id']}",
                     headers={"Authorization": f"Bearer {TOKIA_KEY}"})
    status = r.json()
    if status.get("status") == "completed":
        print(f"Vídeo pronto: {status.get('video_url')}")
        break
    print(f"Status: {status.get('status')}...")
    time.sleep(10)

Exemplo Node.js

typescript
const TOKIA_KEY = "sk-...";
const BASE = "https://api.usetokia.com";

const submit = await fetch(`${BASE}/v1/video/generations`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${TOKIA_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "veo-3-1-fast",
    prompt: "paisagem montanhosa com nuvens passando em time-lapse",
    duration: 5,
    resolution: "1080p",
  }),
});
const job = await submit.json();
console.log("Job:", job.id);

while (true) {
  const poll = await fetch(`${BASE}/v1/video/generations/${job.id}`, {
    headers: { Authorization: `Bearer ${TOKIA_KEY}` },
  });
  const status = await poll.json();
  if (status.status === "completed") {
    console.log("Vídeo pronto:", status.video_url);
    break;
  }
  console.log("Status:", status.status);
  await new Promise((r) => setTimeout(r, 10000));
}