API y SDK de edición de video con IA: automatiza ediciones en tu app

La mayoría de las ediciones de video no necesitan a una persona frente a la línea de tiempo. Cambiar el fondo de 200 clips de producto, convertir un brief escrito en cinco cortes verticales o recortar cada subida a 15 segundos: estos son trabajos para código. Una API de edición de video con IA permite que tu app envíe ese trabajo como peticiones HTTP y recoja los clips terminados, y un SDK, aunque sea pequeño y lo escribas tú, mantiene esas llamadas ordenadas. Este artículo muestra lo que puede hacer hoy esa API, cómo funciona la API para desarrolladores de PicassoIA y cómo encadenar ediciones generativas con pasos sencillos de FFmpeg en un único pipeline de video automatizado. Cuando una función solo existe en la app web, el texto lo indica.

Qué hace realmente una API de edición

Antes de escribir código, divide la palabra "editar" en dos tareas, porque cada una necesita herramientas distintas.

Ediciones generativas frente a ediciones de línea de tiempo

Las ediciones de línea de tiempo son deterministas. Cortar en el segundo 1,0, unir dos clips, incrustar subtítulos o cambiar a 9:16: la misma entrada siempre da la misma salida, y FFmpeg lo hace en tu propio servidor. Las ediciones generativas son probabilísticas. Un modelo vuelve a renderizar los píxeles a partir de un prompt, así que "convierte el sofá en cuero morado" o "anima esta foto" pueden verse algo distintos en cada ejecución, a menos que fijes la semilla.

Un pipeline de producción casi siempre necesita ambas. Así se reparten las tareas habituales:

Dónde encaja un SDK

Un SDK es la capa que mantiene el HTTP en bruto fuera de la lógica de negocio. Adjunta el token, crea trabajos, consulta resultados, reintenta los fallos adecuados, cancela los trabajos bloqueados y limita cuántos se ejecutan a la vez. Como los trabajos de video son asíncronos (creas, esperas, recuperas), casi todo el código incómodo está en esa espera. La página de la API incluye ejemplos en Python, Node y cURL. Eso basta para crear un cliente ligero propio, que es justo lo que hacen las secciones siguientes.

Qué ofrece PicassoIA hoy

La API para desarrolladores está en https://api.picassoia.com/v1. Te autenticas con un token Bearer que empieza por pia_sk_, que creas en la página de la API de picassoia.com (una cuenta puede tener hasta dos). El formato sigue el estilo de Replicate: creas una predicción, la consultas y lees el resultado.

Cuatro modelos detrás de la API

💡 Planifica en torno a esta división. A octubre de 2026, los modelos de edición de video del catálogo, como P Video Edit, Aleph 2 y Lucy Edit 2, funcionan en la app web, no a través de la API. Usa la API para generar y volver a renderizar, y la app web para las ediciones con prompt sobre metraje existente.

Límites con los que diseñar

• 5 predicciones simultáneas por cuenta, compartidas por todos los tokens y conexiones MCP.
• 10 MB por cuerpo de petición. Envía URL de imágenes y videos, nunca archivos en base64.
• 4000 caracteres por prompt.
• 3 horas antes de que una predicción agote el tiempo.

💡 Las reglas de acceso y los requisitos de los planes cambian, así que confírmalos en la página de la API antes de prometer una hoja de ruta a tu equipo.

Envía tu primera petición

Cada llamada de abajo lee una variable de entorno, PICASSOIA_TOKEN, para que el token nunca aparezca en tu código fuente.

Crear un trabajo con cURL

curl -X POST https://api.picassoia.com/v1/models/picassoia/picassoia-video/predictions \
  -H "Authorization: Bearer $PICASSOIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "prompt": "Slow push-in on a ceramic mug of coffee on a sunlit desk, steam rising, soft room tone",
      "image": "https://example.com/first-frame.jpg",
      "resolution": "720p"
    }
  }'

Copiar prompt

La respuesta devuelve una predicción id y un status. El objeto input sigue el esquema del modelo. Para PicassoIA Video eso significa un prompt obligatorio más image opcionales, resolution (480p o 720p, por defecto 720p), aspect_ratio, seed y save_audio. Cuando pasas una imagen, se convierte en el primer fotograma y el clip hereda su relación de aspecto. Cada clip dura 5 segundos a 24 fps con audio sincronizado, a menos que desactives save_audio.

Consulta hasta que el clip esté listo

Los trabajos son asíncronos, así que la primera respuesta es un recibo, no un video. Pide la predicción cada pocos segundos con GET /v1/predictions/{id} hasta que el estado indique que se completó o falló, y luego lee la URL de salida. Las ejecuciones de ejemplo en las páginas de los modelos terminan en unos 30 segundos a 2 minutos, así que un intervalo de sondeo de 3 a 5 segundos es suficiente. Si ya no te interesa un trabajo, llama al endpoint de cancelación para que no ocupe una de tus cinco plazas.

Construye un pequeño envoltorio de SDK

Un envoltorio en menos de 40 líneas

Envuelve las llamadas que necesitas en un único módulo. Esta versión para Node (18 o posterior, así que fetch viene integrado) hace el trabajo:

const BASE = "https://api.picassoia.com/v1";
const headers = {
  Authorization: `Bearer ${process.env.PICASSOIA_TOKEN}`,
  "Content-Type": "application/json",
};

export async function createPrediction(model, input) {
  const res = await fetch(`${BASE}/models/${model}/predictions`, {
    method: "POST",
    headers,
    body: JSON.stringify({ input }),
  });
  if (!res.ok) throw new Error(`Create failed: ${res.status} ${await res.text()}`);
  return res.json();
}

export async function waitFor(id, { everyMs = 4000, timeoutMs = 10 * 60_000 } = {}) {
  const started = Date.now();
  while (Date.now() - started < timeoutMs) {
    const res = await fetch(`${BASE}/predictions/${id}`, { headers });
    const prediction = await res.json();
    if (prediction.status === "succeeded") return prediction;
    if (prediction.status === "failed" || prediction.status === "canceled") {
      throw new Error(`Prediction ${id} ${prediction.status}`);
    }
    await new Promise((r) => setTimeout(r, everyMs));
  }
  await fetch(`${BASE}/predictions/${id}/cancel`, { method: "POST", headers });
  throw new Error(`Prediction ${id} timed out`);
}

Copiar prompt

Tres hábitos la mantienen segura en producción. Reintenta solo lo que puede tener éxito en un segundo intento: las caídas de red y las respuestas 5xx obtienen dos o tres intentos con retardos crecientes, mientras que los errores 4xx, como una entrada incorrecta o un token no válido, no, porque repetirlos no cambia nada. Define siempre un tiempo de espera y cancela al vencer, como hace el código anterior, para que un trabajo bloqueado nunca retenga una plaza. Registra el id de la predicción junto a tu propio id de trabajo, porque es lo primero que necesitarás cuando algo parezca fallar. Confirma los campos exactos de la respuesta en la documentación de la API antes de publicar.

Mantente por debajo de cinco trabajos a la vez

El límite de la cuenta son cinco predicciones simultáneas, compartidas entre tokens y conexiones MCP. Un lote de 40 clips lanzado con Promise.all llegaría al límite de inmediato. Pon un pequeño pool delante del envoltorio y limítalo a 4, para que una plaza quede libre para pruebas manuales u otra herramienta en la misma cuenta:

export function pool(limit = 4) {
  let active = 0;
  const queue = [];
  const next = () => {
    if (active >= limit || queue.length === 0) return;
    active++;
    const { task, resolve, reject } = queue.shift();
    task().then(resolve, reject).finally(() => { active--; next(); });
  };
  return (task) => new Promise((resolve, reject) => { queue.push({ task, resolve, reject }); next(); });
}

const run = pool(4);
const clips = await Promise.all(
  shots.map((shot) => run(async () => {
    const job = await createPrediction("picassoia/picassoia-video", shot);
    return waitFor(job.id);
  }))
);

Copiar prompt

Automatiza ediciones dentro de tu app

Con el envoltorio listo, una edición automatizada es una cadena corta de pasos:

1. Un plan: un LLM convierte un brief en una lista de ediciones en JSON.
2. Imágenes fijas: genera o edita imágenes a través de la API.
3. Planos: renderiza clips nuevos a partir de esas imágenes.
4. Trabajo de línea de tiempo: recorta, une y añade subtítulos con FFmpeg.
5. Revisión y entrega: comprueba cada archivo y luego publícalo.

Los tres patrones siguientes cubren la parte central de esa cadena.

Edita el primer fotograma y luego anima

La API no puede tomar tu metraje y aplicarle una edición de texto, pero se acerca bastante. Extrae un fotograma del clip original, edita esa imagen fija con PicassoIA Image Editor Pro y luego renderiza un plano nuevo que parta del fotograma editado con PicassoIA Video o Seedance 2.5 Lite.

1. Extrae un fotograma: ffmpeg -ss 2 -i source.mp4 -frames:v 1 frame.jpg
2. Súbelo a un almacenamiento para que tenga una URL pública.
3. Envíalo en el array images y llámalo "imagen 1" en el prompt. El editor admite hasta tres imágenes de referencia, y los ejemplos de su página tardan entre uno y dos segundos, así que puedes descartar una edición mala antes de gastar un render en video.
4. Pasa la imagen editada como image a un modelo de video con un prompt de movimiento.

const edit = await waitFor((await createPrediction("picassoia/picassoia-image-editor-pro", {
  prompt: "Change the sofa in image 1 to light purple leather. Keep everything else unchanged.",
  images: [frameUrl],
})).id);
const firstFrame = Array.isArray(edit.output) ? edit.output[0] : edit.output;

const clip = await waitFor((await createPrediction("picassoia/picassoia-video", {
  prompt: "Slow push-in toward the sofa, soft window light, a hand places a cushion.",
  image: firstFrame,
  resolution: "720p",
})).id);

Copiar prompt

Esto vuelve a renderizar el plano en lugar de editar los píxeles originales, así que el movimiento será distinto del de tu metraje. Úsalo para producir una variación, no un retoque fotograma por fotograma. Seedance 2.5 Lite también acepta last_frame_image y una duración de 10 segundos, lo que ayuda cuando un plano debe caer en un fotograma concreto.

Deja que un LLM escriba el plan de edición

Codificar a mano cada edición no escala. Deja que un modelo de lenguaje convierta un brief en lenguaje natural en una lista de ediciones en JSON y luego haz que tu código ejecute esa lista. GPT 5 Structured está pensado para devolver JSON limpio, y Claude Sonnet 5 y Gemini 3.5 Flash son buenos compañeros para redactar planes cuando los pruebas a mano en la app web. En producción, llama al proveedor de LLM que ya use tu app.

{
  "shots": [
    { "source": "clip_01.mp4", "start": 1.0, "end": 4.5, "caption": "New arrivals" },
    { "generate": "Slow dolly toward a sunlit storefront, shallow depth of field", "seconds": 5 }
  ]
}

Copiar prompt

Nunca ejecutes un plan a ciegas. Valídalo con un esquema, rechaza los campos desconocidos, limita las duraciones y fija un máximo de planos. El modelo propone; tu código decide.

Recorta, une y subtitula con FFmpeg

Los pasos de línea de tiempo siguen siendo deterministas y baratos. Ejecútalos desde Node con child_process o desde cualquier gestor de trabajos:

# trim 3.5 seconds starting at 1.0
ffmpeg -ss 1.0 -t 3.5 -i clip_01.mp4 -c:v libx264 -c:a aac trimmed.mp4

# merge the clips listed in list.txt (same codec, size and frame rate)
ffmpeg -f concat -safe 0 -i list.txt -c copy merged.mp4

# burn captions from an SRT file
ffmpeg -i merged.mp4 -vf subtitles=captions.srt -c:a copy final.mp4

Copiar prompt

Unir con -c copy solo funciona cuando todos los clips comparten el mismo códec, tamaño y fotogramas por segundo. Los clips de PicassoIA Video salen todos con 5 segundos y 24 fps, pero si los mezclas con grabaciones de teléfono, vuelve a codificar todo con una única especificación primero. La app web ofrece los mismos trabajos a mano mediante Trim Video, Video Merge y Autocaption.

Usa P Video Edit en PicassoIA

Cuando necesites una edición con prompt sobre metraje que ya grabaste, la herramienta es P Video Edit. Funciona en la app web de PicassoIA y admite un clip de hasta 15 segundos. Cambia el video siguiendo una instrucción de texto sencilla, así que una petición como "cambia el cielo a un atardecer" o "haz la chaqueta roja" no necesita línea de tiempo.

Paso a paso en la app web

1. Abre la página de P Video Edit y sube tu clip (15 segundos como máximo).
2. Escribe una instrucción, por ejemplo: Change the material of the sofa to light purple leather. Do not change anything else.
3. Opcional: adjunta hasta cuatro imágenes de referencia (jpg, jpeg, png o webp) cuando un color, una textura o un objeto deban coincidir exactamente.
4. Activa Draft para obtener una vista previa más rápida y de menor calidad antes del render final.
5. Deja Prompt Upsampling activado para instrucciones cortas. Desactívalo cuando tu prompt ya sea preciso.
6. Mantén Save Audio activado para que la banda sonora original siga sincronizada.
7. Ejecútalo, revisa el resultado, ajusta el prompt y vuelve a ejecutarlo. Fija una semilla si quieres repetir un resultado exactamente.

Las ejecuciones de ejemplo en la página del modelo tardaron entre uno y dos minutos cada una.

Prompts que mantienen intacta la escena

Nombra lo que debe cambiar y luego nombra lo que no debe cambiar. Un prompt de ejemplo en la página del modelo sigue ese patrón: Change only the SUV body paint to yellow. Termina con Keep the environment, lighting and camera movement unchanged. Limítalo a un cambio por ejecución y encadena ejecuciones si necesitas más.

El catálogo tiene más editores. Estos merecen una prueba sobre el mismo clip:

Costos, fallos y salvaguardas

Prevé fallos y costos

Trata cada predicción como algo que puede fallar. Un trabajo fallido no se puede recuperar, así que vuelve a enviarlo como un trabajo nuevo, limita los reintentos a dos y guarda la entrada original para poder repetirla. Registra el consumo de cada trabajo por modelo y resolución en tus propios registros: los precios y las reglas de los planes cambian, así que consulta las condiciones vigentes en las páginas de la API y de precios antes de dar a un cliente un costo por clip. Copia los archivos terminados a tu propio almacenamiento justo después del éxito y trata la URL del resultado como un enlace de entrega, no como un archivo.

Revisa las entradas antes de renderizar

Si los usuarios pueden escribir prompts o subir imágenes, compruébalos primero. Llama Guard 4 12B es un modelo de moderación de contenido que puedes probar en la app web, y la misma idea se aplica con el servicio de moderación que ya use tu app. Añade también un límite de peticiones por usuario, para que un solo cliente no ocupe las cinco plazas.

Ejecuta tu propia edición hoy

La forma más rápida de ver el pipeline es probar sus piezas a mano. Abre PicassoIA, crea una imagen fija con PicassoIA Image, cambia un detalle con PicassoIA Image Editor Pro y luego anima el resultado con PicassoIA Video. Unos minutos de experimentos te mostrarán qué prompts funcionan antes de escribir una sola línea de código de integración. Haz una segunda pasada sobre la misma imagen fija con Seedance 2.5 Lite y compara el movimiento.

Cuando los resultados te parezcan correctos, conecta los mismos pasos a tu app con el envoltorio de este artículo. Explora todos los modelos, incluidos los editores de video, en picassoia.com/en/all-models, y crea tus propias imágenes hoy mismo.