Clipwright

API de Clipwright

Una API HTTP que convierte un guion en un video UGC con sincronización labial, o un guion o una breve descripción en un video sin rostro: narración sobre un clip animado de apertura y escenas con imágenes. Está diseñada para que la controle un agente: cada llamada es una única solicitud JSON, cada rechazo indica qué hacer a continuación y no se publica nada en ningún sitio. Cada palabra de esta página también está en un archivo Markdown en https://clipwright.io/docs.md y en un contrato breve para agentes en https://clipwright.io/llms.txt destinado a agentes que leen texto. El archivo OpenAPI 3.1 en https://api.clipwright.io/openapi.json es el contrato REST legible por máquinas, creado a partir de los esquemas que valida la API.

Autenticación

Todas las llamadas se envían a https://api.clipwright.io e incluyen la clave en un encabezado:

Authorization: Bearer cw_your_key_here

• Las claves empiezan por cw_ y se muestran una sola vez, cuando se emiten. Solo conservamos un resumen criptográfico, así que una clave perdida se sustituye, nunca se recupera.
• Emite y revoca claves en https://app.clipwright.io/api-keys desde el panel de control. La revocación surte efecto en la siguiente solicitud.
• @clipwright/cli y @clipwright/mcp-server leen la clave de la variable de entorno CLIPWRIGHT_API_KEY; @clipwright/sdk la recibe como argumento.
• Una llamada sin clave, o con una clave revocada, se rechaza con 401 antes de que se cobre nada.

03

Coste

• make_ugc a partir de un guion sin formato: 10 créditos por cada segundo de video terminado, redondeado al segundo entero superior, con un mínimo de 50 por un video entregado.
• make_ugc con segmentos o inserciones: 9 créditos por cada segundo que aparezca un rostro en pantalla (22 en una toma renderizada con OmniHuman), más 1 por cada segundo del video y 400 por cada imagen de llamada de avatar en directo, con un mínimo de 50 créditos por un video entregado. Un rostro cubierto por una inserción, superposición, ventana o plantilla sigue contando, y una ejecución que no entregue ningún archivo no cuesta nada. El tiempo de aparición de rostros se suma en todo el video y se redondea una sola vez, no por segmento. Estos campos requieren la habilitación para contenido de formato largo; si está desactivada, se rechazan por nombre antes de cualquier cobro.
• create_actor con calidad medium: 4 créditos por el retrato (ninguno si es tu propia imagen, proporcionada en portrait; 4 por una vista de un actor existente creada con from_actor_id) y 8 por cada formato adicional.
• create_actor con calidad high: 45 créditos por el retrato (ninguno si es tu propia imagen, proporcionada en portrait; 12 por una vista de un actor existente creada con from_actor_id) y 18 por cada formato adicional.
• make_faceless: 7 créditos por cada imagen que generemos, 49 por el clip de apertura y 1 por cada segundo del video entregado, con un mínimo de 50. El presupuesto para tu duration_seconds es el máximo que pagarás: 212 a los 30 segundos, 356 a los 90. Tus propias imágenes no se cobran y los subtítulos no cambian el precio.
• Los créditos se compran en paquetes: 1000 créditos por $10.00, 2750 créditos por $25.00, 6000 créditos por $50.00. Un paquete por pago, sin suscripción.

Pregunta antes de gastar: el endpoint de presupuesto de cada habilidad no cobra nada. El valor de su respuesta varía según la habilidad.

• make_ugc: el presupuesto es una estimación basada en las palabras del guion. El cobro se basa en lo que se mida en el video terminado —su duración con la tarifa para guiones sin formato, sus segundos con rostros con la tarifa para rostros—, así que el importe puede ser superior o inferior al presupuesto.
• create_actor: el presupuesto calcula el precio de todos los formatos que solicitaste, que es el máximo que puedes pagar. Se te cobra por el retrato y por las variantes que se publiquen realmente; los formatos que no se generen se indican en warnings[] y no cuestan nada.
• make_faceless: el presupuesto calcula el precio de los duration_seconds que solicitaste, que es el máximo que puedes pagar. El video dura lo que necesite la narración, con un mínimo de 25 segundos (un video explicativo, solo su narración) y, por lo general, como máximo un cuarto más que esa duración y 90 segundos; una narración más larga llega hasta el final. Se te cobra por la duración realmente entregada, nunca más que el presupuesto.

El coste de una ejecución fallida también varía según la habilidad:

• make_ugc a partir de un guion sin formato: se cobra una ejecución que haya fallado después de que se encargara el video. Si falla antes, no cuesta nada; tampoco cuesta nada si la detenemos, se pierde o la rechazamos nosotros. Con la tarifa para rostros no se cobra ningún fallo.
• create_actor: una ejecución fallida no cuesta nada, porque no recibiste ningún actor.
• make_faceless: una ejecución fallida no cuesta nada, incluso si la detenemos nosotros porque un paso no superó nuestras comprobaciones. Una ejecución retenida para revisión mantiene la retención de créditos hasta que se resuelva.

04

Precios de edición

Una revisión de un video sin rostro es una nueva ejecución creada a partir de un documento editado: POST /v1/runs/{id}/revisions/quote calcula el precio sin cobrar nada; POST /v1/runs/{id}/revisions la inicia.

• Una imagen nueva: 7 créditos.
• Un clip de apertura nuevo: 49 créditos.
• Una imagen fija de apertura nueva y su clip: 56 créditos.
• El renderizado de una revisión que genere algo: 13 créditos, una vez por revisión.
• El renderizado de una revisión que no genere nada (un cambio de ritmo, una eliminación o una carga tuya): 13 créditos.
• Una vez habilitadas las ediciones de pago, se puede editar un original por un precio durante los 364 días posteriores a su finalización.
• Revisiones de un mismo original en curso a la vez: como máximo 1. Fallidas o sin terminar: como máximo 3.
• Una revisión entregada se cobra según el total presupuestado; una que falla no cuesta nada.
• Mientras las ediciones de pago estén deshabilitadas, ambas rutas de revisión responden editing_disabled y no cobran nada.

05

Precios de candidatos de toma

Un candidato de toma es una imagen o un clip creado para una toma de un video sin rostro, que se puede conservar o descartar en una revisión: POST /v1/runs/{id}/candidates/quote calcula el precio sin cobrar nada; POST /v1/runs/{id}/candidates lo crea.

• Una imagen candidata: 7 créditos.
• Un clip de apertura candidato: 49 créditos.
• Una imagen fija de apertura candidata y su clip: 56 créditos.
• Candidatos de toma de un mismo original en curso a la vez: como máximo 1. Fallidos o sin terminar: como máximo 3. Las revisiones se cuentan por separado.
• Un candidato entregado se cobra como una unidad, tanto si se conserva como si se descarta; uno que falla no cuesta nada.
• Mientras los candidatos de toma estén deshabilitados, las tres rutas de candidatos responden editing_disabled y no cobran nada.

06

Endpoints

Endpoint	Cuesta créditos	Qué hace
POST /v1/skills/make_faceless/quote	no	Calcula el precio de una llamada a make_faceless con esta entrada. No cobra nada.
POST /v1/skills/make_faceless/run	sí	Inicia una ejecución de video sin rostro y responde de inmediato con un run_id. Consulta la ejecución para obtener el resultado.
GET /health	no	Comprueba que la API esté activa. Responde sin una clave.
GET /	no	Indica el nombre del servicio y remite a este documento. Responde sin una clave.
GET /robots.txt	no	Indica a los rastreadores que no indexen el host de la API. Responde sin una clave.
GET /openapi.json	no	La descripción OpenAPI 3.1 de esta API, generada a partir de los mismos esquemas que la API usa para validar. Responde sin una clave.
GET /v1/voices	no	Voces que puedes indicar en voice o voice_id para make_ugc; skill=make_faceless muestra en su lugar las voces de narración de make_faceless.
GET /v1/template-sounds	no	Los sonidos que reproducen las plantillas de make_ugc, por compás: dónde se reproduce cada uno, su valor predeterminado y todos los nombres que acepta template_sounds. Gratis.
GET /v1/moves	no	Catálogo de movimientos que se pueden aplicar a las líneas de un guion como movimientos de make_ugc, make_faceless y una recreación de referencia: qué aporta cada uno al espectador, las líneas a las que se aplica y sus créditos por uso; permite filtrar y paginar; names proporciona las líneas completas. Gratis.
GET /v1/account	no	Saldo, deuda y retenciones de la cuenta asociada a la clave, además de nuestras respuestas a sus solicitudes de asistencia y comentarios.
POST /v1/skills/make_ugc/quote	no	Calcula el precio de una llamada a make_ugc con esta entrada. No cobra nada.
GET /v1/runs/{id}	no	Estado de una ejecución de cualquier habilidad, sus advertencias y la URL de su video.
GET /v1/runs/{id}/shots	no	Tomas de una ejecución: el intervalo, las palabras, la descripción y la vista previa de cada toma, y si se puede editar la ejecución.
GET /v1/runs/{id}/edit	no	Borrador guardado de una edición de una ejecución, con su versión. La versión 0 corresponde a una ejecución sin borrador: su documento no cambia nada.
POST /v1/runs/{id}/edit	no	Guarda el borrador de una edición con respecto a la versión que se leyó. No cobra ni renderiza nada.
POST /v1/runs/{id}/revisions/quote	no	Calcula el precio de una revisión de una ejecución sin rostro: qué genera el documento o la lista de cambios en las tomas y cuánto cuesta. No cobra nada. Una revisión entregada se cobra al total cotizado; una que falla no se cobra. Mientras las ediciones de pago estén cerradas, responde editing_disabled.
POST /v1/runs/{id}/revisions	sí	Inicia una revisión, una nueva ejecución sin rostro creada a partir del documento, y retiene los créditos cotizados. La misma Idempotency-Key con la misma solicitud devuelve la primera revisión; otra clave crea otra revisión y vuelve a cobrar. Una revisión entregada se cobra al total cotizado; una que falla no se cobra. Mientras las ediciones de pago estén cerradas, responde editing_disabled y no cobra nada.
POST /v1/runs/{id}/candidates/quote	no	Calcula el precio de una candidata para una toma de una ejecución sin rostro: una imagen o un clip creado para una toma, que se puede conservar o descartar. No cobra nada. Una candidata entregada se cobra por su unidad, tanto si se conserva como si se descarta; una que falla no se cobra. Mientras las candidatas de tomas estén cerradas, responde editing_disabled.
POST /v1/runs/{id}/candidates	sí	Inicia una candidata para una toma y retiene el precio de su unidad. Una candidata entregada se cobra por su unidad, tanto si se conserva como si se descarta; una que falla no se cobra. La misma Idempotency-Key con la misma solicitud y take devuelve la primera candidata; take + 1 crea otra y vuelve a cobrar. Mientras las candidatas de tomas estén cerradas, responde editing_disabled y no cobra nada.
GET /v1/runs/{id}/candidates	no	Candidatas para las tomas de la familia de una ejecución sin rostro, de la más antigua a la más reciente, cada una con su estado, su cargo y una vista previa cuando esté lista. Mientras las candidatas de tomas estén cerradas, responde editing_disabled.
DELETE /v1/runs/{id}/media	no	Elimina los archivos de una ejecución finalizada: a partir de ahora no se proporcionan enlaces a ellos y se borran del almacenamiento después de 7 días. La ejecución y su cargo se mantienen. Se rechaza con run_media_in_use mientras otra ejecución sin finalizar los esté usando. Gratis.
POST /v1/skills/make_ugc/run	sí	Inicia una ejecución de video y responde de inmediato con un run_id. Consulta la ejecución para obtener el resultado.
GET /v1/public/skills	no	Catálogo de habilidades y sus entradas, sin necesidad de una clave.
GET /v1/public/prices	no	Precio en créditos de cada acción: una cantidad fija por unidad o una fórmula cuyo precio depende de la entrada; la cotización proporciona la cantidad exacta. Gratis, sin necesidad de una clave.
GET /v1/actors	no	Actores guardados en la cuenta, con el id que acepta make_ugc.
GET /v1/public/actor-previews/{actor_id}/{version}/{file}	no	Imagen PNG de un actor de la biblioteca; el enlace lo proporcionan list_actors y las cotizaciones. Responde sin una clave.
DELETE /v1/actors/{id}	no	Elimina un actor guardado. Se conserva un actor que esté usando una ejecución activa.
GET /v1/actors/{id}/defaults	no	Lee la política predeterminada del actor guardado para las personas que aparecen en inserciones.
POST /v1/actors/{id}/defaults	no	Establece la política predeterminada del actor guardado para las personas que aparecen en inserciones. Una ejecución puede anularla.
GET /v1/brand-kit	no	Lee el diseño guardado de la cuenta: colores, fuentes, logotipo, esquinas y movimiento. Devuelve null si no hay ninguno guardado.
POST /v1/brand-kit	no	Guarda el diseño de la cuenta o lo borra con null. Un video que no indique ni diseño ni template_theme lo utiliza. Gratis.
POST /v1/brand/extract	no	Lee los colores, las fuentes, el logotipo y las esquinas de un sitio público y los convierte en un diseño propuesto con texto legible para que lo confirmes. Gratis; cuenta para el límite horario de descargas de URL.
POST /v1/skills/create_actor/quote	no	Calcula el precio de una llamada a create_actor con esta entrada. No cobra nada.
POST /v1/skills/create_actor/run	sí	Inicia una ejecución de actor y responde de inmediato con un run_id. Consulta la ejecución para obtener el resultado.
POST /v1/uploads	no	Recibe bytes de imagen y devuelve una URL https firmada, upload_id y content_digest (SHA-256 de los bytes originales). Usa upload_id como asset_id de un flujo de trabajo y copia content_digest directamente; las llamadas nativas de video y actor usan url.
GET /v1/uploads	no	Tus cargas que todavía puede usar una revisión, de la más reciente a la más antigua y una por imagen; cada una incluye upload_id, el content_digest original, una URL recién firmada y el momento en que deja de poder usarse. Gratis.
POST /v1/uploads/import	no	Descarga un PNG o JPEG público mediante https (hasta 10 MB, 20 segundos y 3 redirecciones) y devuelve la misma estructura de carga. Se rechazan las direcciones privadas; 30 descargas por hora y cuenta. Gratis.
POST /v1/uploads/intents	no	Devuelve una URL PUT prefirmada para un PNG o JPEG local del tipo, tamaño y sha256 declarados. upload_id se puede usar una vez completado el PUT; antes de eso, las generaciones responden upload_not_finished. Gratis.
GET /v1/uploads/{id}	no	Una carga con una URL recién firmada y su usable_until. Después de un PUT prefirmado, confirma el archivo: responde upload_not_finished hasta que esté disponible y upload_expired después de 24 horas. Gratis.
DELETE /v1/uploads/{id}	no	Elimina una carga: a partir de ahora ninguna llamada puede usarla y su archivo se borra del almacenamiento después de 7 días, salvo que se conserve otra carga de la misma imagen. Se rechaza con upload_in_use mientras una ejecución sin finalizar la esté usando. Gratis.
POST /v1/assets	no	Guarda una imagen como recurso de la cuenta, que se conserva hasta que la elimines: puede provenir de un run_id, un upload_id, una URL https pública o base64. Para tu propio material se necesita rights_confirmed: true o analysis_only: true si se trata de una referencia que se conserva únicamente para analyze_reference y que no se usa en ningún renderizado ni generación. 2000 recursos y 1 GB por cuenta; 20 GB una vez que haya comprado créditos; 100 recursos nuevos al día. Gratis.
POST /v1/assets/bytes	no	Guarda el PNG o JPEG del cuerpo (hasta 10 MB) como recurso; role, name y rights_confirmed=true (o analysis_only=true, únicamente para analyze_reference) se envían en la consulta. Gratis.
GET /v1/assets	no	Recursos activos de la cuenta, del más reciente al más antiguo, cada uno con un enlace firmado durante una hora, y uso de los límites; permite filtrar por role y kind, y paginar mediante cursor. Gratis.
GET /v1/assets/{id}	no	Un recurso activo con un enlace firmado durante una hora. Gratis.
POST /v1/assets/{id}	no	Cambia el nombre de un recurso o modifica su role. Gratis.
DELETE /v1/assets/{id}	no	Elimina un recurso: desaparece de la lista y de las generaciones de inmediato, y una limpieza diaria elimina su archivo una vez transcurridos 7 días. Gratis.
GET /v1/public/workflows	no	Enumera los métodos de flujo de trabajo públicos e indica si cada uno está disponible ahora, sin incluir los planes de cuenta ni una declaración de admisión de la cuenta.
GET /v1/public/workflows/{id}	no	Consulta las instrucciones y limitaciones de un método, y lo que puede hacer en este momento.
POST /v1/workflow-plans	no	Crea un borrador de flujo de trabajo inmutable, propiedad de la cuenta. No cobra nada ni inicia un renderizado.
GET /v1/workflow-plans/{id}	no	Consulta la revisión actual del flujo de trabajo de la cuenta y su estado de preparación.
POST /v1/workflow-plans/reference-remake	no	Compila un perfil de referencia y el guion aceptado en un nuevo borrador de recreación de referencia; sus advertencias indican qué aspectos no reproduce el plan. No cobra, no genera nada ni inicia un renderizado.
POST /v1/workflow-plans/{id}/revisions	no	Guarda un nuevo borrador con respecto a base_version. Si se reintenta una solicitud cuya respuesta se perdió, devuelve la revisión correspondiente.
POST /v1/workflow-plans/{id}/approve	no	Aprueba una revisión lista y su digest. No cobra nada ni inicia un renderizado.
POST /v1/workflow-plans/{id}/quote	no	Cotiza un flujo de trabajo aprobado mediante la preparación nativa. La cotización caduca después de cinco minutos; no se reservan créditos. El lanzamiento es el cuerpo listo de la solicitud de ejecución, con un idempotency_key nuevo.
POST /v1/workflow-plans/{id}/run	sí	Admite una sola vez la solicitud nativa exacta cotizada y devuelve un recibo y la Run nativa existente. Envía launch de la cotización sin cambios como cuerpo, con el encabezado Idempotency-Key igual a launch.idempotency_key; si se repite la misma solicitud aceptada, se devuelve su ejecución.
GET /v1/generations/models	no	Modelos que aceptan generate_image y generate_video, con sus modos medidos, relaciones de aspecto, resoluciones, duraciones, tamaño de salida y créditos por imagen o por segundo. Gratis. Mientras las generaciones estén cerradas, responde generations_disabled.
POST /v1/skills/generate_image/quote	no	Calcula el precio de una imagen con esta solicitud: créditos, ancho, alto y advertencias. No cobra nada.
POST /v1/skills/generate_image/run	sí	Inicia la generación de una imagen y responde de inmediato con un run_id; el bloque generation de la ejecución contiene la imagen una vez entregada. Una generación fallida no se cobra. Mientras las generaciones estén cerradas, responde generations_disabled y no cobra nada.
POST /v1/skills/generate_video/quote	no	Calcula el precio de un clip sin sonido con esta solicitud: créditos por segundo multiplicados por su duración, ancho, alto y advertencias. No cobra nada.
POST /v1/skills/generate_video/run	sí	Inicia la generación de un clip y responde de inmediato con un run_id; el bloque generation de la ejecución contiene el clip una vez entregado. Una generación fallida no se cobra. Mientras las generaciones estén cerradas, responde generations_disabled y no cobra nada.
POST /v1/reference-analyses/quote	no	Calcula el precio de analizar este recurso o enlace: 70 créditos, 10 con mode data o 0 si ya se puede devolver el análisis activo en ese modo. No cobra nada.
POST /v1/reference-analyses	sí	Empieza a analizar un recurso MP4 de hasta 120 s para crear un perfil de referencia (o, con mode data, su transcripción, gancho y hoja de fotogramas) y responde de inmediato; el mismo recurso en el mismo modo devuelve el mismo análisis gratis. Retiene 70 créditos (10 para data), que se cobran cuando el análisis se completa correctamente; si falla, no cuesta nada. 10 análisis completos nuevos y 60 análisis data nuevos por hora.
GET /v1/reference-analyses/{id}	no	Un análisis de referencia: en cola, en análisis, completado correctamente con reference_profile o data y advertencias, o fallido con su error. Gratis.
POST /v1/creator-profiles/quote	no	Calcula el precio de un perfil de creador para este enlace: 20 créditos, o 0 si se puede devolver un perfil del mismo creador de la última hora. No cobra nada.
POST /v1/creator-profiles	sí	Inicia el análisis del creador detrás de un perfil o enlace de video de Instagram o TikTok: sus 12 videos más recientes con visualizaciones, Me gusta, comentarios y compartidos, la mediana de visualizaciones y el x de cada video respecto a ella. Responde de inmediato; si se consulta al mismo creador en el plazo de una hora, devuelve el mismo perfil gratis. Retiene 20 créditos, que se cobran cuando la operación se completa correctamente; si la cuenta es privada o está vacía, o si se produce cualquier error, no cuesta nada. 30 perfiles nuevos por hora.
GET /v1/creator-profiles/{id}	no	Un perfil de creador: en cola, en análisis, completado correctamente con el perfil y las advertencias, o fallido con el error correspondiente. Gratis.
DELETE /v1/creator-profiles/{id}	no	Elimina de inmediato un perfil de creador completado; la ejecución que lo generó y su cargo se mantienen. Se rechaza con run_not_finished mientras se está generando. Gratis.
POST /v1/trend-searches/quote	no	Calcula el precio de una búsqueda por tema: 20 créditos, o 0 si una búsqueda de la misma consulta realizada durante la última hora ya daría la respuesta. No cobra nada.
POST /v1/trend-searches	sí	Inicia una búsqueda de reels sobre un tema; combina los resultados de TikTok e Instagram, salvo que se indique una plataforma: hasta 10 reels por plataforma, uno por creador, cada uno con sus visualizaciones comparadas con la mediana de su creador. Responde de inmediato; si se repite la misma consulta en el plazo de una hora, devuelve la misma búsqueda gratis. Retiene 20 créditos, que se cobran cuando la operación se completa correctamente, incluso si los resultados solo incluyen una plataforma (warnings[] indica cuál es la otra); si no se encuentra ningún reel o se produce cualquier error, no cuesta nada. 10 búsquedas nuevas por hora.
GET /v1/trend-searches/{id}	no	Una búsqueda por tema: en cola, en curso, completada correctamente con los reels y las advertencias, o fallida con el error correspondiente. sort muestra los mismos reels en otro orden. Gratis.
POST /v1/feedback	no	Cuéntanos qué falta, qué resulta confuso, qué está mal o qué va lento; puedes referirte a una ejecución de esta cuenta. Leemos todos los comentarios. Gratis. Si se envía el mismo tipo, texto y ejecución en un plazo de 24 horas, se devuelve el mismo feedback_id; 20 por hora.
Una ejecución de cualquier skill se consulta desde el mismo lugar, GET /v1/runs/{id}, y pasa por estos estados: queued, generating, scripting, tts, avatar, compositing, uploading, succeeded, failed.

GET /v1/runs/{id}?wait_seconds=N (como máximo 50) mantiene la respuesta en espera hasta que la ejecución tenga éxito o falle, termine la espera o te desconectes, así que no hace falta esperar entre consultas. Una ejecución sin terminar responde con su estado actual.

07

Skills y sus entradas

make_ugc. Inicia la generación de un video UGC con sincronización labial. El actor se obtiene de actor_id (un actor guardado de list_actors) o de image; de lo contrario, se usa el actor predeterminado. El formato y la resolución dependen de la solicitud y de la fuente; el valor predeterminado es 1080x1920. Los subtítulos son OPT-IN: pregunta primero al usuario. La descripción de un campo que el renderizador aún no admite indica NOT HONORED YET.

Devuelve un run_id de inmediato; consulta get_run con sus poll.arguments hasta que el estado sea 'succeeded' (video_url) o 'failed'. Una ejecución 'failed' cuyo video aún se está generando puede volver a 'queued' y tener éxito más adelante; esto se indica en warnings[]. attempt=2,3,… inicia una ejecución NUEVA con la misma entrada. Para crear un video como un reel de referencia, usa analyze_reference y luego plan_reference_remake con su analysis_id.

Campo	Obligatorio	Qué significa
script	opcional	Las palabras que dice el actor; es obligatorio salvo que segments proporcione el texto hablado. Segments y los insertos anclados al texto requieren la cualificación para formato largo en el servidor. Límites de script según el modelo de voz: eleven_v3: 5000 caracteres; eleven_flash_v2_5: 10000 caracteres; eleven_turbo_v2_5: 10000 caracteres; eleven_v4: 5000 caracteres; gemini-3.8-flash-tts: 5000 caracteres. El recuento incluye espacios, etiquetas de audio y marcas de énfasis; los emojis pueden contar como dos caracteres. Las etiquetas de pausa se eliminan del texto enviado a eleven_v4 y gemini-3.8-flash-tts y no se cuentan en esos casos. No hay límite de palabras. La duración y el precio son estimaciones hasta que se midan. Acentuación rusa: escribe la vocal tónica en mayúscula dentro de una palabra en minúsculas («потОм», «зАмок»); eleven_v4 y gemini-3.8-flash-tts la reciben como la marca de acento U+0301 («пото́м»); si se escribe directamente la marca, se conserva. Una mayúscula al principio de una palabra sigue siendo mayúscula, y las palabras con una segunda mayúscula o una consonante mayúscula en su interior (todo en mayúsculas, «ВУЗы») se dejan tal cual. Una única vocal mayúscula dentro de una palabra siempre se interpreta como acento, así que escribe «Яндекс Еда», no «ЯндексЕда». Indica a los usuarios que escriban en ruso que pueden marcar el acento de esta manera. eleven_flash_v2_5 y eleven_turbo_v2_5 cuestan menos, pero interpretan mal las marcas de acento: las mayúsculas les llegan sin cambios.
segments	opcional	Segmentos ordenados de actores e imágenes; requiere la cualificación para formato largo en el servidor, captions=false y 1080p. Los medios de imagen requieren broll_policy=anyone explícito.
inserts	opcional	Insertos de imagen o vídeo anclados al texto sobre la narración completa; cada uno cubre cover_words palabras pronunciadas desde su ancla. Requiere la cualificación para formato largo en el servidor, 1080p y broll_policy=anyone explícito. Los subtítulos se muestran sobre los insertos.
overlays	opcional	Imágenes o vídeos anclados al texto sobre el presentador visible, cada uno en una posición o lugar. Puede haber como máximo 2 en pantalla a la vez, en recuadros que no se superpongan. Los subtítulos se desplazan al tercio central o inferior, fuera del overlay, nunca sobre la cara, y se ocultan cuando ninguno de esos espacios está libre. Quedan ocultos bajo los insertos a pantalla completa. Se aplican los mismos requisitos que a los insertos: script, cualificación para formato largo en el servidor, 1080p y broll_policy=anyone explícito. El presentador permanece en pantalla, por lo que el precio no cambia.
layout_windows	opcional	Reencuadres del presentador anclados al texto: split (solo 9:16) o card. Las ventanas no pueden superponerse entre sí ni a un inserto. Se aplican los mismos requisitos que a los insertos. Un presentador cubierto o desenfocado sigue siendo trabajo del proveedor y se factura como tiempo de rostro.
framing	opcional	Tamaños del presentador anclados al texto: cada uno cambia a un plano cercano o medio durante sus palabras y vuelve al plano original cuando terminan. Los elementos no pueden superponerse entre sí, a un inserto ni a una ventana de diseño. Un encuadre que quede completamente bajo plantillas a pantalla completa se indica en warnings[]. Cuando un énfasis punch_in coincide con un encuadre, se dibuja el encuadre. Requiere script y la cualificación para formato largo en el servidor; el precio no cambia.
templates	opcional	Plantillas gráficas, cada una { id, kind, anchor, cover_words?, placement?, transition?, data }. En cualquier ejecución del script. Las plantillas nunca cambian el precio: cada ejecución se factura según sus componentes, tal como los indica list_prices, y el tiempo de un presentador cubierto por una plantilla sigue contando como tiempo de presentador. Los Ids son únicos entre inserts, overlays, layout_windows y templates. El texto es una línea de letras latinas o de la propia escritura del script, dígitos y puntuación común, sin emojis; un glifo CJK ancho cuenta como 2 para el límite, y el texto largo se reduce para ajustarse al ancho del tipo. size small|medium|large escala un tipo; si se omite, es medium. Un campo media acepta { asset_id } de un recurso listo del tipo que indica. Una cita interna nombra palabras dentro del propio texto de la plantilla, después de la palabra anterior: su ritmo cae en la primera palabra indicada y no debe coincidir con un insert ni con una plantilla de pantalla completa; un clic o paso sin cita se distribuye uniformemente. Un ritmo pronunciado antes de que aparezca la plantilla se desplaza justo después de su entrada, con una advertencia. Una plantilla que coincide con la banda de subtítulos los oculta mientras se muestra; una situada en otro lugar, como una pequeña en la parte superior, los deja visibles. Una plantilla de pantalla completa también oculta al presentador, los overlays y las plantillas superpuestas al presentador mientras se muestra; nunca coincide con un insert de wipe o zoom, y el presentador cubierto se factura. Se muestran como máximo 3 overlays y plantillas superpuestas al presentador a la vez, en áreas que no se solapan. template_theme define el aspecto de todas ellas. Tipos: tag (over): una píldora corta con degradado sobre el presentador o un insert; sin position, se coloca en el espacio de los subtítulos y los oculta mientras se muestra; data text ≤ 32, position? top|center|bottom, size? small|medium|large. lower_third (over): una barra con nombre y cargo en la parte inferior del encuadre; los subtítulos se ocultan mientras se muestra; si se omite style, es clean_bar; data name ≤ 28, role? ≤ 36, side left|right, style? clean_bar|side_rule|soft_pill|mask_reveal, size? small|medium|large. end_card (over): una píldora con un sitio web y una llamada a la acción opcional en el espacio de los subtítulos; los subtítulos se ocultan mientras se muestra; data site ≤ 32, cta? ≤ 48, size? small|medium|large. title_card (full): una tarjeta de gancho a pantalla completa: el título (hasta dos líneas) en una tarjeta blanca junto a una imagen de logotipo opcional, y una etiqueta opcional debajo; data title ≤ 48, chip? ≤ 32, logo? {asset_id} image, size? small|medium|large. quote (full): una tarjeta de cita a pantalla completa: comillas, el texto en hasta cuatro líneas y luego el autor con una foto redonda opcional, recortada en círculo; data text ≤ 120, author? ≤ 32, photo? {asset_id} image (recortada para llenar), size? small|medium|large. stat (full|over): un número que cuenta desde 0 hasta value (hasta 2 decimales), con prefix y suffix a sus lados y una etiqueta debajo; full llena el encuadre, over se coloca a la altura del pecho sobre una tarjeta; data value number, prefix? ≤ 6, suffix? ≤ 6, label? ≤ 32, size? small|medium|large. callout (over): una flecha o un círculo que señala un punto del encuadre y pulsa; target {x,y} en % del encuadre desde la esquina superior izquierda, con una píldora de etiqueta opcional debajo o encima; puede señalar el rostro, y su etiqueta evita el rostro cuando es posible; también sobre un insert; data target {x,y}, style arrow|ring, text? ≤ 24, size? small|medium|large. checklist (over): 2–4 filas, cada una con un icono opcional, una etiqueta y un interruptor o casilla marcada o desmarcada; un cursor hace clic en las filas por turnos (item es el índice de la fila desde 0), y cada clic cambia su estado; debajo del rostro; data items 2–4 de {label ≤ 24, on true|false, icon? phone|briefcase|user|clock|chat|star}, clicks? 0–6 de {item number, quote? cita interna}, style? switch|check, size? small|medium|large. phone_call (over): una llamada entrante en un teléfono neutro a un lado (a la derecha, salvo que side sea left): la persona que llama, un subtítulo y un anillo de avatar redondo; luego se responde la llamada en answer_at y se inicia el temporizador (o aparece un banner de espera); junto al rostro en encuadres anchos, debajo en los altos; data caller ≤ 24, subtitle? ≤ 32, avatar? {asset_id} image (recortada para llenar), answer_at cita interna, side? left|right, size? small|medium|large, banner? ≤ 32, banner_note? ≤ 48, mask_number? true|false. compare (full): una tarjeta 3:5 a pantalla completa que muestra la imagen del antes; en reveal_at, la imagen del después entra con un barrido diagonal (reveal ausente) o con un barrido desde la izquierda hasta un divisor central; ambas permanecen, con píldoras de etiqueta opcionales; data before {asset_id} image (recortada para llenar), after {asset_id} image (recortada para llenar), labels? {before? ≤ 20, after? ≤ 20}, reveal_at cita interna, reveal? sweep|wipe, size? small|medium|large. notification (over): una notificación de teléfono en la parte superior, por encima del rostro: un icono (o la inicial de la aplicación), la aplicación, un título y una línea de texto; aparece desde arriba, permanece al menos 1.2 s y desaparece antes de que termine su intervalo; cada tarjeta apilada aparece desde arriba sobre la anterior en su at, empujando las anteriores hacia atrás; data app ≤ 20, title ≤ 32, body ≤ 80, icon? phone|briefcase|user|clock|chat|star, stack? 1–2 de {app? ≤ 20, title ≤ 32, body ≤ 80, icon? phone|briefcase|user|clock|chat|star, at? cita interna}, size? small|medium|large. progress (over): 2–5 pasos en una columna sobre una tarjeta, cada uno se completa con una marca de verificación por turnos, en su cita advance_at (una por paso, en orden) o distribuidos uniformemente; debajo del rostro; data steps 2–5 de ≤ 20, advance_at? 2–5 de cita interna, size? small|medium|large. rating (over): cinco estrellas en una tarjeta que se rellenan por turnos hasta llegar a stars (1–5 en incrementos de medio punto; una media estrella se rellena a la mitad), con una etiqueta opcional debajo; a la altura del pecho; data stars number, label? ≤ 32, size? small|medium|large. chat_window (full): una ventana de chat a pantalla completa: el prompt se escribe, la respuesta aparece palabra por palabra, la tabla se abre fila por fila y luego aparecen tarjetas de respuesta, cada una en su at o distribuidas uniformemente; zoom true acerca y aleja en los ritmos; data app? ≤ 24, prompt ≤ 120, replies? 1–3 de {title ≤ 32, body? ≤ 64, at? cita interna}, answer? {text ≤ 150, at? cita interna}, table? {columns 2–3 de ≤ 16, rows 1–4 de {cells 2–3 de ≤ 20, at? cita interna}}, zoom? true|false, size? small|medium|large. video_grid (full): una cuadrícula a pantalla completa de los recursos de video de la cuenta, en mosaicos 9:16, 2x2 (celdas 1–4, con la columna izquierda elevada) o 3x1 (celdas 1–3); sin layout, las celdas indicadas determinan la disposición; cada mosaico aparece después del anterior y se reproduce sin sonido, con un título opcional encima; data layout? 2x2|3x1, cell_1 {asset_id} video (recortado para llenar), cell_2 {asset_id} video (recortado para llenar), cell_3 {asset_id} video (recortado para llenar), cell_4? {asset_id} video (recortado para llenar), title? ≤ 40, size? small|medium|large. word_title (full): un título cinético a pantalla completa en el color de acento: la primera entrada aparece desde el primer fotograma de la plantilla; cada entrada posterior aparece en su cita at (normalmente las mismas palabras que se pronuncian) o se distribuye uniformemente; reveal replace (predeterminado) muestra una entrada a la vez, build añade cada entrada al título; data words 1–8 de {text ≤ 16, at? cita interna}, reveal? replace|build, size? small|medium|large. phone_screen (full): un teléfono a pantalla completa que reproduce el video de pantalla (sin sonido; un degradado si no se proporciona uno) y cuyos estados cambian por turnos, cada uno en su cita at o distribuidos uniformemente: lock (atenuado, un candado y el texto), play (el video nítido, el texto en la parte superior), liked (un corazón y el texto), counter (una píldora en la parte inferior de la pantalla), timer (una insignia en el borde superior), tag (una etiqueta con una línea indicadora en el lateral de la pantalla); lock, play y liked se reemplazan entre sí, las etiquetas se acumulan y un counter o timer posterior reemplaza al anterior; data screen? {asset_id} video (recortado para llenar), states 1–6 de {state lock|play|liked|counter|timer|tag, text? ≤ 24, at? cita interna}, size? small|medium|large. terminal (full): una tarjeta de terminal oscura a pantalla completa: el comando se escribe; un diff debajo contrae sus líneas del (rojas) y abre sus líneas add (verdes) en diff.at; luego aparece una línea de estado marcada en at; title nombra la tarjeta; data title? ≤ 24, command ≤ 100, diff? {lines 2–7 de {text ≤ 36, change? add|del}, at? cita interna}, status ≤ 40, at? cita interna, size? small|medium|large. pointer_chips (over): 1–4 etiquetas en una columna debajo del rostro (a la derecha, salvo que side sea left), cada una unida mediante una línea curva a un punto de su target {x,y} en % del encuadre desde la esquina superior izquierda; aparecen por turnos en su cita at o distribuidas uniformemente; las líneas pueden cruzar el rostro, pero las etiquetas lo evitan; también sobre un insert; data items 1–4 de {target {x,y}, text ≤ 20, at? cita interna}, side? left|right, size? small|medium|large. chart (full): un gráfico de barras o líneas a pantalla completa, con 2–6 puntos etiquetados sobre una tarjeta: en el at de cada punto, o distribuidos uniformemente, la barra crece o la línea se dibuja hasta él y su valor cuenta hacia arriba, con suffix después; title encima; data type bar|line, title? ≤ 40, suffix? ≤ 6, points 2–6 de {label ≤ 12, value number, at? cita interna}, size? small|medium|large. race (full): una carrera de barras clasificadas a pantalla completa: una barra por nombre, con la más larga arriba; los valores de la primera ronda aparecen desde el inicio; luego, en el at de cada ronda posterior, o distribuidos uniformemente, las barras se desplazan a sus valores y cambian de posición según la clasificación, y la etiqueta de la ronda aparece debajo; data title? ≤ 40, suffix? ≤ 6, names 3–6 de ≤ 14, rounds 2–5 de {label? ≤ 10, values 3–6 de number, at? cita interna}, size? small|medium|large. hand_title (full|over): un título escrito trazo a trazo con una tipografía manuscrita (hasta dos líneas), seguido de un marcador que se dibuja sobre las palabras del título desde mark.word (índice desde 0) durante mark.words (si se omite, 1), en mark.at o hacia el final de la plantilla; over se coloca en el espacio de los subtítulos y los oculta; data text ≤ 40, mark? {word number, words? number, style highlight|underline|circle, at? cita interna}, size? small|medium|large. word_fill (full): una sola palabra enorme a pantalla completa cuyas letras muestran tu video (clip, reproducido sin sonido), mientras el resto del encuadre usa el color de fondo del tema; crece durante sus primeros 10 fotogramas; data word ≤ 10, clip {asset_id} video, size? small|medium|large.
template_theme	opcional	El aspecto de todas las plantillas de la ejecución: un ajuste preestablecido y un acento opcional; solo con templates.
design	opcional	La identidad visual de la ejecución: templates, la tarjeta final y el acento de los subtítulos se basan en ella. Solicita la marca o usa extract_brand; si se omite, se usa el kit de marca guardado. No se puede usar junto con template_theme.
template_sounds	opcional	Aceptado; el esquema aún no incluye una descripción.
scenes	opcional	Gráficos creados para este video a partir de tus palabras, para lo que no cubre ninguna plantilla: cada uno se dibuja sobre el presentador (over) o en pantalla completa (full) mientras se pronuncian sus palabras; si se dibuja sobre los subtítulos, los oculta mientras se muestra. Si no supera nuestra comprobación, se omite y se indica en warnings[]. 25 créditos por escena, con su propia línea de cita; solo se cobran las escenas dibujadas en el video entregado. Requiere un script y cumplir los requisitos de formato largo en el servidor.
motion_style	opcional	Tipo aceptado: object.
moves	opcional	Movimientos de list_moves aplicados a tus palabras: cada uno { name, anchor: { quote }, cover_words?, placement?, data? }. Cada uno se dibuja tal como lo indica su línea en list_moves; data acepta los campos que allí se nombran. Si un movimiento no se puede dibujar sobre sus palabras o en este video, se indica en warnings[] y se omite; nunca se descarta sin avisar. Sus créditos aparecen en la cita.
edit_sounds	opcional	Valores aceptados: true | false.
music	opcional	Música de fondo bajo la voz, creada para este video; desactivada salvo que la solicites. "auto" toma el ambiente del script; { mood } lo indica con tus propias palabras, como "calm lo-fi". 60 créditos por video, con su propia línea en la cita; solo se cobra cuando el video se entrega con música.
call	opcional	Una llamada telefónica después de una cita: el presentador escucha y luego se queda inmóvil mientras la llamada se reproduce como una línea telefónica, primero con un tono de llamada; un teléfono junto a él muestra la llamada (en su lugar, se usa una plantilla phone_call que cubra la llamada). Requiere un script, un encuadre 9:16 y palabras después de la llamada. El presentador inmóvil y la llamada suman segundos de producción, no segundos de presentador; si durante la llamada se muestra un avatar en vivo, su precio aparece por separado en list_prices. Requiere cumplir los requisitos de formato largo en el servidor.
interview	opcional	Una entrevista: una voz fuera de cámara dice las palabras marcadas del guion con su propia voz; el presentador responde el resto en pantalla y permanece inmóvil mientras habla la voz fuera de cámara. Requiere guion y habilitación para formato largo en el servidor; los fotogramas en los que el presentador permanece inmóvil suman segundos de producción, no segundos de presentador.
presenter_gaze	opcional	Hacia dónde mira el presentador durante estas palabras, desde la perspectiva del espectador: cámara, izquierda o derecha. Requiere actor_id con esa vista (list_actors); un cambio de mirada es un corte.
shots	opcional	Tomas en vivo del actor durante algunas palabras del guion: talking, talking_action (habla mientras actúa) o action (actúa mientras las palabras se reproducen como voz en off). Las tomas no pueden superponerse; las palabras que quedan fuera de ellas corresponden a la toma habitual del presentador. Requiere un fotograma 9:16 y habilitación para formato largo en el servidor; cada tipo tiene su propio precio por segundo de presentador en list_prices.
product_asset_id	opcional	La imagen del producto (ast_…) que muestran las tomas con producto.
person	opcional	AÚN NO COMPATIBLE: person aún no es compatible: esta solicitud usa el actor predeterminado; elige actor_id en list_actors o proporciona una imagen para seleccionar otro rostro
actor_id	opcional	ID de actor guardado de Clipwright, obtenido de list_actors. Elige actor_id, image o person; no los combines. Si no se especifica voice ni voice_id, la voz dependerá del género del actor. No se puede combinar con actor_gender.
presenter_framing	opcional	close (predeterminado), wide (presentador más abajo, con espacio arriba) o full (de la cabeza a los pies). Requiere la vista del actor con ese nombre (list_actors), solo 9:16; full pasa a wide y luego a close, además de warnings[].
presenter_mic	opcional	true: el presentador sostiene un micrófono pequeño. Requiere la vista del actor con micrófono en ese encuadre (list_actors; las de la biblioteca son wide); de lo contrario, no habrá micrófono y se incluirá warnings[].
image	opcional	URL https pública de la foto del actor (PNG, JPEG o WebP, hasta 10 MB). Un archivo en disco debe pasar primero por upload_image (POST /v1/uploads); proporciona la url que devuelve. Se rechaza una fuente que no podamos usar —host privado o de loopback, http, inaccesible, con redirección, de más de 10 MB o que no sea uno de esos tipos de imagen— (unusable_source) antes de cualquier cargo. No detectamos el género del rostro: proporciona actor_gender o voice; de lo contrario, se usará la voz masculina predeterminada y se mostrará una advertencia.
actor_gender	opcional	Género del rostro en image: female | male. Solo se admite con image: selecciona la voz predeterminada de ese género (female: sarah, male: george; en gemini-3.8-flash-tts: kore y charon). Se rechaza con actor_id (se conoce su género) y sin image. Una voz o voice_id explícitos tienen prioridad y la respuesta advierte que actor_gender no cambió nada.
name	opcional	AÚN NO COMPATIBLE: name aún no es compatible: no llega al renderizador
broll_policy	opcional	Política para B-roll: anyone permite personas, incluido el actor; no_actor excluye al actor; no_people excluye a todas las personas, incluidas las manos. Las plantillas con tu propia imagen o video requieren "anyone"; de lo contrario, solo se almacenan. La anulación de la ejecución tiene prioridad sobre el valor predeterminado del actor de la cuenta; de lo contrario, se usa no_people.
captions	opcional	Incrusta subtítulos sincronizados con las palabras en el video, sobre el presentador y sobre las inserciones. No está disponible con segments.
caption_style	opcional	Apariencia de los subtítulos cuando captions=true. hormozi: el estilo predeterminado: mayúsculas blancas gruesas con contorno negro ancho, hasta tres palabras por segmento y una palabra clave por segmento en amarillo (la enfatizada o, si no la hay, la palabra más larga que no sea una palabra vacía). accent: mayúsculas blancas condensadas en negrita, sin contorno, hasta tres palabras por segmento y una palabra clave por segmento en naranja (la enfatizada o, si no la hay, la palabra más larga que no sea una palabra vacía). tiktok: mayúsculas redondeadas en negrita, una o dos palabras a la vez; la palabra pronunciada se vuelve amarilla y aumenta de tamaño. youtube: sans serif limpia y en negrita, cuatro palabras (cinco en 16:9) sobre un recuadro oscuro redondeado cerca de la parte inferior; las palabras aparecen gradualmente y la palabra pronunciada va en rojo. instagram: mayúsculas de estilo cómic con contorno rosa, dos palabras a la vez; la palabra pronunciada aparece de golpe en naranja. minimalist: sans serif sencilla, cuatro palabras sobre una franja oscura semitransparente, con una aparición gradual suave. neon: mayúsculas cian con contorno magenta, dos palabras a la vez; la palabra pronunciada aparece de golpe en blanco. genz: mayúsculas grandes de estilo cómic, una palabra a la vez, que aparece de golpe con un resaltado rosa. campfire: mayúsculas redondeadas de estilo cómic, tres palabras; las palabras pronunciadas se iluminan en dorado y permanecen iluminadas. midnight: mayúsculas tenebrosas, dos palabras, con aparición gradual lenta; la palabra pronunciada va en rojo. plottwist: sans serif gruesa, tres palabras; la palabra pronunciada se vuelve azul cielo y aumenta de tamaño. headline: mayúsculas altas y condensadas sobre una franja negra sólida, tres palabras; la palabra pronunciada aumenta de tamaño en amarillo. promo: sans serif gruesa sobre una cápsula azul, tres palabras; la palabra pronunciada aparece de golpe en amarillo. lecture: sans serif legible, cuatro palabras sobre un recuadro oscuro redondeado; la palabra pronunciada va en verde. highlighter: sans serif gruesa, cuatro palabras; las palabras pronunciadas se vuelven verde lima y permanecen iluminadas. studio: sans serif, cuatro palabras que aparecen como si se escribieran sobre un recuadro oscuro desenfocado; la palabra pronunciada va en ámbar. broadcast: sans serif con contorno, cuatro palabras en la parte baja del encuadre; la palabra pronunciada va en amarillo pálido. arcade: mayúsculas amarillas de estilo pixelado, dos palabras; la palabra pronunciada rebota y aparece en blanco. clutch: mayúsculas de estilo pincel, una palabra a la vez, que aparece de golpe en verde. bubblegum: letras redondeadas de estilo display con contorno rosa, dos palabras; la palabra pronunciada rebota y aparece en amarillo. crayon: escritura a mano con marcador y contorno azul marino, dos palabras; la palabra pronunciada aparece de golpe en naranja. lyrics: escritura manuscrita, cuatro palabras; las palabras pronunciadas se iluminan en rosa y permanecen iluminadas. bassdrop: mayúsculas de estilo display con contorno, una palabra a la vez, que aumenta de tamaño en naranja. punch: planteamiento y remate en el centro del encuadre: una pequeña línea introductoria blanca sobre una o dos palabras clave grandes, azules y brillantes; las demás palabras son pequeñas y blancas. Alias: minimal aplica el estilo minimalist. Si una fuente no puede representar las letras del guion, se sustituye por una sans serif sencilla. Vistas previas: https://clipwright.io/captions
caption_emphasis	opcional	Palabras clave o frases cortas que se deben enfatizar; cada una se cita del guion y debe coincidir con una cita de inserción (sin distinguir mayúsculas ni puntuación). Un elemento puede ser la cita o { quote, look }: look punch muestra una pequeña línea introductoria de la misma oración sobre la cita, que aparece como una palabra clave grande y brillante; look pill muestra solo la cita dentro de una cápsula redondeada; look color la muestra en el color de acento y con el mismo tamaño; look box la muestra sobre un recuadro suave del color de acento y con el mismo tamaño. Si no se especifica look, punch aplica el estilo punch; hormozi y accent aplican color; los demás ajustes preestablecidos muestran la cita en mayor tamaño y con su color de resaltado. Se enfatizan todas las apariciones. Requiere captions=true y script; si una cita no aparece en el guion, se rechaza antes de cualquier cargo.
caption_mode	opcional	full (predeterminado si se omite): se subtitulan todas las palabras pronunciadas. highlights: los subtítulos aparecen solo alrededor de las citas de caption_emphasis (introducción, cita y breve continuación) y en ningún otro lugar; requiere caption_emphasis. En ambos modos, los subtítulos se ocultan mientras haya una inserción a pantalla completa o una plantilla que coincida con su franja.
caption_position	opcional	Ubicación de los subtítulos: top, middle, lower o bottom (80% de la altura). Si se omite, se usa la ubicación propia de caption_style. Requiere captions=true.
caption_place	opcional	En lugar de caption_position, fija los subtítulos a su propia altura; las superposiciones nunca los desplazan y se rechaza una superposición que coincida con ellos, salvo que se coloque relative_to captions. Requiere captions=true.
presenter_place	opcional	Altura y centro del rostro del presentador en el encuadre. El retrato se encuadra más de cerca para alcanzar esa posición, usando la vista wide del actor cuando la vista close queda demasiado cerca; si incluso así queda demasiado cerca, warnings[] indica la altura del rostro representada. Requiere actor_id y script con overlays, inserts, layout_windows, framing o call. El precio no cambia.
look	opcional	AÚN NO COMPATIBLE: look aún no es compatible: no llega al renderizador
aspect_ratio	opcional	Formato de salida: 9:16 | 1:1 | 16:9. Si se omite, se usa 9:16 sin image; con image, se usa el formato compatible más cercano a la forma de la imagen, incluso si es apaisada. Especifica este valor siempre que proporciones image. Si la diferencia entre la solicitud y la fuente supera el 15%, se rechaza (aspect_conflict) antes de cualquier cargo.
resolution	opcional	Resolución de salida: 720p | 1080p (lado corto de 720 / 1080 px). Si se omite, se usa 1080p.
voice	opcional	Nombre de voz de list_voices. Ajustes preestablecidos seleccionados: sarah | george | eric | daria_ru_female. La API rechaza cualquier nombre que no devuelva list_voices, antes de cualquier cargo. Si se omite, se usa la voz predeterminada para el género del actor: el género de actor_id, actor_gender con image o george para el actor predeterminado y para image sin actor_gender. gemini-3.8-flash-tts solo habla con sus propias voces (kind model_voice en list_voices, como kore): al indicar una, se selecciona ese modelo; se rechaza una voz con un tts_model que no la admita, antes de cualquier cargo. No se puede combinar con voice_id.
voice_id	opcional	ID de voz sin procesar del proveedor (de 16 a 32 letras y dígitos) para una voz que no esté en el catálogo. Se comprueba de forma diferida: un ID desconocido hace que falle la ejecución, no la solicitud. Se rechaza con tts_model=gemini-3.8-flash-tts. No se puede combinar con voice.
tts_model	opcional	Modelo de voz: eleven_v3 | eleven_flash_v2_5 | eleven_turbo_v2_5 | eleven_v4 | gemini-3.8-flash-tts. Si se omite, se usa el modelo de la voz elegida (list_voices lo muestra): gemini-3.8-flash-tts para sus propias voces y eleven_v4 para todos los ajustes preestablecidos, las voces del catálogo y voice_id sin procesar. Un tts_model explícito tiene prioridad, excepto eleven_v3: ya no se usa para hablar y una ejecución que lo indique usa eleven_v4 con una advertencia. eleven_v4 y gemini-3.8-flash-tts interpretan las marcas de acento (una vocal mayúscula dentro de una palabra rusa, "потОм", se convierte en una; consulta script); eleven_flash_v2_5 y eleven_turbo_v2_5 son alternativas más económicas para idiomas distintos del ruso. gemini-3.8-flash-tts solo habla con sus propias voces (list_voices con model=gemini-3.8-flash-tts; si no se especifica voice, kore para un actor femenino y charon en los demás casos) y no devuelve tiempos por palabra: se rechazan antes de cualquier cargo los ajustes preestablecidos, las voces del catálogo, voice_id, captions=true, segments e inserts. Las etiquetas de audio entre corchetes son una convención de los otros modelos de voz y no se miden con este. Límites del guion según el modelo de voz: eleven_v3: 5000 caracteres; eleven_flash_v2_5: 10000 caracteres; eleven_turbo_v2_5: 10000 caracteres; eleven_v4: 5000 caracteres; gemini-3.8-flash-tts: 5000 caracteres. El recuento incluye espacios, etiquetas de audio y marcas de acento; los emoji pueden contar como dos caracteres. Las etiquetas de pausa se eliminan del texto enviado a eleven_v4 y gemini-3.8-flash-tts y no se cuentan en esos modelos. No hay límite de palabras. La duración y el precio son estimaciones hasta que se midan.
voice_pace	opcional	Velocidad de narración; 1 es la velocidad propia de la voz. gemini-3.8-flash-tts recibe una indicación de estilo; eleven_v4 no tiene control de velocidad, así que elige una voz según las palabras por segundo de list_voices; ambos se indican en warnings[].
pause_trim	opcional	Recorta las pausas que superen estos segundos; false las conserva todas. Valor predeterminado con templates, scenes y shots: 0.15 por oración, 0.08 por coma.
end_hold_s	opcional	Segundos que permanece el último fotograma después de la última palabra: el presentador se congela y todas las capas en pantalla permanecen. Son segundos de producción, no segundos de presentador. Requiere script y habilitación para formato largo.
visible_ai_label	opcional	Etiqueta de IA visible para los videos nuevos del presentador que se marquen, incluidos los de formato largo; la política de admisión del servidor la activa de forma predeterminada. false oculta solo la etiqueta visible y no desactiva el marcado invisible ni la procedencia firmada. Los resultados históricos no cambian.
background	opcional	Valores aceptados: white | blur | contain.
create_actor. Crea un actor personal para esta cuenta a partir de palabras que describan a un adulto ficticio: un retrato 9:16 con exactamente un rostro, además de los otros formatos solicitados editados a partir de él. Devuelve un run_id de inmediato; consulta get_run hasta que el estado sea 'succeeded' (created_actor.actor_id; luego pásalo como actor_id a make_ugc) o 'failed'. Cada imagen publicada se cobra al precio que muestra la cotización; las descripciones rechazadas y los retratos inutilizables no cuestan nada. Si la generación está desactivada, la llamada falla con actor_generation_disabled. from_actor_id conserva el rostro (se comprueba; una discrepancia no cuesta nada). Con style_reference, se rechaza sin cargo un retrato que se parezca a una persona de la foto, y el precio es el mismo. portrait (con gender y approximate_age) se convierte en el retrato 9:16 sin cargo; solo se cobran los otros formatos. Se rechaza sin cargo una imagen que no tenga exactamente un rostro o cuyo rostro esté cortado, sea demasiado pequeño o demasiado grande. Una mascota de marca dibujada con generate_image puede servir como retrato si su rostro se percibe como un rostro humano (una persona de dibujos animados); se rechaza una mascota animal u objeto, así que muéstrala en los insertos.

Field	Required	What it means
description	opcional	Palabras que describen a un adulto ficticio: apariencia, ropa y entorno. Se rechaza antes de cualquier cargo (actor_prompt_refused) nombrar a una persona real o describir un parecido con ella. Es obligatorio salvo que se proporcione from_actor_id o portrait; con from_actor_id, determina la apariencia, la ropa y la pose de la vista, mientras que el género y la edad siguen siendo los de la fuente.
gender	opcional	female | male. Determina el género del actor y la voz predeterminada de los videos con este actor. Es obligatorio salvo que se proporcione from_actor_id.
approximate_age	opcional	Edad aproximada en años, de 18 a 90: los actores son adultos. Es obligatorio salvo que se proporcione from_actor_id.
name	obligatorio	Nombre que se muestra en list_actors.
aspect_ratios	opcional	Formatos que se crearán: 9:16 | 1:1 | 16:9; siempre incluye 9:16. Si se omite, se usan los tres. Los formatos que no superen la comprobación de identidad no se cobran y se indican en warnings.
from_actor_id	opcional	Deriva un nuevo actor personal de este actor (de la biblioteca o tuyo): el mismo rostro, género y edad, con una vista modificada mediante el encuadre, lo que sostiene, el entorno, description o style_reference. Omite gender y approximate_age.
framing	opcional	Tamaño del plano: close (predeterminado, de pecho para arriba), wide (de cintura para arriba, con las manos y espacio por encima) o full (de pie, de la cabeza a los pies). A partir de palabras, determina el encuadre del nuevo retrato; con from_actor_id, wide o full aleja la cámara. La vista se clasifica según el tamaño del rostro dibujado, y make_ugc la renderiza con presenter_framing de ese nombre. No se usa con style_reference ni portrait, cuya imagen determina el plano.
holding	opcional	Hasta 2 objetos que sostiene el presentador, uno en cada mano.
setting	opcional	La habitación o el fondo donde se coloca al presentador, descritos con palabras.
style_reference	opcional	Foto PNG o JPEG cuyo escenario, iluminación, ángulo de cámara, tamaño de plano y ropa seguirá el nuevo retrato: de pecho para arriba, de cintura para arriba o de cuerpo entero, como en la foto; un retrato con un encuadre más amplio que de pecho para arriba se convierte en una vista wide. Un recurso de imagen de esta cuenta (carga, importación desde URL o imagen encontrada, rights_confirmed). Sin from_actor_id, el rostro es nuevo y se basa en description; con él, se usa el rostro del actor de origen. Se rechaza sin cargo un retrato que se parezca a una persona de la foto.
portrait	opcional	Crea el actor a partir de tu propia imagen de retrato en lugar de generar una: un recurso de imagen PNG o JPEG de esta cuenta (rights_confirmed), con una proporción dentro del 2 % de 9:16 y exactamente un rostro que no esté cortado ni sea demasiado pequeño o demasiado grande. Se convierte en el retrato 9:16 del actor sin cargo; los otros formatos se editan a partir de él y se cobran como de costumbre. Se usa con gender y approximate_age; no se usa con description, style_reference ni from_actor_id.
quality	opcional	Calidad de imagen: medium | high. Si se omite, se usa medium. high genera el retrato más natural. El precio por imagen depende de este valor; quote lo muestra antes de cualquier cargo.

make_faceless. Inicia un video faceless terminado y de pago a partir de un guion o una descripción. Seleccionas entre 30 y 90 segundos; el video termina con su narración, dura al menos 25 segundos (en un explicativo, lo mismo que su narración) y como máximo un cuarto más que la duración seleccionada, sin superar nunca los 90 segundos. El video incluye un clip animado de apertura y escenas con imágenes. Los subtítulos están activados de forma predeterminada y se pueden desactivar.

Devuelve un run_id de inmediato; consulta get_run con sus poll.arguments hasta que el estado sea 'succeeded' (video_url) o 'failed'. attempt=2,3,… inicia una NUEVA ejecución con la misma entrada.

Field	Required	What it means
input_mode	obligatorio	'script' narra tu texto exacto; 'brief' redacta la narración a partir de una descripción breve. Envía exactamente uno de los campos script o brief, según este modo.
script	opcional	La narración, leída tal como está escrita. Obligatorio cuando input_mode es 'script'; debe omitirse cuando sea 'brief'.
brief	opcional	De qué trata el video; la narración se redacta a partir de esta descripción. Obligatorio cuando input_mode es 'brief'; debe omitirse cuando sea 'script'.
duration_seconds	obligatorio	Duración seleccionada, de 30 a 90 segundos, en un límite de fotograma de 1/25 s. El video termina con su narración y dura al menos 25 segundos (en un explicativo, lo mismo que su narración), normalmente como máximo un cuarto más que la duración seleccionada y 90 segundos; si la narración dura más, el video llega hasta el final. Si un video supera la duración seleccionada en más de 5 segundos, se indica en warnings[]. El cargo nunca supera la cotización. Se acepta un guion cuando su duración estimada es de 21 segundos hasta 5 segundos más que la duración seleccionada, con un máximo de 90.
style_reference	opcional	Imagen pública https cuyo estilo visual siguen las escenas.
character_reference	opcional	Imagen pública https de una persona o figura que se debe mantener coherente en todas las escenas.
character_details	opcional	Detalles visuales fijos de esa persona o figura, como el pelo, la ropa y los accesorios que no lleva; se mantienen en cada escena generada.
scene_images	opcional	Tus imágenes, cada una colocada en un intervalo de palabras o una cita de la narración.
captions	opcional	Subtítulos incrustados; activados de forma predeterminada.
transitions	opcional	Flash o fuga de luz en los cortes, con su sonido: en cada cambio de escena o en el más cercano a cada ancla (solo para script). Si se omite en un brief, se aplica un flash en cada cambio de escena; false indica cortes simples. Sin cargo adicional.
edit_sounds	opcional	Un sonido suave en cada cambio de escena, con el pico en el corte; template_sounds.edit lo selecciona. El precio no cambia.
template_sounds	opcional	false para no usar sonidos, o { flash, whoosh (fuga de luz), edit: name } de list_template_sounds.
music	opcional	Música de fondo bajo la voz, creada para este video; desactivada salvo que la solicites. "auto" toma el tono del guion; { mood } lo indica con tus propias palabras, como "calm lo-fi". 60 créditos por video, en una línea aparte de la cotización; solo se cobra si el video se entrega con música.
templates	opcional	Solo para script: como en make_ugc, una ranura puede mostrar tu recurso de imagen o video (asset_id, rights_confirmed). Gratis.
shots	opcional	Solo para script: 1-10 {id, anchor, action, asset_id?}, máximo 5 s cada uno.
scenes	opcional	Solo para script: como las escenas de make_ugc.
motion_style	opcional	Como motion_style de make_ugc; solo abarca el guion. Gratis.
moves	opcional	Solo para script: movimientos de list_moves basados en tus palabras: cada uno { name, anchor: { quote }, cover_words?, placement?, data? }. Cada movimiento se dibuja tal como indica su línea en list_moves; data recibe los campos que especifica. Si un movimiento no se puede dibujar con esas palabras o en este video, se indica en warnings[] y se omite; nunca se descarta sin avisar. Sus créditos aparecen en la cotización.
format	opcional	'explainer': un explicativo dibujado como caricatura, con un evento en cada palabra y un personaje principal en una esquina; solo para script. Se adapta a una secuencia de acciones concretas narradas por una sola voz: instrucciones paso a paso, cómo funciona algo, un flujo de trabajo, un recorrido por una herramienta, N errores o N maneras, con algo que mostrar en cada frase. El razonamiento sin acciones, un diálogo o una historia sobre personas no encajan bien. Cada cotización de un guion incluye explainer_fit: ofrece el formato cuando encaje; cuando no, indica el motivo y una versión reescrita como acciones antes de preguntar. El personaje principal se dibuja a partir de character_reference o character_details (su pose aparece en la cotización); de lo contrario, usamos uno nuestro, gratis. Una lista de elementos con nombre incluye una imagen de cada uno en su escena, una por cada elemento de la cotización; solo se cobra cuando se muestra. Sin voz, un guion en inglés se lee con nuestra voz más rápida.
pause_trim	opcional	Solo para script: como pause_trim de make_ugc, con el mismo valor predeterminado cuando se usan templates, scenes, shots o el formato explainer.
voice	opcional	Voz de narración: un nombre de list_voices con skill=make_faceless (kind faceless_voice). Si se omite, se usa narrator_en_wise_lady; para un explicativo en inglés, la voz más rápida. Elige una voz en el idioma de la narración: una voz puede leer cualquier idioma, con su propio acento. La API rechaza un nombre desconocido y una voz de make_ugc antes de cualquier cargo. Aquí no se acepta un voice_id sin procesar.

• Un video faceless no tiene presentador en cámara: la narración se reproduce sobre un clip animado de apertura y escenas con imágenes. Envía exactamente uno de los campos script y brief, el que indique input_mode.
• duration_seconds es un objetivo, no una duración a la que se alarga el video: el video termina con su narración, que dura al menos 25 segundos (en un explicativo, solo lo que dure la narración) y normalmente como máximo un cuarto más que duration_seconds y 90 segundos; una narración más larga llega hasta el final. Si un video supera la duración en más de 5 segundos, se indica en warnings[]. El cargo nunca supera la cotización.
• Los subtítulos omiten la puntuación, conservan los acentos y otros signos diacríticos, y muestran los números tal como están escritos. Con los subtítulos activados, el guion se comprueba con la fuente de los subtítulos antes de generar la voz; si la fuente no puede dibujar un carácter, la ejecución falla sin cargo.
• El idioma de la narración se detecta automáticamente.
• voice indica la voz de narración: elige un nombre de GET /v1/voices?skill=make_faceless. Si se omite, la narración se lee con narrator_en_wise_lady y un explicativo en inglés, con la voz más rápida. Elige una voz en el idioma de la narración. Un nombre desconocido, una voz de make_ugc y voice_id se rechazan antes de cualquier cargo: make_faceless solo usa las voces que aparecen en su lista.
• make_faceless siempre entrega videos en 1080p y 9:16. Si la generación faceless está desactivada en el servidor, ambas llamadas devuelven paid_render_disabled y no se cobra nada.
• Una ejecución fallida cuyo error empieza por story_not_planned se detuvo en el primer paso: no se pudo planificar la narración en ese intento. No se cobró nada y se puede volver a ejecutar la misma entrada con una nueva Idempotency-Key.

Para make_ugc y create_actor, el formato de salida depende de la solicitud y de la fuente. Los formatos admitidos son 9:16, 1:1, 16:9 y las resoluciones 720p, 1080p; si no se especifica, se usa 1080p en 9:16.

08

Flujos de trabajo

GET /v1/public/workflows enumera los métodos que se pueden ejecutar. Los métodos nativos son ugc-product-intro, ugc-faq-answer, faceless-explainer y product-image-story. website-proof-demo y kinetic-launch todavía no se pueden ejecutar y siguen en estado execution_blocked con sus motivos.

La ruta más corta con la CLI empieza con el ejemplo propio de un método. Solo plan-run consume créditos; todos los comandos anteriores son gratuitos. Edita el brief antes de crear el plan y conserva los pins del método.

clipwright workflow-show faceless-explainer > method.json
jq '{document: {v: 1, method: {method_id: .descriptor.id, version: .descriptor.version, content_digest: .descriptor.content_digest, capability_digest: .capabilities.content_digest}, brief: .descriptor.example.brief, beats: .descriptor.example.beats, claims: [], assets: []}}' method.json > create.json
clipwright plan-create --file create.json > plan.json
jq '{revision, content_digest}' plan.json > approval.json
clipwright plan-approve wfp_example --file approval.json
clipwright plan-quote wfp_example > quote.json
jq '{revision, content_digest, semantic_input_digest, quote_id, idempotency_key: "workflow-example:1"}' quote.json > launch.json
clipwright plan-run wfp_example --file launch.json
clipwright runs run_example

Reemplaza wfp_example por el plan_id de plan.json y run_example por el ID de ejecución que muestra plan-run. Una cotización vence cinco minutos después de emitirse, así que ejecuta plan-run poco después de plan-quote. Para product-image-story, carga cada foto con clipwright upload --json. La respuesta proporciona su upload_id y content_digest; cópialos directamente en el recurso. Añade un recurso por cada foto. El comando uploads devuelve la misma identidad para una carga anterior.

clipwright upload mug-front.jpg --json > upload.json
jq '{instance_id: "mug-front", asset_id: .upload_id, content_digest, anchor: {quote: "overall shape"}, provenance: "owner_supplied", rights: "owner_authorized", purpose: "product_proof"}' upload.json > asset.json

{
  "instance_id": "mug-front",
  "asset_id": "upl_00000000000000000000000000000000",
  "content_digest": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
  "anchor": {
    "quote": "overall shape"
  },
  "provenance": "owner_supplied",
  "rights": "owner_authorized",
  "purpose": "product_proof"
}

• Crea un plan propiedad de la cuenta, guarda revisiones y aprueba la revisión exacta y el content_digest. La planificación y la aprobación no tienen costo ni inician una renderización. Una revisión editada necesita una nueva aprobación.
• Para un plan aprobado, envía un POST con el cuerpo vacío a /v1/workflow-plans/{id}/quote. Usa su quote_id, revision, content_digest y semantic_input_digest en la solicitud de ejecución. Comprueba expires_at antes de iniciar una nueva compra; son metadatos de la cotización. Idempotency-Key debe coincidir con idempotency_key del cuerpo.
• Las cotizaciones de flujos de trabajo UGC indican en native_quote.quote.warnings que duration_estimate_sec y credits_estimate son estimaciones, no un precio fijo. El UGC corto entregado se cobra según sus price_lines sobre el video medido, redondeando cada una al segundo entero superior, por lo que un video más largo que el estimado cuesta más que la estimación. Lee credits_charged en la ejecución completada. Una cotización nativa con long_form_pricing usa, en cambio, los intervalos de aparición verificados del video entregado y la tarifa fijada al admitirlo, no la duración total del video. Siguen aplicándose las condiciones nativas por fallos.
• Siguen aplicándose la tarifa nativa y las reglas de fallos. Faceless duration_seconds selecciona la duración cuya cotización limita el cargo; la narración medida determina la duración entregada. La voz, los subtítulos y el guion exacto aceptado conservan su configuración nativa.
• Vincula cada imagen proporcionada con un instance_id distinto, un asset_id de carga propio y estable, content_digest, derechos, procedencia, propósito y un intervalo de palabras no superpuesto o una cita inequívoca. Reutiliza una carga en varias instancias; las URL firmadas temporales se resuelven al cotizar y al iniciar.
• La prueba original del producto ocupa tomas IMAGE compatibles. La apertura generada es ilustrativa. No están disponibles cuando son obligatorios una presentación de diapositivas exacta compuesta solo por imágenes fijas, una apertura solo con clientes ni diseños de escenas arbitrarios.
• Un protected_area es un rectángulo expresado en fracciones de la imagen de origen. La comprobación previa debe conservarlo durante el recorte, el movimiento PAN y los subtítulos. Se rechazan las imágenes cuya orientación o ubicación no pueda verificarse; una imagen generada nunca sustituye la prueba original obligatoria.
• Se rechazan los PNG protegidos con animación o fragmentos EXIF y los JPEG con cualquier segmento APP1 (EXIF/XMP). Exporta una copia estática y vertical sin esos metadatos. La cobertura usa el reloj de fotogramas nativo medido de 25 fps.
• La retención de las cargas y la URL firmada de 24 horas son límites independientes; una cotización no amplía ninguno de los dos. Las fuentes y firmas deben seguir disponibles para la renderización y la recuperación. La repetición aceptada conserva sus fuentes y firmas originales.
• Un inicio correcto devuelve el recibo y su Run nativo existente. Reintenta la misma solicitud aceptada para recuperar esa compra, incluso después de que caduque la cotización o deje de estar disponible la firma de la fuente. Consulta el progreso y el video entregado mediante GET /v1/runs/{id}.
• Los planes privados pertenecen a la cuenta del token.
• Para product-image-story, las escenas generadas y la imagen de apertura usan los dos primeros originales distintos de product_proof que cumplan los requisitos, según el orden de los recursos aceptados. El primero fija la forma del producto; el segundo aporta otra vista. La preparación del plan y la cotización nativa indican la cantidad seleccionada y que las ilustraciones generadas pueden diferir. Los originales adicionales conservan sus ubicaciones de imagen vinculadas exactas. La recuperación de un punto de control pagado anterior reutiliza sus escenas existentes con una advertencia explícita cuando no se puede verificar el condicionamiento con el producto original. Las revisiones y las propuestas, incluidas las propuestas conservadas y las revisiones posteriores, mantienen esa limitación de condicionamiento conocida, sin garantizar que las escenas o ubicaciones anteriores sobrevivan a la edición.
• Las escrituras rechazan los campos desconocidos y los documentos que superen los 256000 bytes JSON. Las lecturas aceptan campos y valores de enumeración futuros; los campos desconocidos dentro de un documento leído se conservan, de modo que un cliente antiguo rechaza un guardado no compatible en lugar de borrar la intención. Mantén sin cambios la narración sin procesar aceptada.
• Si se pierde la respuesta de un guardado, repite la misma solicitud explícita de base_version/document. Si ya se convirtió en el documento actual, el backend devuelve esa revisión sin restablecer la aprobación; si el documento actual es distinto, se produce workflow_conflict. SDK, MCP y CLI nunca aprueban, cotizan ni compran como efecto secundario de guardar.
• GET /v1/runs/{id} puede incluir workflow: su recibo inmutable, approved_plan, estado/advertencias nativos, actual_output, asset_placements, advisory beat_dispositions, validation_issues y creative_acceptance=not_reviewed. approved_plan omite brief.reference_profile, por lo que una consulta de estado no lo repite; lo que el plan no reproduce de la referencia aparece en las advertencias, y GET /v1/workflow-plans/{id} devuelve la revisión actual completa. La ejecución conserva la revisión comprada incluso después de que cambie el borrador. Una revisión o propuesta de toma nunca hereda el recibo de su antecesor.
• La liquidación faceless verificada proporciona el resumen criptográfico del artefacto, el formato y la duración medida, aunque falte geometría opcional posteriormente. Las ubicaciones requieren un punto de control intacto y vinculado a la cuenta/ejecución/solicitud; si falta la prueba, el valor es null y se incluye un problema de validación. Una lista de ubicaciones vacía verificada es []. La entrega UGC verificada proporciona el formato, la duración y el resumen criptográfico medidos del archivo final; el formato se determina a partir de las dimensiones medidas, no de la solicitud. El UGC sin prueba de bytes/formato, incluidas las ejecuciones antiguas, tiene actual_output=null con output_evidence_unavailable; su video_url nativa sigue siendo el resultado. La evidencia histórica no renueva una URL de descarga caducada ni demuestra la aceptación creativa humana.
• Los métodos del SDK son listWorkflows, getWorkflow, createWorkflowPlan, planReferenceRemake, getWorkflowPlan, saveWorkflowPlan, approveWorkflowPlan, quoteWorkflowPlan y runWorkflowPlan; getRun conserva la evidencia del flujo de trabajo. Los comandos de CLI son workflows, workflow-show, plan-create --file, plan-show, plan-save --file, plan-approve --file, plan-quote y plan-run --file. Estos comandos de flujo de trabajo imprimen JSON; los archivos tienen un límite de 1 MiB antes del análisis. Se puede editar un archivo de plan-show y pasarlo a plan-save para el mismo plan.

Ejemplo de cuerpo para POST /v1/workflow-plans/{id}/run: sustituye los campos de cotización por los de la cotización del plan aprobado y envía Idempotency-Key: workflow-example:1.

{
  "quote_id": "wq_example",
  "revision": 1,
  "content_digest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "semantic_input_digest": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "idempotency_key": "workflow-example:1"
}

09

Iniciar una ejecución

Una llamada de pago lleva un encabezado además de la clave: Idempotency-Key. POST /v1/skills/make_faceless/run y POST /v1/runs/{id}/revisions y POST /v1/runs/{id}/candidates y POST /v1/skills/make_ugc/run y POST /v1/skills/create_actor/run y POST /v1/workflow-plans/{id}/run y POST /v1/skills/generate_image/run y POST /v1/skills/generate_video/run y POST /v1/reference-analyses y POST /v1/creator-profiles y POST /v1/trend-searches lo requieren, y una llamada sin él se rechaza con 400 idempotency_key_required antes de que se cobre nada.

• Tú eliges la clave, y es lo único que permite distinguir un reintento de un segundo pedido. Sirve cualquier cadena única; consérvala mientras exista la posibilidad de que vuelvas a enviar la llamada.
• La misma clave con el mismo cuerpo devuelve la ejecución que ya inició y no vuelve a cobrar. Eso es lo que hace seguro un reintento normal.
• La misma clave con un cuerpo distinto se rechaza con 409 idempotency_key_reused. Usa una clave nueva para una solicitud nueva, en lugar de editar una solicitud con una clave ya utilizada.
• Para iniciar deliberadamente una ejecución nueva con la misma entrada —un reintento tras un fallo—, envía una clave nueva. La ejecución que ya pagaste permanece como está.
• @clipwright/sdk y @clipwright/mcp-server generan la clave por ti a partir del cliente y la entrada, y convierten attempt=2, 3 … en una clave nueva. Con HTTP sin intermediarios, tú eliges la clave.

10

Cuando falla una llamada

Cada rechazo incluye un objeto de error con un código y un mensaje. Qué hacer depende del tipo de rechazo, no del texto:

Rechazo	HTTP	¿Repetir la misma llamada?	Qué hacer	Cobro
rate_limited	429	sí, después de esperar	Es una limitación de velocidad, no un error: la respuesta indica cuántos segundos esperar, en Retry-After y en el cuerpo.	Nada. No se aceptó la llamada.
server_error	500, 502, 503	sí, después de esperar	El fallo está del lado del servidor. No inicies una segunda ejecución con una clave de idempotencia nueva: la misma llamada es el reintento.	No por esta respuesta. Se devuelve la retención de créditos de una ejecución que el servidor no pudo iniciar; una ejecución que sí se inició se cobra una sola vez, según su propio resultado.
insufficient_credits	402	no, devuelve la misma respuesta	Detente e informa a la persona del saldo y el precio; ambos aparecen en el cuerpo. Repetir no puede cambiar ninguno de los dos.	Nada. La llamada se rechazó antes de crear una ejecución o retener créditos.
debt_outstanding	402	no, devuelve la misma respuesta	Detente. Comprar créditos salda la deuda antes de que nada llegue al saldo y elimina el bloqueo.	Nada. La llamada se rechazó antes de crear una ejecución o retener créditos.
not_admitted	403	no, devuelve la misma respuesta	Detente. La cuenta no tiene acceso beta; ni un reintento ni una compra lo cambian. Contacta con soporte.	Nada. La llamada se rechazó antes de crear una ejecución o retener créditos.
edit_conflict	409	no, devuelve la misma respuesta	Detente. El borrador de la edición tiene una versión distinta de aquella contra la que se escribió el guardado; el cuerpo indica cuál. Lee el borrador: si ya contiene tu documento, un guardado anterior se completó. De lo contrario, aplica el cambio a lo que leíste y guarda con su versión.	Nada. La llamada se rechazó antes de crear una ejecución o retener créditos.
run_not_editable	409	no, devuelve la misma respuesta	Detente. La ejecución no tiene un borrador de edición que puedas leer o guardar. El cuerpo indica el estado y el motivo, los mismos que muestran las tomas de la ejecución.	Nada. La llamada se rechazó antes de crear una ejecución o retener créditos.
editing_closed	503	no, devuelve la misma respuesta	Detente. Las ediciones de pago no están habilitadas; el cuerpo indica el motivo. No se cobró nada ni se creó ninguna ejecución, y paid_edits en las tomas de la ejecución indica cuándo se habilitan.	Nada. La llamada se rechazó antes de crear una ejecución o retener créditos.
edit_ceiling_reached	409	no, devuelve la misma respuesta	Detente. El original ya tiene el máximo permitido de revisiones o de propuestas de toma (cada una se cuenta por separado), en curso o fallidas e incompletas; el cuerpo indica el límite, el recuento y las ejecuciones. Sigue una ejecución en curso con GET /v1/runs/{id} e inicia la siguiente cuando termine; soporte aumenta el límite de fallos de las revisiones después de un fallo nuestro.	Nada. La llamada se rechazó antes de crear una ejecución o retener créditos.
edit_invalid	422	no, devuelve la misma respuesta	Detente. El documento o la operación solicitada por una propuesta de toma infringe las reglas de la ejecución que edita; issues enumera cada problema en orden. Corrige la solicitud: las reglas aparecen en las tomas de la ejecución.	Nada. La llamada se rechazó antes de crear una ejecución o retener créditos.
workflow_invalid	400	no, devuelve la misma respuesta	Detente. Lee todos los problemas y advertencias y luego corrige el documento del flujo de trabajo. La aprobación, la cotización y el inicio de pago son llamadas explícitas independientes.	Nada. La llamada se rechazó antes de crear una ejecución o retener créditos.
workflow_conflict	409	no, devuelve la misma respuesta	Detente. Lee el plan guardado y compara su revisión y documento con tu solicitud original. Recupera un inicio incierto con la solicitud original y la clave de idempotencia; una clave nueva puede generar un segundo cobro.	Nada por esta llamada. Un inicio anterior que se haya completado se cobra una sola vez, según su propio resultado; la solicitud y la clave originales lo devuelven.
workflow_not_ready	409	no, devuelve la misma respuesta	Detente. Lee todos los problemas y advertencias. Resuelve los requisitos de preparación y luego aprueba y cotiza explícitamente la revisión elegida antes de iniciar una ejecución de pago con clave.	Nada. La llamada se rechazó antes de crear una ejecución o retener créditos.
client_error	400, 401, 403, 404, 409, 410, 413, 415, 422, 503	no, devuelve la misma respuesta	Detente. Se rechazó la solicitud en sí: lee el mensaje, corrige la llamada y vuelve a enviarla.	Nada por esta llamada: no creó ninguna ejecución ni retuvo créditos. Una ejecución iniciada anteriormente con el mismo Idempotency-Key (409 idempotency_key_reused) se cobra una sola vez, según su propio resultado.
Estos son todos los códigos que la API incluye en error.code. Un código que no hayas visto antes sigue correspondiendo a la fila anterior, porque la fila se determina por el estado:

• account_not_admitted
• actor_creation_limited
• actor_format_unavailable
• actor_generation_disabled
• actor_in_use
• actor_storage_unavailable
• actor_unavailable
• analysis_enqueue_failed
• aspect_conflict
• asset_cap_exceeded
• asset_ingest_cap_exceeded
• asset_not_found
• asset_not_ready
• assets_disabled
• creator_profile_limited
• creator_profile_not_found
• creator_url_unsupported
• debt_outstanding
• deletion_held
• edit_ceiling_reached
• edit_conflict
• edit_invalid
• editing_disabled
• editing_not_priced
• editing_window_not_set
• feedback_limited
• generations_disabled
• generations_marking_pending
• idempotency_key_required
• idempotency_key_reused
• ingest_enqueue_failed
• insufficient_credits
• insufficient_scope
• internal_error
• invalid_image
• invalid_request
• malformed_body
• no_changes
• not_found
• paid_render_disabled
• payload_too_large
• rate_limited
• reference_analysis_disabled
• reference_analysis_limited
• reference_analysis_not_found
• reference_not_analyzable
• reference_not_usable
• reference_url_unsupported
• rejected_field
• revision_needs_generated_unit
• rights_not_confirmed
• run_media_in_use
• run_not_editable
• run_not_finished
• run_not_found
• script_encoding_lost
• source_aspect_mismatch
• source_not_usable
• trend_search_limited
• trend_search_not_found
• trends_unavailable
• unauthorized
• unknown_field
• unsupported_combination
• unsupported_media_type
• unusable_source
• upload_cap_exceeded
• upload_digest_mismatch
• upload_expired
• upload_in_use
• upload_not_finished
• upload_size_mismatch
• upstream_error
• url_fetch_busy
• url_fetch_failed
• url_fetch_rate_limited
• url_fetch_refused
• url_import_disabled
• workflow_conflict
• workflow_invalid
• workflow_not_ready

11

Límites

• 60 solicitudes de pago y 300 gratuitas cada 60 segundos. El intervalo se cuenta por cuenta, no por clave, así que las claves adicionales no aumentan el rendimiento.
• Se crean a la vez por cuenta 3 videos con presentador y 2 videos sin rostro; el resto queda en cola y no se rechaza. Cuando muchas cuentas renderizan a la vez, una ejecución también puede tener que esperar su turno detrás de las demás.
• Si se rechaza una solicitud por límite de frecuencia, el tiempo de espera en segundos se indica en Retry-After y en el cuerpo. Respeta el valor mayor de los dos.
• 99 inserciones por clip y un máximo de 16 apariciones del actor entre ellas. Ambas cantidades se calculan a partir de los índices de palabras que envías, así que una solicitud que pida más se rechaza antes de que se cobre nada.
• cover_words indica cuántas palabras habladas cubre una inserción, contadas desde la primera palabra de su ancla. La inserción termina donde empieza la primera palabra no cubierta, así que dos inserciones cuyas coberturas se tocan son contiguas y no dejan ninguna toma del actor entre ellas.
• La proporción de palabras que dejas sin cubrir determina qué proporción del clip muestra un rostro, y no cambia con la velocidad de la voz. La longitud de las palabras sí varía: con un guion de 560 palabras, pedir un 19% da aproximadamente entre 16 y 22; con un guion más corto, la variación es mayor, y otra voz también cambia el resultado.
• Dos opciones de una sola palabra cambian el precio, no solo el aspecto. Una inserción anclada en la palabra 0 incluye el silencio anterior a la primera palabra; si se ancla en la palabra 1, queda una aparición adicional del actor, y cada aparición aumenta el precio. La cobertura que llega hasta la última palabra se extiende hasta el final del clip y elimina la aparición de cierre del mismo modo.
• Una cotización informa la proporción como estimatedFaceWordShare. Lee ese campo; no dividas estimatedFaceSeconds entre estimatedTotalDurationSec. Esos dos valores responden a preguntas distintas: el primero es la reserva que mantenemos en el extremo lento del rango de habla; el segundo es la duración prevista del clip, y su cociente no representa la proporción de nada.

12

Lo que esta API nunca hará

• Publicar nada. Devolvemos un archivo y un enlace firmado; tú decides dónde va.
• Cancelar una ejecución iniciada. No hay ningún endpoint para ello.
• Aceptar estos campos de make_ugc: character, broll_url, disclosure_overlay, webhook_url. Se rechazan por nombre antes de cualquier cargo; no se aceptan para luego ignorarlos silenciosamente.
• Cambiar el formato o la resolución que solicitaste sin avisarte. Una discrepancia se ajusta con una advertencia o se rechaza antes de la llamada de pago.
• Devolverte una llamada. No hay webhooks: consulta la ejecución con GET /v1/runs/{id}.
• Mostrar una clave por segunda vez ni recuperarla de una copia de seguridad.

13

También conviene saber

• Advertencias, no silencio. Todo lo que no hayamos podido respetar aparece con su nombre en warnings[] en la misma ejecución. Ningún parámetro desaparece sin una explicación.
• Un servidor MCP. @clipwright/mcp-server expone el mismo contrato como herramientas, y tools/list es la versión legible por máquinas de esta página.