Documentación

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.

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 basehttps://api.revana.si/v1
AutenticaciónAuthorization: Bearer <key>
EnviarPOST /v1/generations
ConsultarGET /v1/generations/{id}
ModelosGET /v1/models (sin clave): todos los modelos con los que puedes generar ahora mismo
SaldoGET /v1/balance: lo que puede gastar la cuenta de tu clave
SubirPOST /v1/uploads: un enlace para un archivo de referencia de tu ordenador
FormatoJSON 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.

CampoTipoDescripción
modelstring, obligatorioA 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.
inputobject, obligatorioEl prompt y los ajustes; consulta los campos de entrada. Los campos desconocidos se rechazan.
taskstring, optionalOn 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_usdnumber, opcionalLo 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_sinteger, opcionalSe 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-Keyheader, opcionalHasta 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

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

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

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.

CampoTipoSe usa para
promptstringQué generar. Obligatorio para texto a imagen y texto a vídeo.
image_urlstring (URL)Fotograma inicial para imagen a vídeo, o la imagen que se va a editar para imagen a imagen.
end_image_urlstring (URL)Último fotograma, para modelos con primer y último fotograma.
image_urlsstring[]Imágenes de referencia, hasta el límite del modelo.
resolutionstring720p, 1080p, 2K... una de las resoluciones del modelo.
durationnumberDuración del vídeo en segundos, una de las duraciones del modelo.
aspect_ratiostring16:9, 9:16, 1:1...
audiobooleanGenera sonido junto con el vídeo, en los modelos que lo admiten. Puede cambiar el precio.
negative_promptstringQué evitar, en los modelos que lo admiten.
video_urlstring (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_urlstring (URL)La voz o el sonido al que anima un modelo de avatar parlante o de sincronización labial.
qualitystringUn nivel de calidad en los modelos con precio por nivel (p. ej., low, medium, high).
seedintegerUna semilla (seed), en los modelos que la admiten.
num_imagesintegerPicture 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.

taskWhat happensModelos
video_editThe 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_extendThe 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:

CampoTipoSe usa para
video_urlstring (URL)Un clip de 4–30 s para editar. El resultado conserva su duración, así que omite duration.
video_urlsstring[]Clips de referencia, hasta 10 y 30 segundos en total. Sus segundos se facturan a la tarifa de vídeo de entrada.
audio_urlsstring[]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.

CampoTipoSe usa para
video_urlstring (URL), obligatorioEl clip de 4–30 s que se va a reconstruir.
image_urlsstring[], obligatorio1–8 imágenes de referencia.
rolesstring[]Una por imagen: person (predeterminado), product, location o look.
target_framebooleanAntes 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.
guidestringnemesis-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.
soundstringoriginal (activado por defecto en nemesis): se vuelve a poner el sonido original del clip. none (predeterminado en nemesis-lite): sin sonido.
face_meshbooleannemesis-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.
resolutionstring480p, 720p (predeterminado) o 1080p.
promptstringIndicaciones 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

CampoTipoDescripción
idstringId de la generación (gen_…), que se usa para consultar.
objectstringSiempre generation.
modelstringEl modelo que pediste.
statusstringConsulta los estados.
messagestringSolo mientras se confirma un resultado con un proveedor: qué está ocurriendo.
quoted_usdnumberEl 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_usdnumberLo 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.
outputobject | nullCuando 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_usdnumber | nullLo que se cobró. Se establece cuando la generación se completa; 0 cuando falla.
attemptsnumberRutas probadas, incluidos los respaldos. Solo se factura la que tuvo éxito.
errorobject | nullCuando 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_atstringMarcas de tiempo ISO 8601.

Estados

EstadoSignificado
queuedAceptada, esperando una ruta.
runningGenerando. Si una ruta falla, el trabajo sigue en running mientras pasa a la siguiente, y mientras se confirma un resultado (consulta message).
succeededHecho. output.urls contiene los archivos y cost_usd lo que pagaste.
failedTodas 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.

CampoSignificado
available_usdLo que puede reservar una nueva generación. Un envío cuyo reserved_usd sea mayor recibe 402 insufficient_credits.
held_usdReservado por generaciones aún en curso. Lo que no usen vuelve cuando se liquiden.
balance_usdDisponible más retenido.
spent_usdCobrado por generaciones terminadas, en total.
*_creditsLos 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.

CampoSignificado
upload_urlEnví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.
urlEl 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.
idupl_…

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ódigoReintentableCuándo
content_policynoEl 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_inputnoNo 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_declinednoEl 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_changednoUn archivo de referencia cambió después de verificarse. Envíalo de nuevo.
max_cost_exceedednoLa única ruta que podía ejecutarlo cuesta más de max_cost_usd.
model_busyyesTodas las rutas del modelo estaban al límite de capacidad. Inténtalo de nuevo en un minuto.
model_unavailableyesNinguna ruta del modelo pudo aceptar el trabajo en este momento.
timeoutyesNinguna ruta devolvió un resultado a tiempo, o pasó max_wait_s.
all_routes_failedyesTodas las rutas fallaron por motivos de su lado.
processing_failedyesNemesis 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.

HTTPCódigoCuándo
400invalid_requestEl cuerpo no es JSON, le falta model o input, o contiene un campo que la API no conoce.
401unauthorizedFalta la clave de API o no es válida.
402insufficient_creditsTu saldo disponible no cubre reserved_usd. Recarga y reintenta.
403account_disabledLa cuenta está en pausa. Contacta con soporte.
403generation_not_enabledTu clave puede consultar precios pero aún no puede generar.
403card_requiredEl crédito gratuito de la cuenta necesita primero una tarjeta guardada. Añade una en el panel y vuelve a intentarlo.
404not_foundNo hay ninguna generación con este id en tu cuenta.
409idempotency_conflictEste Idempotency-Key ya se usó con un cuerpo distinto.
409not_readySe pidió el archivo antes de que la generación se completara.
413body_too_largeEl cuerpo supera 1 MB. Envía los medios como URL.
422invalid_inputUn campo, valor o combinación que el modelo no admite, o medios que no se pueden leer. No se cobra nada.
422max_cost_exceededTodas las rutas cuestan más de max_cost_usd.
422model_not_availableNo hay ningún modelo con este id en la API. Los ids están en la página de modelos.
429rate_limitedDemasiadas solicitudes en el mismo segundo desde una cuenta (una protección contra bucles descontrolados, no una cuota). Espera los Retry-After segundos.
429concurrency_limitLa cuenta ya tiene el máximo de generaciones en curso. Reintenta cuando termine una.
503busyUn momento de carga. Reintenta después de Retry-After con el mismo Idempotency-Key.
503model_unavailableNinguna ruta de este modelo está disponible ahora mismo. Reintenta en breve.
500server_errorAlgo 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:

CampoSignificado
route_pricesFor 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.qualitiesThe quality tiers you can send as input.quality, when the model has them; options.default_quality is the one used when you send none.
capabilitiesFlags 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.
GEThttps://api.revana.si/v1/webhooks/secret

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: