Pro API: generar vídeos con sonido

Un clip a partir de un prompt, o una animación de una imagen fija que tú aportas. El archivo es un MP4, con sonido cuando lo pides.

Enviar un vídeo

POST /videos

{ "prompt": "a woman in a white linen dress walks along a beach at sunset, wind in her hair, she turns and smiles at the camera",
  "width": 1080, "height": 1920, "audio": true }

Cadencia por defecto: 30 fps. Los clips se renderizaban antes a 24 fps. Sin fps, un clip con el mismo length es por tanto más corto que antes (241 fotogramas: 8 s en lugar de 10 s). Envía "fps": 24 para mantener el comportamiento anterior.

La respuesta:

{ "jobId": "...", "seed": 908172, "cost": 30 }

El coste se calcula y se anuncia al enviar la solicitud, antes de cargar nada. La seed también se devuelve, tanto si la has indicado tú como si se ha generado aleatoriamente.

Formatos y precio

Un vídeo tiene un precio por formato, como tarifa plana independiente de su duración. Base: 5 créditos.

La tarifa plana se multiplica por 2 a 720p y por 3 a 1080p, y el sonido duplica el precio. Los factores se aplican sobre la tarifa base, no entre sí: 1080p con sonido cuesta 5 x 3 x 2 = 30 créditos. Hasta 481 fotogramas, es decir 20 s a 24 fps, la duración no cambia nada (5 s o 20 s, misma tarifa). Más allá de 481 fotogramas (hasta 721, solo con consistency enhanced, duración fija), el precio del formato se duplica. La cadencia (fps) no cambia el precio, pero los tramos cuentan fotogramas: a 30 fps, el precio normal llega hasta 16 s; a 60, hasta 8 s (12 s al doble del precio en enhanced).

Una excepción: en Calidad, 480p sin sonido cuesta 2 créditos, sea cual sea su duración (desde el 11 de octubre de 2026). Multi-Ref y la coherencia reforzada mantienen la tarifa plana del formato, 5 créditos.

El tamaño que recibes. El motor trabaja en múltiplos de 32 y en dos etapas, por lo que el archivo sale a 768 x 1280 (o 1280 x 768) para 720p y 1088 x 1920 (o 1920 x 1088) para 1080p. El 480p se mantiene en 480 x 832 (o 832 x 480), excepto en coherencia reforzada. Útil saberlo si vas a unir o superponer nuestros renders.

El modo turbo fue retirado el 11 de octubre de 2026: una solicitud turbo se renderiza en Calidad 480p y se factura como tal (2 créditos sin sonido, 10 con sonido).

Conocer el precio antes de enviar

POST /videos/quote acepta el mismo cuerpo que POST /videos y realiza el mismo cálculo, pero no se crea nada: ni render, ni créditos retenidos, ni cuota consumida. Úsalo antes de comprometerte, especialmente desde un agente que trabaja con un presupuesto.

{ "cost": 30, "mode": "ltx25", "format": "1080p", "audio": true, "fps": 30, "duration_auto": true,
  "seconds_max": 16, "detail": "flat 5 x 3 (1080p) x 2 (sound) = 30" }

detail desglosa la cifra; fps es la cadencia utilizada y seconds_max la duración máxima en segundos a esa cadencia. Con "consistency": "enhanced", el presupuesto acepta una duración fija de hasta 721 fotogramas y aplica la tarifa por encima de 481 fotogramas (x 2 (over 20 s) en detail a 24 fps, x 2 (over 481 frames) a otra cadencia). La misma ruta existe para imágenes, POST /images/quote, que siempre responde { "cost": 1, ... }: una imagen siempre cuesta 1 crédito.

Para un clip Ultra facturado por segundo, el presupuesto da la duración facturada en seconds, y detail desglosa el precio por segundo.

Consultar, descargar, cancelar

Las mismas rutas que para las imágenes, bajo /videos.

• GET /videos/{jobId}: pending / completed / failed, mismos campos. Una extensión reforzada puede terminar como failed con "error": "extension_not_applied" (el motor no tomó el final del clip anterior): no se cobra nada, vuelve a enviarla.
• GET /videos/{jobId}/file: el MP4 (Content-Type: video/mp4).
• POST /videos/{jobId}/cancel: cancela y no se cobra nada.

En Ultra facturado por segundo, un render que ya se está calculando ya no se detiene: la cancelación responde 409 render_in_progress, y el clip se entrega y se factura. Un clip que el motor rechaza a la salida termina en failed, con una frase en detail y el código del motor en reason: no se cobra nada.

Un vídeo tarda entre 1 y 5 minutos, más cuando el motor arranca en frío. Consulta el estado cada 3 segundos y descarga en cuanto el estado sea completed: el archivo no se archiva.

Varios planos en un mismo clip

Un único prompt puede contener varios planos con cortes directos, hasta 20 segundos en total a 24 fps (16 s a 30, la cadencia por defecto). Descríbelos en orden: Shot 1: <encuadre>, <acción>. Cut to Shot 2: .... Repite en cada plano lo que debe mantenerse igual (personaje, ropa, lugar, luz) y termina con una línea de ambiente compartido.

Omite los códigos de tiempo: deja duration_auto activado y el motor elige la duración (hasta 20 s a 24 fps, 16 s a 30) y dónde cortar. De dos a cuatro planos por clip es lo que mejor funciona.

A cinematic sequence of three shots, same woman, same place, same lighting throughout.
Shot 1: Wide shot, night, light rain on a narrow Paris street with glowing café windows. A woman in a long beige trench coat walks toward the camera under a transparent umbrella, wet cobblestones reflecting warm yellow streetlights.
Cut to Shot 2: Close-up on her face under the umbrella, raindrops on the plastic, warm café light on her cheek, she smiles softly.
Cut to Shot 3: Medium shot from inside the café through the rainy window, she pushes the door open and steps in, warm light spilling onto the wet pavement.
Calm, melancholic, romantic mood.

¿Varios planos en un clip o una secuencia? Cada opción hace cosas distintas:

Extender un clip

Un clip puede extenderse: el siguiente plano continúa el movimiento del anterior sin pausa en la unión. Está guiado aproximadamente por el último segundo del clip anterior, no por un fotograma fijo. Añade a POST /videos:

El plano extendido mantiene la resolución del clip anterior: width y height se ignoran con extend_job_id, y con extend_video el tamaño se lee del archivo que envías. Contiene solo los fotogramas nuevos, de modo que los planos unidos forman un vídeo continuo. Mantiene la cadencia del clip anterior: omite fps (la toma del clip anterior) o indica la misma; una distinta se rechaza (extend_fps_mismatch). length es la nueva duración del plano (121 = 5 s más a 24 fps) y es exacta: la duración automática no se aplica a una extensión. Una extensión cuesta el precio de un clip.

Limitaciones: no se puede usar fotograma final ni imágenes clave al mismo tiempo, excepto con coherencia reforzada.

El sonido continúa en la unión. Con audio: true, cuando el final del clip anterior tiene pista de sonido, el nuevo plano retoma ese sonido en lugar de generar uno nuevo. Con extend_job_id, el final cortado conserva el sonido del clip; con extend_video, envía el final con su sonido. Sin pista de sonido en ese final, en coherencia reforzada y en Ultra, el sonido empieza de nuevo con el plano: mantén el mismo ambiente en cada prompt para que la unión se note lo menos posible.

Extiende un clip poco después de que termine. Más tarde ya no estará disponible para nosotros (clip_unavailable) y deberás enviar su final tú mismo en extend_video.

Extender un plano Ultra, hacia delante o hacia atrás

Un plano renderizado en Ultra por segundo también se extiende en Ultra, hacia delante o hacia atrás; cualquier otro clip se extiende como se indica arriba. Envía POST /videos con "quality": "max" y:

• El render contiene solo la parte nueva, con la duración de un clip Ultra (length / fps, 5 s con la duración automática). Toma la resolución del plano (width y height se ignoran) y enlaza con su último fotograma (forward) o con el primero (backward).
• Sin imagen de inicio, referencias (multiref), movimiento ni coherencia reforzada. backward no entra en una secuencia, que coloca sus planos uno tras otro.
• Precio: la parte nueva al precio de Ultra por segundo, más, por cada segundo del plano extendido, 2 créditos en 480p, 5 en 720p y 13 en 1080p (ultra.extend_per_second en GET /pricing). Esos segundos se redondean al segundo superior (con una precisión de 0,1 s) y se cuentan a 24 fotogramas por segundo: un plano con más fotogramas por segundo cuenta a prorrata (2 s a 60 fps cuentan como 5 s). POST /videos/quote con los mismos campos da extend_seconds y el precio exacto.
• Un plano de más de 24 horas: sube su archivo original, tal como lo entregó GET /videos/{jobId}/file. POST /extensions con { "size": <bytes> } devuelve upload_id, upload_url, headers y expires_in (900 s); envía el archivo con PUT upload_url y exactamente esos headers, y luego pasa extend_upload_id en un plazo de 2 horas. Una subida sirve para un render: un MP4 de 4 a 30 s, 60 MB y 1080p como máximo. Antes del render, cada vídeo enviado al modo Ultra (un movimiento o un vídeo que prolongar) se comprueba, y no se cobra nada si se rechaza (400 input_video_out_of_limits): de 24 a 60 imágenes por segundo, una relación ancho/alto de 0,4 a 2,5 y, por render, 30 s y 10 archivos como máximo para los vídeos y los sonidos de referencia en conjunto. Con un rostro realista, un archivo recodificado o editado se rechaza (400 engine_refused): solo pasa el original. Un vídeo que no se renderizó en modo Ultra (el render de otro modo, por ejemplo) no se prolonga en Ultra si muestra un rostro realista (400 extension_real_face, no se cobra nada): prolóngalo en modo Calidad, o vuelve a hacer el plano en Ultra.

Coherencia reforzada

Con "consistency": "enhanced", el clip se renderiza por un canal que mantiene el movimiento, las caras y el fondo más estables a lo largo del tiempo. Llega hasta 721 fotogramas por plano, es decir 30 s a 24 fps y 24 s a 30 (length, duración fija), y está pensado principalmente para vídeos largos:

• Primer plano: un clip normal (prompt, fotograma inicial, keyframes, end_image), hasta 721 fotogramas.
• Extensión: extend_job_id (o extend_video) como en Extender un clip, con la misma consistency. length sigue siendo la nueva duración (hasta 721, es decir 30 s más a 24 fps). Una extensión reforzada también admite keyframes, cuyo at cuenta desde el primer fotograma nuevo, y un fotograma final end_image colocado en el último fotograma del plano: por ejemplo el fotograma inicial del primer plano, para que un vídeo largo forme un bucle.

Solo en modo Calidad (mode ltx25, sin quality: "max"), hasta 1080p, no disponible en Multi-Ref (400 consistency_mode). Precio: la tarifa plana del formato (480p sin sonido: 5 créditos) hasta 481 fotogramas nuevos (20 s a 24 fps), duplicada a partir de ahí (consulta la tabla de precios anterior). Cadencias: 24, 30, 50 o 60. Por encima de 30, la duración es fija (fps_requires_fixed_duration en caso contrario); 50 da una ligera cámara lenta (consulta fps). El render tarda más que un clip estándar y su inicio puede esperar a una tarjeta gráfica más potente (planos largos). Una secuencia mantiene la misma consistency en todos sus planos. Tamaño entregado: igual que en Calidad a 720p y 1080p; a 480p, el lado corto sale en 448 (448 x 832, 832 x 448, 448 x 448), ya que este canal trabaja en múltiplos de 64.

Algunos prompts aún no son compatibles. Para ellos, un plano único de 20 s o menos (15 s con end_image, a duración fija) se renderiza con coherencia estándar, al mismo precio. Más allá de eso (length superior a 481 con duration_auto: false, o superior a 361 con end_image), en una extensión o en una secuencia, la solicitud se rechaza con 400 consistency_explicit: acorta el plano o pide consistency: "standard".

Vídeo largo (secuencias)

Un clip dura como máximo 481 fotogramas, es decir 20 s a 24 fps (721 con coherencia reforzada, 30 s a 24 fps). Para duraciones mayores, una secuencia registra cada plano a medida que termina su render y los une en un único MP4 sin recodificar. Un minuto, por ejemplo, son 3 planos de 20 s, o 2 planos de 30 s en coherencia reforzada, a 24 fps.

1. POST /sequences abre una secuencia y responde { "sequence_id": "seq_...", ... }.
2. POST /videos con "sequence_id": "seq_..." para cada plano: el primero como de costumbre, los siguientes con extend_job_id apuntando al plano anterior. Cada plano se registra en la secuencia, en orden de envío, en cuanto GET /videos/{jobId} lo ve terminado.
3. POST /sequences/{id}/export una vez terminado el último plano. Responde con seconds, resolution y file_url.
4. GET /sequences/{id}/file: el vídeo ensamblado (MP4).

Además: GET /sequences/{id} indica el estado (planos registrados o pendientes), POST /sequences/{id}/clips con { "job_id": "..." } registra un render a mano, y DELETE /sequences/{id} elimina la secuencia de inmediato.

Reglas. Todos los planos tienen la misma resolución (las extensiones la conservan) y la misma elección de sonido, todos con sonido o todos sin él, la misma consistency y la misma cadencia (fps): el primer plano las establece, y un plano que difiere se rechaza (409 consistency_mismatch, 409 sequence_fps_mismatch; 422 encoding_mismatch para un plano registrado a mano). Un plano sin fps toma la cadencia de la secuencia. Como máximo 30 planos por secuencia y 5 secuencias en curso por licencia.

Qué conservamos y durante cuánto tiempo. Los planos de una secuencia en curso se borran 30 minutos después de que se añadiera el último, y el vídeo ensamblado 24 horas después de la exportación. Después, todo desaparece.

Exportar la carpeta del proyecto

Una carpeta de proyecto reúne en un ZIP todo lo necesario para retomar un vídeo en otro lugar o automatizarlo: los planos, sus referencias, el montaje y un manifiesto que permite volver a renderizar cada plano. Es gratuita: no se renderiza nada.

• POST /videos/{jobId}/export: un render de POST /videos (plano suelto, Multi-Ref, extensión).
• POST /sequences/{id}/project: todos los planos de una secuencia, uno tras otro.
• Cuerpo opcional, las mismas opciones que la ventana de exportación de la app:
  • include_media (true por defecto): los vídeos de los planos y sus originales firmados. false: ningún vídeo (ni clip, ni original, ni película); los planos conservan su texto, sus ajustes y sus referencias ("state": "expired") y el manifiesto lleva videos_included: false.
  • include_references (true por defecto): las vistas de los personajes y las imágenes de los elementos, en references/. false: no se copia ninguna; sus nombres, @menciones, id y huellas quedan en el manifiesto (references_included: false).
  • exclude_references: las referencias que no se copian, una a una, por id (character_id, subject_id), nombre o @mención, por ejemplo ["@Parc", "chr_..."] (200 como máximo). El manifiesto lleva references_included: "partial" y "included": false en cada excluida (false si lo están todas). Una entrada que no designa ninguna referencia de la exportación: 400 unknown_reference.
  • include_film (solo secuencia, false por defecto): la película de una secuencia ya ensamblada; requiere include_media (si no, 400 invalid_export_options, como una opción que no es booleana o un exclude_references que no es una lista de textos).
  • manifest_only: true: solo el manifiesto, sin ZIP.

La respuesta es { "manifest": { ... }, "file_url": "...", "export_id": "exp_...", "expires_at": "...", "bytes": n }, y GET /exports/{id}/file descarga el ZIP. Una exportación a la vez por licencia (409 export_in_progress), 2 GB como máximo (413 export_too_large: exporta los planos uno a uno).

Qué conservamos y durante cuánto tiempo. Por cada POST /videos aceptado, el servidor guarda una ficha del render sin ninguna imagen ni vídeo: el texto, los ajustes, los identificadores (una imagen enviada en base64 solo deja su huella). Se borra 24 horas después del envío; pasado ese plazo, la exportación responde 404 unknown_export. El ZIP se borra 45 minutos después de su primera descarga, 2 horas después de su creación como máximo. Un plano que el servidor ya no tiene sale con "state": "expired", sin su archivo pero con su texto, sus ajustes y sus referencias: un agente puede volver a renderizarlo con api_request.

Secuencia. El ensamblaje borra los planos uno a uno. Para tener los planos y la película, exporta el proyecto antes de ensamblar, luego ensambla y vuelve a exportar con { "include_film": true }: la película se añade, y los planos salen entonces como expired.

Modo Ultra

El modo Ultra es el render de vídeo más fino. Añade "quality": "max" a POST /videos (con mode ltx25, el valor por defecto). Se factura por segundo, o a precio fijo con un LoRA o en una extensión de un clip que no se renderizó por segundo; extender un plano Ultra, hacia delante o hacia atrás, se factura por segundo. POST /videos/quote da el precio exacto de tu solicitud.

Por segundo

El clip se factura por segundo según su resolución, sonido incluido:

• Duración: de 4 a 30 s a 24 fotogramas por segundo, conocida antes del render: 5 s con la duración automática (duration_auto, por defecto), si no length / fps (24 si falta fps), redondeada al segundo.
• Formato: el solicitado, en la proporción más cercana; el 480p se renderiza en 480p. Por encima de 1080p: resolution_outside_ultra.
• Imagen inicial (image): posible. El motor puede rechazar un texto o una imagen al enviarlos: 400 engine_refused, con su motivo en detail y su código en code; no se cobra nada.
• Sin semilla: seed se ignora y la respuesta no la incluye.
• Cancelación: libre mientras el render espera su turno; una vez en cálculo, 409 render_in_progress, y el clip se entrega y se factura.
• Sin imagen final, sin imágenes clave y sin coherencia reforzada en Ultra.

A precio fijo

Con un LoRA o en una extensión de un clip que no se renderizó por segundo, Ultra se renderiza con el modelo de vídeo completo, a precio fijo:

El precio es fijo por formato: el sonido y la duración no cambian nada. Ultra empieza en 720p: una solicitud 480p se renderiza y se factura en 720p. POST /videos/quote da el precio exacto. 1080p (1920 x 1088) es el máximo, en todos los modos: el 4K ya no se ofrece. Un tamaño mayor se rechaza (ultra_4k_unavailable con quality: "max", resolution_above_quality sin él).

• Duración: 481 fotogramas como máximo, como cualquier clip (20 s a 24 fps, 16 s a 30, 8 s a 60). Las extensiones y los vídeos largos también funcionan en Ultra. Una extensión conserva el tamaño del clip que continúa y, por debajo de 720p, se factura al precio de 720p.
• Tiempo: varios minutos para un clip de 5 s, más para un clip de 20 s. El inicio puede esperar a que una tarjeta gráfica potente quede libre.
• Sin transición (end_image) en Ultra (ultra_incompatible).
• Sin imágenes clave (keyframes) en Ultra (keyframes_mode).
• Un LoRA de personaje de tu cuenta se aplica en Ultra igual que en el modo normal.

Multi-Ref Vídeo

Un clip en el que juegan de 1 a 4 personajes (hasta 12 en Ultra), cada uno reconocible, en un decorado opcional, con objetos guardados, animales y un decorado guardado cuando los necesitas. Los personajes provienen de GET /characters: creados a partir de una foto mediante la API o en la app. Los objetos, animales y decorados provienen de GET /subjects. Añade el objeto multiref a POST /videos (permiso videos) y llama a cada personaje por @Nombre en el prompt:

{
  "prompt": "@Lea walks toward @Tom in a sunny kitchen and hands him a cup. Sound: footsteps, soft music.",
  "multiref": {
    "characters": [
      { "character_id": "chr_8f3a...", "name": "Lea", "description": "a 28 year old woman with long red hair" },
      { "character_id": "chr_21bc...", "name": "Tom", "description": "a 30 year old man", "strength": 1.2 }
    ],
    "background_b64": "<optional: an image of the location>",
    "background_description": "a sunny kitchen"
  },
  "width": 1088, "height": 1920,
  "audio": true
}

• Prompt en inglés, un párrafo en presente; Sound: para el sonido, líneas de diálogo entre comillas, exactly 2 people y la posición de cada uno cuando ayude, sin negaciones. Una criatura se describe por lo que es. Un @Nombre que no coincide con ningún personaje se rechaza (unknown_mention).
• Formatos (width x height): vertical 480 x 832, 720 x 1280, 1088 x 1920; horizontal 832 x 480, 1280 x 720, 1920 x 1088; cuadrado 480 x 480, 720 x 720, 1088 x 1088. Sin 4K; 480p solo en Calidad.
• Modos: Calidad (el predeterminado) o Ultra (quality: "max"). Sin extensión ni transición.
• Duración: automática (duration_auto, el valor predeterminado) o fija con duration_auto: false y length 121 (5 s), 241 (10 s) o 481 (20 s) a 24 fps; a otra cadencia, las mismas duraciones contadas en fotogramas, 481 como máximo (a 30: 145, 297, 481; a 60: 297, 481).
• Cadencia: fps 24, 30 (el predeterminado) o 60, como para cualquier clip; length cuenta fotogramas a esta cadencia, 481 como máximo (16 s a 30, 8 s a 60).
• Precio: el precio de un clip. En Calidad, la tarifa plana del formato en la tabla anterior, duplicada con sonido; 480p sin sonido se mantiene en 5 créditos (el precio reducido de Calidad no se aplica a Multi-Ref). POST /videos/quote con "multiref": true da el precio exacto.
• El servidor adapta los ángulos al formato exacto del vídeo: envía los personajes tal como están. Un personaje que tiene una sola vista se renderiza, con warnings limited_likeness en la respuesta: el parecido es limitado.
• Voces de perfil: con sonido, characters[0] y characters[1] hablan por defecto con la voz de su perfil cuando está en línea (has_voice); voice generated deja que el modelo haga una. La respuesta da la voz de cada uno en voices (character_id, voice: character, custom o generated).
• Voces de personajes (voice_b64): el modelo hace hablar al personaje con esa voz, labios incluidos; el servidor usa sus primeros 5 segundos. Dos voces como máximo, en characters[0] y characters[1] (el motor admite 2 voces). Ordena characters según el diálogo: characters[0] habla primero, characters[1] responde. Requiere sonido ("audio": true), de lo contrario voice_requires_audio; una voz en otro personaje: voice_slot; un archivo ilegible: unsupported_audio_format; más de 4 MB: audio_too_large. Solo se usan los primeros 5 segundos: envía un fragmento corto. El cuerpo total de la solicitud debe estar por debajo de 30 MB (si no, un 413 sin cuerpo JSON). Sin cargo adicional.
• La consulta, la descarga y la cancelación son las de cualquier vídeo (consulta Consultar, descargar, cancelar, más arriba).

Objetos, animales y decorados guardados. Dos campos más de multiref incorporan los sujetos guardados a partir de tus propias imágenes:

name toma por defecto la primera palabra del nombre del sujeto, y cada @Nombre en el prompt se empareja igual que el de un personaje. Un decorado pasado en subjects, o un objeto pasado como location, se rechaza (invalid_subject_type). El precio no cambia: es el precio de un clip. Un sujeto se usa con sus 5 primeras imágenes (todas en Ultra, 6 como máximo).

"multiref": {
  "characters": [{ "character_id": "chr_8f3a...", "name": "Lea" }],
  "subjects": [{ "subject_id": "sub_1c2d...", "name": "Rex" }],
  "location": { "subject_id": "sub_9e8f...", "name": "Loft" }
},
"prompt": "@Lea throws a ball to @Rex across @Loft. Sound: barking, laughter."

En Ultra, un clip Multi-Ref sigue las reglas de Ultra facturado por segundo: mismo precio por segundo, sonido incluido, de 4 a 30 s a 24 fotogramas por segundo (5 s con la duración automática), de 480p a 1080p, sin semilla.

• Cada personaje va con su character sheet (o, si no tiene, con todas sus imágenes), y el servidor lo reúne todo en una sola imagen; cada objeto, animal o decorado con todas sus imágenes (6 como máximo).
• El primer render de un personaje prepara esa imagen, unas decenas de segundos más: su jobId empieza entonces por sdp- y se sigue como los demás.
• Sin voz: voice_b64 y la voz de la ficha se ignoran (warnings voice_ignored), y strength no tiene efecto.
• El motor puede rechazar una imagen de referencia (un rostro real, por ejemplo): el render termina en failed con el motivo, y no se cobra nada.

Estilos, outfits y movimiento. Solo en Ultra (quality: "max"), tres campos más de multiref; en otro modo, la solicitud se rechaza (multiref_ultra_only), nunca se renderiza sin ellos.

• 30 imágenes como máximo en Ultra, entre personajes, sujetos, estilos, outfits y decorado (multiref_too_many_images), con 12 personajes como máximo (multiref_characters_required por encima). Se recomiendan 8: de 9 a 12, el render sale con warnings many_characters, porque algunos pueden faltar o mezclarse. Un estilo fuera de styles, o un outfit fuera de outfits, se rechaza (invalid_subject_type).
• Precio del movimiento: 3 créditos por segundo del vídeo de movimiento (redondeado al segundo superior), además del render, en GET /pricing (ultra.motion_per_second); POST /videos/quote con el mismo multiref.motion da motion_seconds y el precio exacto.
• Subida directa, para un vídeo de movimiento pesado: POST /motions con { "size": <bytes> } (20 MB como máximo) devuelve motion_id, upload_url, headers y expires_in (900 s); envía el archivo con PUT upload_url y exactamente esos headers, y luego pasa multiref.motion.motion_id a POST /videos en un plazo de 2 horas. Un motion_id sirve para un render.

"quality": "max",
"multiref": {
  "characters": [{ "character_id": "chr_8f3a...", "name": "Lea" }],
  "styles": [{ "subject_id": "sub_a1b2..." }],
  "outfits": [{ "subject_id": "sub_c3d4...", "name": "RedGown", "worn_by": "Lea" }],
  "motion": { "motion_id": "4f0c2a9b1d7e6a35", "description": "a low tracking shot from the side" }
},
"prompt": "@Lea walks along a seaside promenade at sunset."

Los códigos de error de los estilos, los outfits y el movimiento están en Límites y errores.

Con el servidor MCP, el agente hace todo esto con tendre_multiref_video: describe la escena y nombra los personajes, objetos, animales y el decorado (subjects, location_id).

Face swap

La persona filmada en tu propio vídeo se convierte en uno de tus personajes: cara, cabello, cuerpo y ropa (o solo la cabeza, ver part), conservando sus gestos, sus labios y el entorno, y su voz salvo que el personaje tenga la suya (ver voice). Es el Face swap de la app, en un pasaje de 20 s como máximo: un personaje, sin encadenamiento ni transición. La solicitud es POST /faceswap (permiso videos):

{
  "video_b64": "<the video in base64: MP4, MOV, WebM or MKV, 20 MB at most>",
  "character_id": "chr_8f3a...",
  "start": 2,
  "duration": 6,
  "scene": "@Lea wears a long red coat.",
  "zone": "normal",
  "likeness": 1
}

Vídeo y voz juntos: 22 MB como máximo, para que el cuerpo de la solicitud se mantenga por debajo de 30 MB (si no, un 413 sin cuerpo JSON).

• El servidor lo prepara todo. Recorta el pasaje, lo ajusta a la cadencia de trabajo (30 fps para una fuente a 29 fps o más, 50 y 60 incluidos, 24 por debajo) y al formato de trabajo (múltiplos de 128, lado corto de 768, la proporción más cercana a tu vídeo), y adapta las vistas del personaje a ese formato.
• Lo que recibes es el vídeo del pasaje en el formato de trabajo, de aproximadamente un megapíxel (768 x 1408 para un vídeo vertical, por ejemplo), con las proporciones de tu vídeo dentro de un 5%. La resolución completa y varios personajes seguidos son funciones exclusivas de la app de escritorio tendre.AI: pega el personaje de vuelta sobre el vídeo original a su resolución completa y encadena varios personajes.
• Precio: 6 créditos por segundo del pasaje preparado (seconds en la respuesta), redondeado al crédito siguiente. La respuesta devuelve jobId, seed, cost y el pasaje preparado (width, height, length, fps, seconds, audio, voice, views, part). Un personaje que tiene solo una vista se renderiza, con warnings limited_likeness.
• Sin presupuesto previo: ni POST /videos/quote ni tendre_quote del MCP conoce Face swap. Para calcular el precio antes de enviar, lee grid.body_swap en GET /pricing: segundos del pasaje x per_block_720p (el precio de un bloque) / block_seconds (la duración de un bloque), redondeado al crédito siguiente.
• Algunas escenas se renderizan a partir de los tres retratos del personaje recortados a la cabeza (heads_only en la respuesta) y la ropa de sus vistas ya no se impone: la escena lo decide.
• Un Face swap cuenta como un uso del personaje y retrasa su borrado, igual que Multi-Ref.
• La consulta, la descarga y la cancelación son las de cualquier vídeo (consulta Consultar, descargar, cancelar, más arriba): GET /videos/{jobId}, GET /videos/{jobId}/file, POST /videos/{jobId}/cancel.
• Errores propios: video_required, video_too_large, unreadable_video, invalid_start, passage_too_short, invalid_duration, invalid_zone, invalid_likeness, invalid_scene, invalid_description, invalid_character_name, invalid_part, invalid_voice_choice, character_required, unknown_character, audio_too_large (voz de más de 2 MB), face_swap_too_large (el pasaje sigue siendo demasiado pesado una vez preparado: acorta duration), server_busy (ya se están preparando dos vídeos: reintenta después de Retry-After, 20 s), face_swap_unavailable y face_swap_price_missing (Face swap cerrado o sin precio: reintenta más tarde). Lo que significa cada uno: Límites y errores.
• Tu vídeo pasa por nuestros servidores mientras se prepara y luego va a la tarjeta gráfica que lo renderiza, como cualquier imagen fuente.

Usa solo vídeos de personas que hayan dado su consentimiento: es una regla de los términos de uso.

Con el servidor MCP, el agente hace todo esto con tendre_face_swap.