Clipwright

API de Clipwright

Una API HTTP que convierte un guion en un video UGC con sincronización de labios. Está diseñada para ser manejada por un agente: cada llamada es una única solicitud JSON, cada rechazo indica qué hacer a continuación y nada se publica en ningún lugar. Cada palabra de esta página también es un archivo markdown en https://clipwright.io/docs.md, y un breve contrato para agentes en https://clipwright.io/llms.txt.

Autenticación

Cada llamada va a https://api.clipwright.io y lleva la clave en un encabezado:

Authorization: Bearer cw_your_key_here

• Las claves comienzan con cw_ y se muestran una sola vez, cuando se emiten. Solo conservamos un resumen, por lo que una clave perdida se reemplaza, nunca se recupera.
• Emite y revoca claves en el panel de control en https://app.clipwright.io/api-keys. 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 cualquier cosa.

03

Lo que cuesta

• make_ugc desde un guion simple: 30 créditos por cada segundo de video terminado, redondeado al segundo completo.
• make_ugc con segmentos o inserciones: 10 créditos por cada segundo en que un rostro esté en pantalla, y al menos 400 créditos por un video que entregamos. Los segundos sin rostro no cuestan nada, y una ejecución que no entrega ningún archivo no cuesta nada en absoluto, incluso cuando el proveedor ya fue pagado. El tiempo de rostro se suma en todo el video y se redondea una sola vez, no por segmento. Estos campos requieren calificación de formato largo en el despliegue; donde esté desactivada, se rechazan por nombre antes de cualquier cargo.
• create_actor con calidad media: 10 créditos por el retrato y 10 por cada formato adicional.
• create_actor con calidad alta: 20 créditos por el retrato y 20 por cada formato adicional.
• Los créditos se compran en paquetes: 1000 créditos por $10.00, un solo pago, sin suscripción.

Pregunta antes de gastar: el endpoint de cotización de cualquiera de las habilidades no cobra nada. Lo que vale su respuesta difiere según la habilidad.

• make_ugc: la cotización es una estimación basada en las palabras del guion. El cargo sigue lo que se midió en el video terminado — su duración en el medidor de guion simple, sus segundos de rostro en el medidor de rostro — por lo que la factura puede estar por encima o por debajo de la cotización.
• create_actor: la cotización fija el precio de cada formato que solicitaste, que es lo máximo que puedes pagar. Se te cobra por el retrato y por las variantes realmente publicadas; un formato que no salió se menciona en warnings[] y no cuesta nada.

Lo que cuesta una ejecución fallida también difiere según la habilidad:

• make_ugc desde un guion simple: una ejecución que falló después de que el trabajo de entrega llegó al proveedor se cobra. Una que falló antes no cuesta nada, y tampoco cuesta una que detuvimos, perdimos o rechazamos nosotros mismos, incluso cuando el proveedor ya fue pagado. En el medidor de rostro, ningún fallo se cobra.
• create_actor: una ejecución fallida no cuesta nada en absoluto, incluso cuando el proveedor ya fue pagado, porque ningún actor llegó a ti.

04

Endpoints

Endpoint	Cuesta créditos	Qué hace
GET /health	no	Estado de la propia API. Responde sin clave.
GET /v1/voices	no	Voces que puedes nombrar en voice o voice_id.
GET /v1/account	no	Saldo, deuda y retenciones de la cuenta detrás de la clave.
POST /v1/skills/make_ugc/quote	no	Cotiza una llamada make_ugc con esta entrada. No cobra nada.
GET /v1/runs/{id}	no	Estado de una ejecución de cualquier habilidad, sus advertencias y su url de video.
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 su entrada, sin clave.
GET /v1/actors	no	Actores guardados en la cuenta, con el id que acepta make_ugc.
DELETE /v1/actors/{id}	no	Olvida un actor guardado. Un actor usado por una ejecución en vivo se conserva.
GET /v1/actors/{id}/defaults	no	Lee la política predeterminada del actor guardado para personas en inserciones.
POST /v1/actors/{id}/defaults	no	Establece la política predeterminada del actor guardado para personas en inserciones. Una ejecución puede anularla.
POST /v1/skills/create_actor/quote	no	Cotiza una llamada 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	Toma bytes de imagen y devuelve la url https que aceptan make_ugc y create_actor.

Una ejecución de cualquiera de las habilidades se lee desde el mismo lugar, GET /v1/runs/{id}, y pasa por estos estados: queued, generating, scripting, tts, avatar, compositing, uploading, succeeded, failed.

05

Habilidades y su entrada

make_ugc. Inicia la generación de un video UGC con sincronización de labios. Proporciona un guion dentro del límite de texto del modelo de voz seleccionado; el actor proviene de actor_id (un actor guardado de list_actors) o image; de lo contrario, se usa el actor predeterminado. El formato y la resolución siguen la solicitud y la fuente, con valor predeterminado de 1080x1920. Los subtítulos son OPCIONALES: pregunta primero al usuario. Los campos que el renderizador aún no respeta llevan una nota NO HONRADO AÚN en su propia descripción — léela en lugar de adivinar.

Llama a quote_ugc antes de generar y muestra el costo. Esto NO espera el video: inicia la ejecución y devuelve un run_id INMEDIATAMENTE. DEBES luego consultar get_run con ese run_id hasta que el estado sea 'succeeded' (video_url) o 'failed'. Una ejecución 'failed' cuyo trabajo de proveedor pagado aún conservamos puede volver a 'queued' y alcanzar 'succeeded' más tarde; cuando eso ocurra, se menciona en warnings[]. Pasa attempt=2,3,… para iniciar deliberadamente una NUEVA ejecución para la misma entrada (reintento después de un fallo).

Campo	Obligatorio	Qué significa
script	opcional	Las palabras que dice el actor; obligatorio a menos que segments proporcione el texto hablado. Los segmentos y las inserciones ancladas a texto requieren calificación de formato largo en el servidor. Límites de guion por modelo de voz: eleven_v3: 5000 caracteres; eleven_flash_v2_5: 10000 caracteres; eleven_turbo_v2_5: 10000 caracteres. El recuento incluye espacios, etiquetas de audio y marcas de acento; los emoji pueden contar como dos caracteres. No hay límite de recuento de palabras. La duración y el precio son estimaciones hasta que se miden. Acento ruso: escribe la vocal acentuada en mayúscula dentro de una palabra en minúsculas ("потОм", "зАмок") y eleven_v3 la recibe como la marca de acento U+0301 ("пото́м"); una marca escrita directamente se conserva. Una mayúscula al inicio de una palabra sigue siendo mayúscula, y una palabra con una segunda mayúscula o una consonante mayúscula en su interior (todo en mayúsculas, "ВУЗы") se deja como está. Una sola vocal mayúscula dentro de una palabra siempre se lee como acento, así que escribe "Яндекс Еда", no "ЯндексЕда". Informa a los usuarios que escriben en ruso que pueden marcar el acento de esta manera. eleven_flash_v2_5 y eleven_turbo_v2_5 cuestan menos pero leen mal las marcas de acento: las mayúsculas les llegan sin cambios.
segments	opcional	Segmentos ordenados de actor e imagen; requiere calificación de formato largo en el servidor, captions=false y 1080p. Los medios de imagen requieren broll_policy=anyone explícito.
inserts	opcional	Inserciones de imagen ancladas a texto sobre la narración completa, cada una cubriendo cover_words palabras habladas desde su ancla; requiere calificación de formato largo en el servidor, captions=false, 1080p y broll_policy=anyone explícito.
person	opcional	NO HONRADO AÚN: person no se honra aún: esta solicitud usa el actor predeterminado; elige actor_id de list_actors o proporciona image para seleccionar un rostro diferente
actor_id	opcional	ID de actor Clipwright guardado de list_actors. Elige actor_id, image o person; no los combines. Sin voice o voice_id, la voz sigue el género del actor. No lo combines con actor_gender.
image	opcional	Url https pública de la foto del actor (PNG, JPEG o WebP, hasta 10 MB). Un archivo en disco pasa primero por upload_image (POST /v1/uploads) — pasa la url que devuelve. Una fuente que no podemos usar — host privado o de bucle local, http, inalcanzable, con redirección, de más de 10 MB, o que no sea uno de esos tipos de imagen — se rechaza (unusable_source) antes de cualquier cargo. No detectamos el género del rostro: pasa actor_gender o voice, o se usa la voz masculina predeterminada con una advertencia.
actor_gender	opcional	Género del rostro en image: female | male. Solo con image: elige la voz predeterminada de ese género (female: sarah, male: george). Se rechaza con actor_id (su género se conoce) y sin image. Una voice o voice_id explícita gana y la respuesta advierte que actor_gender no cambió nada.
name	opcional	NO HONRADO AÚN: name no se honra aún: no llega al renderizador
broll_policy	opcional	SOLO ALMACENADO: Política guardada para B-roll: anyone permite personas incluido el actor; no_actor excluye al actor; no_people excluye a todas las personas, incluidas las manos. La generación de medios segmentados está cerrada. Esta configuración solo se almacena y no tiene efecto en videos solo de actor. La anulación de la ejecución gana sobre el predeterminado del actor de la cuenta; de lo contrario, no_people.
captions	opcional	NO HONRADO AÚN: subtítulos solicitados pero no renderizados en este prototipo (etapa-B)
caption_style	opcional	NO HONRADO AÚN: caption_style no se honra: los subtítulos no se renderizan en este prototipo (etapa-B)
look	opcional	NO HONRADO AÚN: look no se honra aún: no llega al renderizador
aspect_ratio	opcional	Formato de salida: 9:16 | 1:1 | 16:9. Omitido significa 9:16, y una fuente de otra forma se ajusta a 9:16 con una advertencia — pásalo explícitamente siempre que pases image. Un desajuste superior al 15% entre la solicitud y la fuente se rechaza (aspect_conflict) antes de cualquier cargo.
resolution	opcional	Resolución de salida: 720p | 1080p | 4k (lado corto 720 / 1080 / 2160 px). Omitido significa 1080p.
voice	opcional	Nombre de voz de list_voices. Presets seleccionados: owner_ru_clone | sarah | george | eric | daria_ru_female (owner_ru_clone es la voz clonada rusa). La API rechaza un nombre que list_voices no devuelve, antes de cualquier cargo. Omitido significa 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. Mutuamente excluyente con voice_id.
voice_id	opcional	ID de voz crudo del proveedor (16–32 letras y dígitos) para una voz fuera del catálogo. Se verifica de forma diferida: un id desconocido falla la ejecución, no la solicitud. Mutuamente excluyente con voice.
tts_model	opcional	Modelo de voz: eleven_v3 | eleven_flash_v2_5 | eleven_turbo_v2_5. Omitido significa el modelo del preset elegido (list_voices lo muestra; cada preset habla con eleven_v3) o eleven_v3 para un voice_id crudo. eleven_v3 es el más expresivo y el único que lee 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 baratas para idiomas distintos del ruso. Límites de guion por modelo de voz: eleven_v3: 5000 caracteres; eleven_flash_v2_5: 10000 caracteres; eleven_turbo_v2_5: 10000 caracteres. El recuento incluye espacios, etiquetas de audio y marcas de acento; los emoji pueden contar como dos caracteres. No hay límite de recuento de palabras. La duración y el precio son estimaciones hasta que se miden.
disclosure_overlay	opcional	Valores aceptados: true | false.
background	opcional	Valores aceptados: white | blur | contain.

create_actor. Crea un actor personal para esta cuenta a partir de palabras que describen a un adulto ficticio: un retrato 9:16 con exactamente un rostro, más los otros formatos solicitados editados a partir de él. Devuelve un run_id inmediatamente; consulta get_run hasta '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. Cuando la generación está desactivada, la llamada falla con actor_generation_disabled.

Campo	Obligatorio	Qué significa
description	obligatorio	Palabras que describen a un adulto ficticio: apariencia, vestimenta, entorno. Nombrar a una persona real o un parecido con una se rechaza antes de cualquier cargo (actor_prompt_refused).
gender	obligatorio	female | male. Fija el género del actor y la voz predeterminada de los videos con este actor.
approximate_age	obligatorio	Edad aproximada en años, de 18 a 90: los actores son adultos.
name	obligatorio	Nombre que se muestra en list_actors.
aspect_ratios	opcional	Formatos a crear: 9:16 | 1:1 | 16:9, incluyendo siempre 9:16. Si se omite, significa los tres. Los formatos que fallan la verificación de identidad no se cobran y se nombran en las advertencias.
quality	opcional	Calidad de imagen: medium | high. Si se omite, significa medium. El precio por imagen depende de esto; la cotización lo muestra antes de cualquier cargo.

El formato de salida sigue la solicitud y la fuente. Los formatos admitidos son 9:16, 1:1, 16:9 y resoluciones 720p, 1080p, 4k; el silencio significa 1080p en 9:16.

06

Iniciando una ejecución

Una llamada de pago lleva un encabezado además de la clave: Idempotency-Key. POST /v1/skills/make_ugc/run y POST /v1/skills/create_actor/run lo requieren, y una llamada sin él se rechaza con 400 idempotency_key_required antes de que se cobre cualquier cosa.

• Tú eliges la clave, y es lo único que distingue un reintento de un segundo pedido. Cualquier cadena única sirve; consérvala mientras puedas reenviar la llamada.
• La misma clave con el mismo cuerpo devuelve la ejecución que ya inició y no cobra nada una segunda vez. Eso es lo que hace seguro un reintento ordinario.
• La misma clave con un cuerpo diferente se rechaza con 409 idempotency_key_reused. Toma una clave nueva para una solicitud nueva en lugar de editar una solicitud bajo una clave ya gastada.
• Para iniciar deliberadamente una ejecución nueva con la misma entrada — un reintento después de un fallo — envía una clave nueva. La ejecución que ya pagaste permanece donde está.
• @clipwright/sdk y @clipwright/mcp-server construyen la clave por ti a partir del cliente y la entrada, y convierten attempt=2, 3 … en una nueva. Sobre HTTP simple, la clave es tuya para elegir.

07

Cuando una llamada falla

Cada rechazo lleva un objeto de error con un código y un mensaje. Qué hacer con él se deduce del tipo de rechazo, no del texto:

Rechazo	HTTP	¿Repetir la misma llamada?	Qué hacer
rate_limited	429	sí, después de la espera	Contrapresión, no un error: la respuesta nombra los segundos a esperar, en Retry-After y en el cuerpo.
server_error	500, 502, 503	sí, después de la espera	El fallo está en el lado del servidor. No inicies una segunda ejecución con una clave de idempotencia nueva: la misma llamada es el reintento.
insufficient_credits	402	no, da la misma respuesta	Detente y dile a la persona el saldo y el precio; ambos están en el cuerpo. Repetir no puede cambiar ninguno.
debt_outstanding	402	no, da la misma respuesta	Detente. Comprar créditos liquida la deuda antes de que cualquier cosa llegue al saldo, y eso levanta el bloqueo.
not_admitted	403	no, da la misma respuesta	Detente. La cuenta no tiene acceso beta; ni un reintento ni una compra cambian eso. Pregunta al operador.
client_error	400, 401, 404, 409, 413, 415	no, da la misma respuesta	Detente. La solicitud en sí fue rechazada: lee el mensaje, corrige la llamada y luego envíala de nuevo.

Estos son todos los códigos que la API pone en error.code. Un código que no hayas visto antes sigue su fila arriba, porque la fila se elige por el estado:

• account_not_admitted
• actor_creation_limited
• actor_format_unavailable
• actor_generation_disabled
• actor_in_use
• actor_storage_unavailable
• actor_unavailable
• aspect_conflict
• debt_outstanding
• idempotency_key_required
• idempotency_key_reused
• insufficient_credits
• internal_error
• invalid_image
• invalid_request
• malformed_body
• not_found
• paid_render_disabled
• payload_too_large
• rate_limited
• rejected_field
• script_encoding_lost
• unauthorized
• unknown_field
• unsupported_media_type
• unusable_source
• upload_cap_exceeded
• upstream_error

08

Límites

• 60 solicitudes de pago y 300 gratuitas por 60 segundos. La ventana se cuenta por cuenta, no por clave, así que las claves adicionales no compran más rendimiento.
• 3 renderizados se ejecutan a la vez por cuenta; el resto se pone en cola y no se rechaza.
• Un rechazo por límite de velocidad nombra los segundos a esperar en Retry-After y en el cuerpo. Respeta el mayor de los dos.
• 49 inserciones por clip, y como máximo 6 apariciones del actor entre ellas. Ambos se cuentan desde los índices de palabras que envías, así que una entrada que pida más se rechaza antes de que se pague cualquier cosa.
• cover_words dice cuántas palabras habladas cubre una inserción, contadas desde la primera palabra de su ancla. La inserción termina donde comienza la primera palabra no cubierta, así que dos inserciones cuyas coberturas se encuentran son adyacentes y no dejan ninguna toma del actor entre ellas.
• La proporción de palabras que dejas sin cubrir decide la proporción del clip que muestra una cara, y no se mueve con la velocidad de la voz. La longitud de las palabras sí varía: con un guion de 560 palabras, pedir 19% entregó de 16 a 22 en novecientas noventa y siete ejecuciones simuladas de mil, y se mantuvo dentro de 15 a 24 en cincuenta mil. Esos números se midieron con la voz de este perfil y a esa longitud; un guion más corto se dispersa más, y una voz diferente los mueve.
• Dos opciones de una sola palabra cambian el precio, no solo el aspecto. Una inserción anclada en la palabra 0 posee el silencio antes de la primera palabra; anclada en la palabra 1 deja una aparición extra del actor, y cada aparición es un trabajo de pago separado. La cobertura que alcanza la última palabra lleva el clip a su fin y elimina la aparición final de la misma manera.
• Una cotización informa la proporción como estimatedFaceWordShare. Lee ese campo; no dividas estimatedFaceSeconds por estimatedTotalDurationSec. Esos dos responden preguntas diferentes — el primero es la reserva que mantenemos en el extremo lento del rango de habla, el segundo es cuánto tiempo se espera que dure el clip — y su proporción no es la proporción de nada.

09

Lo que esta API nunca hará

• Publicar nada. Devolvemos un archivo y un enlace firmado; a dónde va es decisión tuya.
• Cancelar una ejecución iniciada. No hay endpoint para eso: una vez que el proveedor tiene el trabajo, detenerlo en nuestro lado no lo desgastaría.
• Aceptar estos campos: character, broll_url, webhook_url. Se rechazan por nombre antes de cualquier cargo, no se aceptan y se ignoran silenciosamente.
• Cambiar el formato o la resolución que pediste sin decirlo. Una discrepancia se corrige con una advertencia o se rechaza antes de la llamada de pago.
• Llamarte de vuelta. No hay webhooks: lee la ejecución con GET /v1/runs/{id}.
• Mostrar una clave una segunda vez, o recuperar una de una copia de seguridad.

10

También vale la pena saber

• Advertencias, no silencio. Cualquier cosa que no pudiéramos honrar vuelve en warnings[] en la misma ejecución, nombrada. Un parámetro nunca desaparece sin una línea al respecto.
• Un servidor MCP. @clipwright/mcp-server expone el mismo contrato como herramientas, y su tools/list es la forma legible por máquina de esta página.