Documentación

Inicio rápido

Una clave, un formato de solicitud, todos los modelos de imagen y vídeo. Envía un trabajo, consúltalo y obtén el archivo.

En vivoTodos los modelos de la página de modelos funcionan en este endpoint. Imágenes y vídeo, un mismo formato de solicitud; las opciones y los precios de cada modelo están en /data/models.json.

NuevoTambién modelos de lenguaje. GPT, Claude, Gemini, Grok, DeepSeek, Qwen y más en el POST /v1/chat/completions compatible con OpenAI, facturados por token con el mismo crédito: consulta chat completions.

URL base	`https://api.revana.si/v1`
Autenticación	`Authorization: Bearer <key>`
Enviar	`POST /v1/generations`
Consultar	`GET /v1/generations/{id}`
Modelos	`GET /v1/models` (sin clave): todos los modelos con los que puedes generar ahora mismo
Saldo	`GET /v1/balance`: lo que puede gastar la cuenta de tu clave
Subir	`POST /v1/uploads`: un enlace para un archivo de referencia de tu ordenador
Formato	JSON de entrada, JSON de salida. Precios en USD; 100 créditos = $1.
Legible por máquinas	`/openapi.json` · `/llms.txt`

Autenticación

Crea una clave desde tu cuenta y envíala como bearer token en cada solicitud. Guárdala en tu servidor; nunca la incluyas en un navegador ni en una aplicación móvil.

Enviar una generación

POSThttps://api.revana.si/v1/generations

Envía el id del modelo y su input. La respuesta llega de inmediato con un id de generación y el estado queued; el trabajo se hace en segundo plano.

Campo	Tipo	Descripción
`model`	string, obligatorio	Un id de modelo de la página de modelos, p. ej., `seedance-2.5`.
`input`	object, obligatorio	El prompt y los ajustes; consulta los campos de entrada. Los campos desconocidos se rechazan.
`max_cost_usd`	number, opcional	Lo máximo que pagarás por esta generación, hasta `100` (el valor predeterminado). Las rutas con un precio superior se omiten; si no queda ninguna, la solicitud responde `422 max_cost_exceeded`.
`max_wait_s`	integer, opcional	Se omiten las rutas que se espera que tarden más de este número de segundos. Una vez superado, no se prueba ninguna ruta nueva, pero una que ya esté en ejecución puede terminar (hasta 40 minutos) y se cobra si entrega.
`Idempotency-Key`	header, opcional	Hasta 200 caracteres. Si envías la misma clave y el mismo cuerpo otra vez (tras un timeout o un `503`), obtienes la misma generación, no una segunda. La misma clave con un cuerpo distinto da `409 idempotency_conflict`.

Obtener el resultado

GEThttps://api.revana.si/v1/generations/{id}

¿Prefieres un endpoint por modelo y webhooks de finalización? Consulta la API de cola compatible con fal para ver los ID de solicitud, las URL de estado y resultado, los alias de fal admitidos y los límites de migración.

Consulta cada pocos segundos hasta que status sea succeeded o failed, y luego descarga con tu clave los archivos de output.urls: GET /v1/generations/{id}/content para el primero, y /content/2, /content/3… cuando un modelo de imágenes devuelve varios. Las imágenes suelen tardar segundos; el vídeo tarda desde menos de un minuto hasta varios minutos según el modelo y la duración.

Una generación terminada:

Campos de entrada

Se usan los mismos nombres en todos los modelos. Los campos y valores que acepta cada modelo, y sus valores predeterminados, se enumeran por modelo en /data/models.json (options, tasks). Si un modelo no admite un campo o valor, la solicitud se rechaza con 422 invalid_input antes de cobrar nada.

Campo	Tipo	Se usa para
`prompt`	string	Qué generar. Obligatorio para texto a imagen y texto a vídeo.
`image_url`	string (URL)	Fotograma inicial para imagen a vídeo, o la imagen que se va a editar para imagen a imagen.
`end_image_url`	string (URL)	Último fotograma, para modelos con primer y último fotograma.
`image_urls`	string[]	Imágenes de referencia, hasta el límite del modelo.
`resolution`	string	`720p`, `1080p`, `2K`... una de las resoluciones del modelo.
`duration`	number	Duración del vídeo en segundos, una de las duraciones del modelo.
`aspect_ratio`	string	`16:9`, `9:16`, `1:1`...
`audio`	boolean	Genera sonido junto con el vídeo, en los modelos que lo admiten. Puede cambiar el precio.
`negative_prompt`	string	Qué evitar, en los modelos que lo admiten.
`video_url`	string (URL)	Un clip para transformar, ampliar o escalar. Se mide su duración y, en los modelos que cobran por segundo, se factura.
`audio_url`	string (URL)	La voz o el sonido al que anima un modelo de avatar parlante o de sincronización labial.
`quality`	string	Un nivel de calidad en los modelos con precio por nivel (p. ej., `low`, `medium`, `high`).
`seed`	integer	Una semilla (seed), en los modelos que la admiten.

Seedance 2.5 usa por defecto 720p, 5 segundos (4–30), 16:9 y sin sonido, y además admite:

Campo	Tipo	Se usa para
`video_url`	string (URL)	Un clip de 4–30 s para editar. El resultado conserva su duración, así que omite `duration`.
`video_urls`	string[]	Clips de referencia, hasta 10 y 30 segundos en total. Sus segundos se facturan a la tarifa de vídeo de entrada.
`audio_urls`	string[]	Sonido de referencia, hasta 10 y 30 segundos en total.

image_url es un primer fotograma exacto, así que no se puede combinar con medios de referencia; usa image_urls para una referencia visual más flexible. end_image_url necesita image_url. Los medios deben ser URL https públicas que se descarguen directamente.

Nemesis

nemesis reconstruye un clip con tus propias personas, productos y lugares: el movimiento, el ritmo y la cámara del clip, interpretados por hasta 8 imágenes de referencia. El resultado conserva la duración y el formato del clip. Se cobra a la tarifa de una edición de Seedance 2.5 más $0.02 por segundo ($0.08, $0.17 y $0.36 a 480p, 720p y 1080p), por cada segundo del clip de entrada más el vídeo de salida.

Sigue la receta de Scenario ALTER: se edita el propio clip, sin sonido, con un fotograma redibujado con el cambio ya aplicado como primera referencia, y después se vuelve a poner el sonido original del clip. Con más de una persona, las imágenes se asocian de izquierda a derecha según el orden en que están las personas en el primer fotograma.

Campo	Tipo	Se usa para
`video_url`	string (URL), obligatorio	El clip de 4–30 s que se va a reconstruir.
`image_urls`	string[], obligatorio	1–8 imágenes de referencia.
`roles`	string[]	Una por imagen: `person` (predeterminado), `product`, `location` o `look`.
`target_frame`	boolean	Antes del render, el primer fotograma del clip se redibuja con el cambio ya aplicado, con la misma pose, el mismo tamaño y la misma luz, y se envía como primera referencia, de modo que el pelo, el rostro y la ropa se mantengan fieles a tus imágenes. Activado por defecto para `nemesis`, desactivado para `nemesis-lite`. Gratis.
`guide`	string	`nemesis-lite` solo (`nemesis` siempre edita el propio clip). `clip` (predeterminado con un fotograma objetivo): sigue la propia imagen del clip. `people` (predeterminado sin uno): se reemplazan las personas y se conserva el fondo. `scene`: todo lo que se ve proviene de las referencias y del prompt.
`sound`	string	`original` (activado por defecto en `nemesis`): se vuelve a poner el sonido original del clip. `none` (predeterminado en `nemesis-lite`): sin sonido.
`face_mesh`	boolean	`nemesis-lite` solo. Sigue cada rostro del clip para que el nuevo rostro conserve sus expresiones, ojos y labios. Activado por defecto con `guide: "people"`, desactivado para `scene` y `clip`. Envía `false` para dejarlo desactivado. Nunca se muestra en el resultado.
`resolution`	string	`480p`, `720p` (predeterminado) o `1080p`.
`prompt`	string	Indicaciones opcionales, hasta 5000 caracteres.

En nemesis-lite, un clip sin nadie, enviado con guide: "people", se rechaza con invalid_input y no se cobra; envíalo con scene o clip.

Cuánto tarda. Primero se prepara el clip: en nemesis se dibuja el fotograma objetivo, unos 15–40 segundos; en nemesis-lite se separa la voz y cada fotograma se convierte en la guía de profundidad, unos 25 segundos para un clip de 8 segundos y minuto y medio para uno de 30. Luego se renderiza el vídeo, que es la mayor parte de la espera: un clip de 8 segundos a 480p tarda unos 4–7 minutos. Consulta la generación hasta que termine.

Nemesis Lite

nemesis-lite admite la misma entrada que nemesis y lo renderiza con Wan 3.0: más barato, algo menos fiel en rostros y detalles finos. El clip dura 2–15 s. Se cobra a la tarifa de Wan 3.0 más $0.02 por segundo ($0.07, $0.11 y $0.19 a 480p, 720p y 1080p), por cada segundo del clip de entrada más el vídeo de salida.

Objeto de generación

Campo	Tipo	Descripción
`id`	string	Id de la generación (`gen_…`), que se usa para consultar.
`object`	string	Siempre `generation`.
`model`	string	El modelo que pediste.
`status`	string	Consulta los estados.
`message`	string	Solo mientras se confirma un resultado con un proveedor: qué está ocurriendo.
`quoted_usd`	number	El precio de la ruta más barata, que es la que se prueba primero. Si no puede generarlo y lo hace una ruta de respaldo más cara, el cargo es el precio de esa ruta, hasta `reserved_usd`.
`reserved_usd`	number	Lo que se retiene de tu saldo: lo máximo que puede costar esta generación, si una ruta de respaldo más cara la completa tras probar otras rutas. La diferencia se libera al liquidarse. Para no pagar nunca más de `quoted_usd`, establece `max_cost_usd` en ese valor: las rutas de respaldo más caras se omiten.
`output`	object \| null	Cuando está en succeeded: `urls`, los archivos del resultado (un modelo de imágenes puede devolver varios), con `width` y `height`; el vídeo también tiene `duration_s` y `has_audio`. Descárgalos pronto; los archivos caducan.
`cost_usd`	number \| null	Lo que se cobró. Se establece cuando la generación se completa; `0` cuando falla.
`attempts`	number	Rutas probadas, incluidos los respaldos. Solo se factura la que tuvo éxito.
`error`	object \| null	Cuando está en failed: `code`, `message` y `retryable`; un rechazo de contenido también tiene `reason`. Consulta por qué falló una generación.
`created_at`, `completed_at`	string	Marcas de tiempo ISO 8601.

Estados

Estado	Significado
`queued`	Aceptada, esperando una ruta.
`running`	Generando. Si una ruta falla, el trabajo sigue en `running` mientras pasa a la siguiente, y mientras se confirma un resultado (consulta `message`).
`succeeded`	Hecho. `output.urls` contiene los archivos y `cost_usd` lo que pagaste.
`failed`	Todas las rutas fallaron o se rechazó la entrada. No se cobra nada.

Facturación

Pagas con créditos prepago, 100 por dólar, que se compran en paquetes de $10 a $5,000. Cada precio es un número entero de créditos.
Al enviar, se retiene reserved_usd de tu saldo. Si la generación falla, se libera todo.
Solo se te cobra cuando la generación se completa, al precio cotizado de la ruta que la generó. Normalmente es la primera ruta, a quoted_usd. Cuando tiene que generarla un respaldo, puede costar más: el precio de esa ruta o, si una ruta probada antes fue facturada por su proveedor, lo que costaron esos intentos más un 10 %, lo que sea mayor. Nunca por encima de reserved_usd.
No hay cuota mensual ni límite por minuto: tu saldo y max_cost_usd son el límite.
El precio de cada modelo está en su página y en la tabla de precios.

Saldo

GEThttps://api.revana.si/v1/balance

La cuenta a la que pertenece tu clave. Compruébala antes de un lote grande; no cuesta nada y no cuenta para los límites de generación.

Campo	Significado
`available_usd`	Lo que puede reservar una nueva generación. Un envío cuyo `reserved_usd` sea mayor recibe `402 insufficient_credits`.
`held_usd`	Reservado por generaciones aún en curso. Lo que no usen vuelve cuando se liquiden.
`balance_usd`	Disponible más retenido.
`spent_usd`	Cobrado por generaciones terminadas, en total.
`*_credits`	Los mismos importes en créditos (100 por dólar), redondeados para que el disponible nunca aparezca mayor de lo que es.

Subir un archivo de referencia

POSThttps://api.revana.si/v1/uploads

Las referencias se pasan como enlaces https:// públicos. Para un archivo de tu propio equipo, pide un enlace de subida, envía allí los bytes y usa el enlace que recibes. Es gratis.

Campo	Significado
`upload_url`	Envía el archivo aquí con `PUT` en el plazo de una hora, con exactamente los encabezados de `upload_headers` (su tipo y tamaño). Cualquier otra cosa se rechaza.
`url`	El enlace del archivo en `api.revana.si`, válido hasta `expires_at` (14 días). No necesita clave y redirige al archivo, así que cualquier cosa que pueda abrir un enlace puede leerlo. Úsalo como referencia en `POST /v1/generations`. El archivo se elimina poco después.
`id`	`upl_…`

Imágenes (image/*) de hasta 30 MB, clips (video/*) de hasta 50 MB, sonido (audio/*) de hasta 15 MB. Un archivo más grande o de otro tipo recibe 413 too_large o 400 invalid_request.

Por qué falló una generación

Una generación en failed tiene error.code, un message escrito para mostrarlo a quien la pidió, y retryable: true cuando volver a enviar la misma solicitud más tarde puede funcionar, false cuando hay que cambiar la solicitud en sí. Una generación fallida nunca se cobra.

Código	Reintentable	Cuándo
`content_policy`	no	El modelo rechazó el prompt o los archivos, o retuvo lo que generó. `reason` indica la regla: `sexual` (contenido NSFW o para adultos), `minors` (niños o adolescentes), `copyright` (material protegido por derechos de autor o de terceros, marcas, personajes), `real_person` (la imagen de una persona real o famosa), o `other` cuando el modelo no da ningún motivo.
`invalid_input`	no	No se pudo leer una referencia, un prompt menciona `@Image2` cuando se envió una sola imagen, o hay un valor que el modelo rechaza. El mensaje indica cuál.
`model_declined`	no	El modelo respondió con palabras en lugar de generar la imagen o el vídeo, normalmente porque el prompt pide algo que necesita y no se envió. Haz que el prompt describa el resultado en sí.
`reference_changed`	no	Un archivo de referencia cambió después de verificarse. Envíalo de nuevo.
`max_cost_exceeded`	no	La única ruta que podía ejecutarlo cuesta más de `max_cost_usd`.
`model_busy`	yes	Todas las rutas del modelo estaban al límite de capacidad. Inténtalo de nuevo en un minuto.
`model_unavailable`	yes	Ninguna ruta del modelo pudo aceptar el trabajo en este momento.
`timeout`	yes	Ninguna ruta devolvió un resultado a tiempo, o pasó `max_wait_s`.
`all_routes_failed`	yes	Todas las rutas fallaron por motivos de su lado.

Errores

Los errores usan códigos de estado HTTP y un cuerpo JSON: {"error": {"code": "...", "message": "..."}}.

HTTP	Código	Cuándo
400	`invalid_request`	El cuerpo no es JSON, le falta `model` o `input`, o contiene un campo que la API no conoce.
401	`unauthorized`	Falta la clave de API o no es válida.
402	`insufficient_credits`	Tu saldo disponible no cubre `reserved_usd`. Recarga y reintenta.
403	`account_disabled`	La cuenta está en pausa. Contacta con soporte.
403	`generation_not_enabled`	Tu clave puede consultar precios pero aún no puede generar.
404	`not_found`	No hay ninguna generación con este id en tu cuenta.
409	`idempotency_conflict`	Este `Idempotency-Key` ya se usó con un cuerpo distinto.
409	`not_ready`	Se pidió el archivo antes de que la generación se completara.
413	`body_too_large`	El cuerpo supera 1 MB. Envía los medios como URL.
422	`invalid_input`	Un campo, valor o combinación que el modelo no admite, o medios que no se pueden leer. No se cobra nada.
422	`max_cost_exceeded`	Todas las rutas cuestan más de `max_cost_usd`.
422	`model_not_available`	No hay ningún modelo con este id en la API. Los ids están en la página de modelos.
429	`rate_limited`	Demasiadas solicitudes en el mismo segundo desde una cuenta (una protección contra bucles descontrolados, no una cuota). Espera los `Retry-After` segundos.
429	`concurrency_limit`	La cuenta ya tiene el máximo de generaciones en curso. Reintenta cuando termine una.
503	`busy`	Un momento de carga. Reintenta después de `Retry-After` con el mismo `Idempotency-Key`.
503	`model_unavailable`	Ninguna ruta de este modelo está disponible ahora mismo. Reintenta en breve.
500	`server_error`	Algo falló por nuestra parte. Es seguro reintentar con el mismo `Idempotency-Key`.

Lista de modelos

Cada modelo, sus opciones y sus precios se publican como JSON en /data/models.json, el mismo archivo a partir del cual se genera este sitio.