Documentação da API

Autenticação

Crie uma chave na sua conta e mande em toda chamada, no cabeçalho Authorization: Bearer. A chave aparece uma vez só; guarde como uma senha e nunca a coloque em código que roda no navegador. Revogada, ela para na hora.

curl https://dorovisual.com/v1/saldo \
  -H "Authorization: Bearer doro_xxxxxxxxxxxx_..."

Cobrança

Só saldo pré-pago, só em dólar: você recarrega em US$ (mínimo de US$ 10) e cada geração desconta o valor dela. Sem mensalidade, e o saldo não vence.

Os créditos dos planos do site não pagam a API. Mesmo quem assina um plano usa o saldo em dólar aqui.

O valor é reservado quando a geração é criada. Se ela falhar, for recusada ou cancelada, o valor volta inteiro ao saldo. Sem saldo suficiente, a resposta é 402 e nada é criado nem cobrado.

Preços

Você paga pela unidade real de consumo: por segundo de vídeo e por imagem, conforme a resolução. Use /v1/estimativa para saber o valor exato antes de gerar.

Vídeo

Imagem

Endpoints

Base: o endereço deste site. Valores em dinheiro vêm em centavos de dólar (inteiros).

GET/v1/motores

Lista os motores, os parâmetros aceitos (valores e padrões), as referências aceitas e o preço por unidade em dólar. Filtre com ?tipo=imagem ou ?tipo=video.

curl https://dorovisual.com/v1/motores -H "Authorization: Bearer $DORO_KEY"

POST/v1/estimativa

Diz quanto uma geração custa em dólar, sem criar nada.

curl https://dorovisual.com/v1/estimativa -H "Authorization: Bearer $DORO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"motor": "seedance_2_0", "params": {"duracao": 5, "resolucao": "720p"}}'

POST/v1/geracoes

Cria uma geração e devolve 201 com ela em "criando". Campos: motor, prompt, params (opcional; o que faltar usa o padrão) e webhook_url (opcional). A cobrança é sempre no saldo em dólar.

curl https://dorovisual.com/v1/geracoes -H "Authorization: Bearer $DORO_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-123" \
  -d '{"motor": "nano_banana_pro", "prompt": "a red fox in the snow, golden hour",
       "params": {"resolucao": "2K", "proporcao": "16:9", "quantidade": 1},
       "webhook_url": "https://example.com/doro/aviso"}'

Com imagens de referência, mande multipart/form-data: os mesmos campos como texto (params em JSON) e cada imagem no campo referencias (PNG, JPEG ou WebP, até 10 MB cada).

curl https://dorovisual.com/v1/geracoes -H "Authorization: Bearer $DORO_KEY" \
  -F motor=seedance_2_0 -F prompt="the fox starts to run" \
  -F 'params={"duracao": 5}' -F [email protected]

{"geracao": {"id": "3f1c…", "motor": "Seedance 2.0", "tipo": "video", "estado": "criando",
  "cobranca": "saldo", "valor": {"moeda": "USD", "centavos": 460}, "arquivos": [],
  "estornado": false, "criado_em": "2026-10-06T12:00:00+00:00", "pronto_em": null}}

GET/v1/geracoes/<id>

O estado da geração: criando, pronta, falhou ou cancelada. Quando fica pronta, "arquivos" traz o endereço de cada arquivo. "estornado": true quando o valor já voltou.

curl https://dorovisual.com/v1/geracoes/3f1c… -H "Authorization: Bearer $DORO_KEY"

GET/v1/geracoes/<id>/arquivos/<n>

Redireciona (302) para um link de download temporário do arquivo. Use -L no curl para seguir.

curl -L -o resultado.mp4 https://dorovisual.com/v1/geracoes/3f1c…/arquivos/0 \
  -H "Authorization: Bearer $DORO_KEY"

POST/v1/geracoes/<id>/cancelar

Cancela enquanto a geração ainda não começou e devolve o valor. Depois disso, 409 nao_cancelavel.

GET/v1/geracoes?pagina=1

As gerações da sua conta pela API, mais novas primeiro, 50 por página.

GET/v1/saldo

O saldo em dólar, em centavos.

{"saldo": {"USD": 2000}}

Repetir sem pagar duas vezes

Mande o cabeçalho Idempotency-Key (letras, números, . _ : -, até 128) em POST /v1/geracoes. Repetir a mesma chave devolve a mesma geração, sem cobrar de novo: seguro para tentar de novo depois de um erro de rede.

Aviso ao terminar (webhook)

Com webhook_url (https, porta 443, endereço público), o Doro faz um POST JSON quando a geração termina: {"evento": "geracao.terminada", "geracao": {...}}, o mesmo corpo da consulta. Respostas 2xx contam como entregue; até 3 tentativas. Redirecionamentos não são seguidos.

Doro-Signature: t=1760000000,v1=5f2b…

# Python
import hmac, hashlib
t, v1 = (p.split("=", 1)[1] for p in header.split(","))
esperado = hmac.new(segredo.encode(), f"{t}.".encode() + corpo, hashlib.sha256).hexdigest()
assert hmac.compare_digest(esperado, v1)

Confira a assinatura do cabeçalho Doro-Signature: HMAC-SHA256 do segredo da sua conta (na área de chaves) sobre "<t>.<corpo>". Recuse aviso com t muito antigo.

Limites

Por chave: 3 gerações em andamento ao mesmo tempo e 60 por hora; por conta: 6 em andamento e 120 por hora; e 120 chamadas por minuto por chave. Acima disso, 429 com o cabeçalho Retry-After.

Erros

Todo erro é JSON: {"erro": "<código>"}, com "campo" no 400. O texto do código não muda; use ele no seu tratamento.