Inicio rápido
One key, one request shape, every image and video model. Submit a job, poll it, get the file. Your inputs and outputs are never shared or used for training: Privacy.
/data/models.json.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
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 | A model id from the models page, e.g. seedance-2.5, or seedance-2.5-fast for faster renders on dedicated compute, built for batches. |
input | object, obligatorio | El prompt y los ajustes; consulta los campos de entrada. Los campos desconocidos se rechazan. |
task | string, optional | On video models, what to do with input.video_url: video_edit or video_extend. See edit or extend a video. Leave it out and each model works as it always has. |
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. Si una generación falló, envíala otra vez con una clave nueva: la clave anterior sigue devolviendo la generación fallida. |
Consulta el precio primero
Envía el mismo cuerpo que al enviar una generación para ver cuánto costará: quoted_usd, reserved_usd (lo máximo que puede costar), estimated_seconds y, para tu clave, available_usd y enough_credit. No se crea ni se retiene nada, y es gratis. Algunas entradas cuestan más que la tarifa publicada de un modelo (Seedance 2.5 con un primer fotograma), así que cotiza la solicitud exacta y pasa la cotización como max_cost_usd.
Obtener el resultado
¿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) | A clip to transform, extend or upscale. Its length is measured and, on per-second models, billed. Name what to do with it in task. |
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. |
num_images | integer | Picture models: how many pictures to make (also accepted as n), from 1 (the default) up to the model’s options.max_images, usually 4. The price and the hold are per picture; you are charged only for the pictures delivered and the rest is released. output.urls lists them all. |
Edit or extend a video
Send the clip as input.video_url, what to change as input.prompt, and name the task at the top level. The same body works on every model that does it; only the routes that do that task are used.
task | What happens | Modelos |
|---|---|---|
video_edit | The clip is changed by the prompt and keeps its length (leave out duration). | seedance-2.5, wan-2.7-videoedit, wan-2.7, happyhorse-1.0, kling-3.0-omni, kling-4.0, wan-3.0 |
video_extend | The clip is continued; send duration for the new part. Priced per second like any clip of the model. | pixverse-v6 |
A model that cannot do the task answers 422 invalid_input and names the models that can. Without task, a clip does what that model does with it by default.
For example: {"model": "wan-2.7-videoedit", "task": "video_edit", "input": {"video_url": "https://example.com/clip.mp4", "prompt": "Make it a snowy night"}}
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.06, $0.09 y $0.16 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_usdde 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 dereserved_usd. - No hay cuota mensual ni límite por minuto: tu saldo y
max_cost_usdson el límite. - El precio de cada modelo está en su página y en la tabla de precios.
Saldo
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
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. |
processing_failed | yes | Nemesis no pudo preparar el clip, así que no se envió nada a ningún modelo. Envíalo otra vez. |
Errores
Los errores usan códigos de estado HTTP y un cuerpo JSON: {"error": {"code": "...", "message": "...", "request_id": "req_..."}}. Cada respuesta lleva una cabecera X-Request-Id; inclúyela cuando pidas ayuda. Cada 429 y 503 lleva Retry-After en segundos.
| 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. |
| 403 | card_required | El crédito gratuito de la cuenta necesita primero una tarjeta guardada. Añade una en el panel y vuelve a intentarlo. |
| 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.
The API lists the same models at GET https://api.revana.si/v1/models. Called with your key, every price in it is your account’s own. Each image and video model has, beside id, name, kind, tasks, options and price:
| Campo | Significado |
|---|---|
route_prices | For each price key (the keys of price.usd, or *), the price on Route 1, 2, … in the order they are tried, as [usd, fee_usd] per price.unit. Route 1 is the list price. A backup route is only used when the ones before it fail, and costs its own price, never less than the list price. |
options.qualities | The quality tiers you can send as input.quality, when the model has them; options.default_quality is the one used when you send none. |
capabilities | Flags for building a UI: edit (changes a picture or clip you give it), image_input, video_input, audio_input, audio_output, first_last_frame, reference_images, upscale. |
Signed webhooks
Completion webhooks (the queue API’s fal_webhook) are signed with a secret only your account has. Every delivery carries:
Revana-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256>, the HMAC of the timestamp, a dot and the raw request body, keyed with your secret.Revana-Webhook-Id: wh_<request id>, the same on every retry of one delivery, so you can drop repeats.
Your account’s signing secret. It stays the same: fetch it once and keep it with your API key.
To verify a delivery, compute the HMAC over the body exactly as it arrived (before parsing it), compare it in constant time, and refuse a timestamp more than five minutes old: