API documentation

Authentication

Create a key in your account and send it on every call, in the Authorization: Bearer header. The key is shown only once; keep it like a password and never put it in code that runs in a browser. Once revoked, it stops immediately.

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

Billing

Prepaid balance only, in US dollars only: you top up in USD (minimum US$ 10) and each generation deducts its price. No monthly fee, and the balance never expires.

Credits from the site's plans don't pay for the API. Even subscribers use the dollar balance here.

The amount is reserved when the generation is created. If it fails, is rejected or cancelled, the full amount goes back to your balance. Without enough balance, the response is 402 and nothing is created or charged.

Prices

You pay for the real unit of usage: per second of video and per image, by resolution. Use /v1/estimativa to get the exact price before generating.

Video

Image

Endpoints

Base: this site's address. Money amounts are whole US cents.

GET/v1/motores

Lists the engines, accepted parameters (values and defaults), accepted references and the price per unit in dollars. Filter with ?tipo=imagem or ?tipo=video.

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

POST/v1/estimativa

Tells you what a generation costs in dollars, without creating anything.

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

Creates a generation and returns 201 with it in "criando". Fields: motor, prompt, params (optional; missing ones use the default) and webhook_url (optional). It is always charged to the dollar balance.

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"}'

With reference images, send multipart/form-data: the same fields as text (params as JSON) and each image in the referencias field (PNG, JPEG or WebP, up to 10 MB each).

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>

The generation status: criando, pronta, falhou or cancelada. When ready, "arquivos" lists the address of each file. "estornado": true when the amount has been refunded.

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

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

Redirects (302) to a temporary download link for the file. Use -L in curl to follow it.

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

POST/v1/geracoes/<id>/cancelar

Cancels while the generation hasn't started and refunds the amount. After that, 409 nao_cancelavel.

GET/v1/geracoes?pagina=1

Your account's generations through the API, newest first, 50 per page.

GET/v1/saldo

Your dollar balance, in cents.

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

Retry without paying twice

Send the Idempotency-Key header (letters, digits, . _ : -, up to 128) on POST /v1/geracoes. Repeating the same key returns the same generation without charging again: safe to retry after a network error.

Completion notice (webhook)

With webhook_url (https, port 443, public address), Doro sends a JSON POST when the generation finishes: {"evento": "geracao.terminada", "geracao": {...}}, the same body as the status call. 2xx responses count as delivered; up to 3 attempts. Redirects are not followed.

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)

Check the Doro-Signature header: HMAC-SHA256 of your account secret (in the keys area) over "<t>.<body>". Reject notices with a t that is too old.

Limits

Per key: 3 generations in progress at once and 60 per hour; per account: 6 in progress and 120 per hour; and 120 calls per minute per key. Above that, 429 with the Retry-After header.

Errors

Every error is JSON: {"erro": "<code>"}, with "campo" on 400. The code text never changes; use it in your handling.