Un plan práctico para una API de generación de video UGC con IA: cómo convertir un brief de producto en decenas de anuncios verticales de estilo creador, con guiones, imágenes de persona, clips de video con audio nativo, límites de cola, controles de calidad y una divulgación clara de la IA, con código de peticiones en Python y Node.
Hace tiempo que las marcas dejaron de confiar en los anuncios de estudio muy pulidos, y los espectadores dejaron de verlos aún antes. Lo que hace que el dedo se detenga es una mujer en su cocina explicando, con sus propias palabras, por qué un sérum por fin le funcionó. Eso es la publicidad de estilo UGC (contenido generado por usuarios), y por eso los equipos de rendimiento quieren ahora una API de generación de video UGC con IA en lugar de una hoja de cálculo llena de creadores esperando muestras de producto.
Este artículo describe un pipeline que puedes construir esta semana. Entra un brief de producto y salen montones de anuncios verticales de estilo creador. Obtienes código de peticiones que funciona en Python y Node, los límites reales de la API para desarrolladores de PicassoIA, una tabla con lo que hace cada modelo y las comprobaciones que mantienen los anuncios automáticos honestos y alineados con la marca.
Cualquier especialista en marketing de rendimiento conoce el ciclo. Sale una creatividad, el gasto aumenta y, en cuestión de semanas, la audiencia la ha visto demasiadas veces y los resultados caen. La solución es más creatividad, y no un poco más. Una prueba seria cruza ganchos, personas, escenarios y duraciones, así que cinco ganchos, cuatro personas y tres escenarios ya son 60 variantes antes de tocar la llamada a la acción.
Contratar creadores humanos para esa matriz significa briefs, envíos, rondas de comentarios y una larga espera. Pedirle a un editor que recorte sesenta versiones a mano significa que el trabajo se hace una vez por trimestre en lugar de cada semana.
💡 Consejo: Trata la creatividad como inventario. Si un lote nuevo tarda tres semanas en llegar, siempre estarás usando los ganadores de ayer.
Así se comparan los dos enfoques en la práctica:
| Flujo de trabajo manual con creadores | Pipeline impulsado por API | |
|---|---|---|
| Variantes por ronda de pruebas | Unas pocas, limitadas por las reservas | Decenas, limitadas por tu matriz |
| Plazo de entrega | Días o semanas | Minutos por clip |
| Coherencia entre variantes | Depende de cada creador | Lo define tu plantilla |
| Cambiar una afirmación sobre el producto | Volver a grabar o recortar | Edita una línea y vuelve a ejecutar |
| Esfuerzo de revisión | Por video, largo | Por lote, revisiones puntuales |
Reemplaza los clics. Un panel sirve para un solo clip, pero nadie quiere pegar sesenta prompts en un formulario. Con una API, el brief vive en una hoja de cálculo, en un feed de productos o en una fila de una base de datos, y un script convierte cada fila en una petición.
El trabajo es asíncrono: creas una predicción, la consultas y luego descargas el archivo terminado. La documentación para desarrolladores no describe webhooks, así que el sondeo es todo el mecanismo, lo que mantiene pequeña la integración.
Los desencadenantes habituales de una ejecución por lotes son estos:
Una API reemplaza la producción, no el criterio. Alguien sigue decidiendo qué afirmaciones son ciertas y qué clips son lo bastante buenos para publicarse.
Piensa en cuatro etapas, cada una con una entrada y una salida. Cuando una etapa falla, reintentas solo esa etapa, nunca toda la cadena.
| Etapa | Entrada | Salida |
|---|---|---|
| Guion | Brief del producto y tipo de gancho | 10 a 15 segundos de texto hablado |
| Fotograma de persona | Prompt de persona y escenario | Una imagen fija |
| Video | Imagen fija más prompt de movimiento | Un clip con audio |
| Revisión | Clip más metadatos | Aprobado o rechazado |
Usa cualquier modelo de lenguaje para escribir las frases, porque la API de video no se preocupa de dónde vienen las palabras. Dale una forma rígida: un gancho en los primeros dos segundos, un problema, una prueba y una llamada a la acción.
El UGC parece real porque es breve y concreto. "Dejé de comprar tres productos y me quedé con este" le gana a "el mejor sérum de la historia" todas las veces. Pide una docena de ganchos por producto y quédate con los cinco que suenan como una persona hablando en voz alta.
💡 Consejo: Una afirmación por guion. Cada afirmación extra es otra frase que debes verificar antes de publicar nada.
El primer fotograma decide cómo se ve todo el clip, porque el modelo de video anima a partir de él. Usa PicassoIA Image para generar el fotograma de la persona: alguien en una habitación de uso cotidiano, con luz de ventana, encuadre a mano y un producto sin marca en la mano.
Cuando el producto real deba aparecer, recurre a PicassoIA Image Editor Pro. Acepta de una a cuatro imágenes de entrada, así que puedes colocar tu packshot real en la escena y mantener la etiqueta exacta.
Escribe los prompts como un fotógrafo: lente, dirección de la luz, textura de la piel y de la tela. Descarta el aspecto brillante. El UGC quiere habitaciones imperfectas y luz natural.
Introduce el fotograma en Seedance 2.5 Lite con un prompt de movimiento que diga qué hace y qué dice la persona a lo largo del clip. La opción save_audio viene activada por defecto, así que el habla y el sonido de la habitación llegan dentro del archivo en lugar de convertirse en un paso separado del pipeline.
Describe la acción en orden: levanta el frasco, echa un vistazo a la lente, dice la frase, sonríe. Ajusta también el guion al clip. Un video de diez segundos admite unas 25 a 30 palabras habladas a un ritmo natural, así que una frase más larga se acelerará o quedará cortada.
Mantén el movimiento de cámara al mínimo. Una ligera deriva de cámara en mano es la firma del UGC, y los movimientos cinematográficos intensos rompen la ilusión.
Descarga el clip, revísalo y súbelo a tu plataforma de anuncios con un nombre que codifique la variante, como question_kitchen_10s. Ese nombrado es lo que hace legibles los resultados después, cuando por fin puedes decir que la persona de la cocina con el gancho de pregunta superó a todo lo demás. Registra el nombre de la variante, el prompt, la semilla, el modelo y el id de la predicción en una fila por clip, y tu hoja de cálculo se convertirá en la memoria de toda la campaña.
En el momento de escribir esto, la API de PicassoIA expone cuatro modelos. Las entradas que aparecen abajo proceden de la documentación pública para desarrolladores.
| Modelo | Función en un pipeline UGC | Entradas destacadas |
|---|---|---|
| PicassoIA Image | Imagen fija de persona y escena | prompt |
| PicassoIA Image Editor Pro | Colocar tu producto real en una escena | prompt, images (de 1 a 4) |
| PicassoIA Video | De texto o imagen a video | resolution (480p, 720p, 1080p), duration, seed |
| Seedance 2.5 Lite | De imagen a video con audio | image, last_frame_image, duration (5, 10, 15), resolution (480p, 720p) |
Dos detalles importan para los anuncios. En PicassoIA Video, la duración máxima depende de la resolución: hasta 20 segundos en 480p, hasta 10 en 720p y hasta 5 en 1080p. En Seedance 2.5 Lite, la last_frame_image opcional te permite fijar dónde termina el clip, lo que resulta útil cuando el último fotograma debe mostrar el producto.
💡 Consejo:
aspect_ratiotoma por defecto el valormatch_input_imagecuando pasas una imagen. Tu imagen fija decide si el anuncio es vertical o cuadrado, así que revisa la forma del fotograma de persona antes de gastar un trabajo de video en él.
El catálogo más amplio vive en la app web y no en la API. Ahí encontrarás voces dedicadas y herramientas para que un rostro hable en los casos en que el audio nativo no basta.
Una división práctica: deja que la API produzca la mayor parte de tus clips con audio nativo y pasa los cinco o diez que mejor rinden a la app para pulir la voz y la sincronización labial.
Todo se envía a https://api.picassoia.com/v1, y cada petición lleva una cabecera Authorization: Bearer pia_sk_…. Crea la clave secreta en la página de API de tu cuenta. Una cuenta puede tener dos a la vez, así que rota las claves creando la nueva antes de borrar la antigua.
Guarda la clave secreta en una variable de entorno de tu servidor. Nunca la incluyas en un paquete de navegador ni en una app móvil.
💡 Comprueba primero el acceso: la documentación indica que las predicciones no consumen créditos por ahora, pero crear una devuelve
403 plan_requiredsi tu plan no incluye acceso a la API. Envía una única petición de prueba antes de diseñar nada en torno a la API.
El endpoint para un trabajo nuevo es POST /v1/models/{owner}/{name}/predictions, con tus campos envueltos en un objeto input. La respuesta incluye un id, un status (starting, processing, succeeded, failed o canceled) y un output, que es una URL o una lista de URL.
El sondeo usa GET /v1/predictions/{id}. El campo eta.next_poll_in_seconds te indica cuándo merece la pena hacer la siguiente consulta, así nunca bombardeas el endpoint.
import os, time, requests
API = "https://api.picassoia.com/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['PICASSOIA_TOKEN']}"}
def run(model, payload):
r = requests.post(f"{API}/models/{model}/predictions",
json={"input": payload}, headers=HEADERS)
pred = r.json()
if not r.ok:
raise RuntimeError(f"{pred['code']}: {pred['detail']}")
while pred["status"] not in ("succeeded", "failed", "canceled"):
time.sleep((pred.get("eta") or {}).get("next_poll_in_seconds", 2))
pred = requests.get(pred["urls"]["get"], headers=HEADERS).json()
if pred["status"] != "succeeded":
raise RuntimeError(pred["error"] or pred["status"])
return pred["output"]
def first(output):
return output[0] if isinstance(output, list) else output
def make_ad(brief):
frame = first(run("picassoia/picassoia-image", {"prompt": brief["persona_prompt"]}))
return first(run("picassoia/seedance-2.5-lite", {
"prompt": brief["motion_prompt"],
"image": frame,
"duration": 10,
"resolution": "720p",
}))
Trata failed como un dato, no como una sorpresa. Registra la cadena error, reintenta una vez el trabajo fallido con la misma entrada y, después, una vez más con un prompt un poco más corto, y luego déjalo en espera para revisión humana. Nunca reintentes plan_required ni una petición mal formada, porque la respuesta no cambiará. Copia los archivos terminados a tu propio almacenamiento en cuanto estén listos, en lugar de suponer que el enlace de salida vivirá para siempre.
La versión en Node es el mismo bucle con fetch. Envuelve tus campos en input, consulta urls.get y respeta eta.next_poll_in_seconds.
const API = 'https://api.picassoia.com/v1'
const headers = {
Authorization: `Bearer ${process.env.PICASSOIA_TOKEN}`,
'Content-Type': 'application/json',
}
const sleep = (s) => new Promise((r) => setTimeout(r, s * 1000))
async function run(model, input) {
const res = await fetch(`${API}/models/${model}/predictions`, {
method: 'POST', headers, body: JSON.stringify({ input }),
})
let pred = await res.json()
if (!res.ok) throw new Error(`${pred.code}: ${pred.detail}`)
while (!['succeeded', 'failed', 'canceled'].includes(pred.status)) {
await sleep(pred.eta?.next_poll_in_seconds ?? 2)
pred = await (await fetch(pred.urls.get, { headers })).json()
}
if (pred.status !== 'succeeded') throw new Error(pred.error ?? pred.status)
return pred.output
}
La cuenta permite 5 predicciones en cola o en ejecución a la vez, y ese cupo se comparte entre todas las claves secretas y todas las conexiones MCP. Si un compañero también genera desde un cliente MCP, tu script compite con él.
La regla para tu código es sencilla: nunca ejecutes más de cinco workers, e idealmente deja uno libre. Un pool de hilos lo resuelve en unas pocas líneas.
from multiprocessing.pool import ThreadPool
with ThreadPool(4) as pool:
results = pool.map(make_ad, briefs)
El rendimiento es fácil de estimar. Divide los segundos de una hora entre el tiempo que tarda un anuncio y multiplica por el número de workers. Si una imagen más un video tardan unos cuatro minutos, cuatro workers terminan unos 60 anuncios por hora.
Otros límites que conviene incluir en tu validación: cuerpos de petición de hasta 10 MB, imágenes en data URL de hasta 5 MB cada una, prompts de hasta 4000 caracteres y un tiempo límite de tres horas por predicción. Un trabajo que supere ese tiempo límite debe marcarse como caído y reintentarse, no esperarse.
La variación es el objetivo, pero la variación aleatoria produce clips fuera de marca. Divide tu plantilla en ejes que cambias y ejes que fijas.
| Eje | Variar | Fijar |
|---|---|---|
| Persona | Rango de edad, pelo, ropa | Realismo de la piel y la tela |
| Escenario | Cocina, coche, gimnasio en el garaje, balcón | Luz natural de ventana o de día |
| Gancho | Pregunta, confesión, demostración | Una afirmación por guion |
| Duración | 5, 10 o 15 segundos | Encuadre vertical |
| Producto | Nunca | Packshot y etiqueta exactos |
Guarda el prompt final y la seed junto a cada resultado. Cuando un clip gane, puedes recrear sus hermanos cambiando un solo campo en lugar de adivinar qué lo hizo funcionar.
Antes de escribir código, genera unos cuantos clips a mano para ver lo que producen realmente tus prompts. Seedance 2.5 Lite es la forma más rápida de hacerlo.
save_audio viene activado por defecto, que es lo que quieres para un anuncio con voz.last_frame_image cuando el clip deba terminar con una toma limpia del producto.💡 Consejo: Juzga solo los primeros dos segundos. Es todo lo que le da a un espectador que desliza el feed, así que un clip con una apertura débil se descarta sin importar lo bueno que sea el final.
Automatiza los rechazos rutinarios para que una persona solo revise los clips que ya superaron el filtro:
save_audio estaba activado.Trata la divulgación como parte del pipeline, no como un añadido posterior. Las plataformas publicitarias y los reguladores esperan cada vez más que el contenido generado por IA esté etiquetado, y las normas cambian con frecuencia, así que lee la política publicitaria vigente de cada plataforma antes de lanzar un lote.
Nunca presentes a un personaje sintético como un cliente real que cuenta resultados reales. No recrees el rostro ni la voz de una persona real sin su consentimiento por escrito. Un testimonio falso es la forma más rápida de perder una cuenta publicitaria, y se lo merece.
Ya tienes el ciclo completo: brief, guion, fotograma de persona, clip con audio y revisión. La forma más barata de saber si encaja con tu producto es probar tres variantes esta tarde.
Abre Seedance 2.5 Lite en PicassoIA, sube un fotograma de persona de PicassoIA Image y escribe tres ganchos distintos para el mismo producto. Compara las aperturas una al lado de la otra. Cuando uno de ellos se adelante claramente, tendrás tu plantilla, y el Python de arriba la convierte en cincuenta más.
Empieza poco a poco, mantén los clips honestos y deja que los datos elijan a los ganadores. Genera hoy tu primera imagen de persona en PicassoIA, anímala en un anuncio de estilo UGC y comprueba hasta dónde llega una buena plantilla. El único experimento que fracasa es el que nunca haces.
Elige tu idioma
