Documentación de la API

Autenticación

Crea una clave en tu cuenta y envíala en cada llamada, en el encabezado Authorization: Bearer. La clave se muestra una sola vez; guárdala como una contraseña y nunca la pongas en código que corre en el navegador. Revocada, deja de funcionar al instante.

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

Cobro

Solo saldo prepago, solo en dólares: recargas en US$ (mínimo US$ 10) y cada generación descuenta su valor. Sin mensualidad, y el saldo no vence.

Los créditos de los planes del sitio no pagan la API. Incluso quien tiene un plan usa aquí el saldo en dólares.

El valor se reserva cuando se crea la generación. Si falla, es rechazada o cancelada, el valor vuelve entero al saldo. Sin saldo suficiente, la respuesta es 402 y no se crea ni se cobra nada.

Precios

Pagas por la unidad real de consumo: por segundo de video y por imagen, según la resolución. Usa /v1/estimativa para saber el valor exacto antes de generar.

Vídeo

Imagen

Endpoints

Base: la dirección de este sitio. Los importes vienen en centavos de dólar (enteros).

GET/v1/motores

Lista los motores, los parámetros aceptados (valores y predeterminados), las referencias aceptadas y el precio por unidad en dólares. Filtra con ?tipo=imagem o ?tipo=video.

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

POST/v1/estimativa

Dice cuánto cuesta una generación en dólares, sin crear 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

Crea una generación y devuelve 201 con ella en "criando". Campos: motor, prompt, params (opcional; lo que falte usa el predeterminado) y webhook_url (opcional). Siempre se cobra del saldo en dólares.

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

Con imágenes de referencia, envía multipart/form-data: los mismos campos como texto (params en JSON) y cada imagen en el campo referencias (PNG, JPEG o WebP, hasta 10 MB cada una).

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>

El estado de la generación: criando, pronta, falhou o cancelada. Cuando está lista, "arquivos" trae la dirección de cada archivo. "estornado": true cuando el valor ya fue devuelto.

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

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

Redirige (302) a un enlace de descarga temporal del archivo. Usa -L en curl para seguirlo.

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

POST/v1/geracoes/<id>/cancelar

Cancela mientras la generación no empezó y devuelve el valor. Después, 409 nao_cancelavel.

GET/v1/geracoes?pagina=1

Las generaciones de tu cuenta por la API, las más nuevas primero, 50 por página.

GET/v1/saldo

Tu saldo en dólares, en centavos.

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

Repetir sin pagar dos veces

Envía el encabezado Idempotency-Key (letras, números, . _ : -, hasta 128) en POST /v1/geracoes. Repetir la misma clave devuelve la misma generación, sin cobrar de nuevo: seguro para reintentar tras un error de red.

Aviso al terminar (webhook)

Con webhook_url (https, puerto 443, dirección pública), Doro hace un POST JSON cuando la generación termina: {"evento": "geracao.terminada", "geracao": {...}}, el mismo cuerpo de la consulta. Las respuestas 2xx cuentan como entregado; hasta 3 intentos. No se siguen redirecciones.

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)

Verifica la firma del encabezado Doro-Signature: HMAC-SHA256 del secreto de tu cuenta (en el área de claves) sobre "<t>.<cuerpo>". Rechaza avisos con t muy antiguo.

Límites

Por clave: 3 generaciones en curso a la vez y 60 por hora; por cuenta: 6 en curso y 120 por hora; y 120 llamadas por minuto por clave. Por encima, 429 con el encabezado Retry-After.

Errores

Todo error es JSON: {"erro": "<código>"}, con "campo" en el 400. El texto del código no cambia; úsalo en tu manejo.