API e SDK de edição de vídeo com IA: automatize edições no seu app

A maioria das edições de vídeo não precisa de uma pessoa na linha do tempo. Trocar o fundo de 200 clipes de produtos, transformar um briefing escrito em cinco cortes verticais, cortar cada upload para 15 segundos: esses são trabalhos para código. Uma API de edição de vídeo com IA permite que seu app envie esse trabalho como requisições HTTP e receba os clipes finalizados, e um SDK, mesmo um pequeno que você escreva sozinho, deixa essas chamadas organizadas. Este artigo mostra o que essa API pode fazer hoje, como funciona a API para desenvolvedores do PicassoIA e como encadear edições generativas com etapas simples do FFmpeg em um único pipeline de vídeo automatizado. Quando um recurso existe apenas no app web, o texto informa isso.

O que uma API de edição realmente faz

Antes de escrever qualquer código, separe a palavra "editar" em dois trabalhos, porque cada um precisa de uma ferramenta diferente.

Edições generativas versus edições de linha do tempo

Edições de linha do tempo são determinísticas. Cortar em 1,0 segundo, unir dois clipes, inserir legendas, redimensionar para 9:16: a mesma entrada sempre gera a mesma saída, e o FFmpeg faz isso no seu próprio servidor. Edições generativas são probabilísticas. Um modelo renderiza os pixels novamente a partir de um prompt, então "deixe o sofá de couro roxo" ou "anime esta foto" podem ficar um pouco diferentes a cada execução, a menos que você fixe o seed.

Um pipeline de produção quase sempre precisa dos dois. Veja como os trabalhos mais comuns se dividem:

Onde entra um SDK

Um SDK é a camada que mantém o HTTP bruto fora da lógica de negócio. Ele anexa o token, cria jobs, consulta resultados, repete as falhas certas, cancela jobs travados e limita quantos rodam ao mesmo tempo. Como os jobs de vídeo são assíncronos (você cria, espera e busca), quase todo o código complicado está nessa espera. A página da API traz exemplos em Python, Node e cURL. Isso basta para construir um cliente enxuto próprio, que é exatamente o que as seções seguintes fazem.

O que o PicassoIA expõe hoje

A API para desenvolvedores fica em https://api.picassoia.com/v1. Você se autentica com um Bearer token que começa com pia_sk_, criado na página da API em picassoia.com (uma conta pode ter até duas). O formato segue o estilo Replicate: você cria uma previsão, consulta essa previsão e lê o resultado.

Quatro modelos por trás da API

💡 Planeje em torno dessa divisão. Em outubro de 2026, os modelos de edição de vídeo do catálogo, como P Video Edit, Aleph 2 e Lucy Edit 2, rodam no app web, não pela API. Use a API para gerar e renderizar novamente, e o app web para edições baseadas em prompt em filmagens existentes.

Limites para considerar no projeto

• 5 previsões simultâneas por conta, compartilhadas entre todos os tokens e conexões MCP.
• 10 MB no corpo da requisição. Envie URLs de imagens e vídeos, nunca arquivos em base64.
• 4.000 caracteres por prompt.
• 3 horas até uma previsão expirar.

💡 As regras de acesso e os requisitos de plano mudam, então confirme-os na página da API antes de prometer um cronograma à sua equipe.

Envie sua primeira requisição

Todas as chamadas abaixo leem uma variável de ambiente, PICASSOIA_TOKEN, para que o token nunca apareça no seu código-fonte.

Crie um job com 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

A resposta devolve uma previsão id e um status. O objeto input segue o schema do modelo. Para o PicassoIA Video, isso significa um prompt obrigatório, mais image, resolution opcionais (480p ou 720p, padrão 720p), aspect_ratio, seed e save_audio. Quando você envia uma imagem, ela vira o quadro de abertura e o clipe herda a proporção dela. Cada clipe tem 5 segundos a 24 fps com áudio sincronizado, a menos que você desative save_audio.

Consulte até o clipe ficar pronto

Os jobs são assíncronos, então a primeira resposta é um comprovante, não um vídeo. Consulte a previsão a cada poucos segundos com GET /v1/predictions/{id} até o status indicar sucesso ou falha e então leia a URL de saída. Os exemplos executados nas páginas dos modelos terminam em cerca de 30 segundos a 2 minutos, então um intervalo de consulta de 3 a 5 segundos é mais que suficiente. Se você não quiser mais um job, chame o endpoint de cancelamento para que ele não ocupe uma das suas cinco vagas.

Crie um pequeno wrapper de SDK

Um wrapper em menos de 40 linhas

Encapsule as chamadas de que você precisa em um único módulo. Esta versão em Node (18 ou superior, para que fetch já esteja disponível) faz o trabalho:

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

Três hábitos mantêm isso seguro em produção. Repita apenas o que pode dar certo na segunda tentativa: quedas de rede e respostas 5xx ganham duas ou três tentativas com intervalos crescentes, enquanto erros 4xx, como entrada inválida ou token ruim, não são repetidos, porque repeti-los não muda nada. Defina sempre um timeout e cancele ao expirar, como o código acima faz, para que um job travado nunca ocupe uma vaga. Registre o id da previsão junto com o id do seu próprio job, porque é a primeira coisa de que você vai precisar quando algo parecer errado. Confirme os campos exatos da resposta na documentação da API antes de colocar em produção.

Fique em até cinco jobs ao mesmo tempo

O limite da conta é de cinco previsões simultâneas, compartilhadas entre tokens e conexões MCP. Um lote de 40 clipes disparado com Promise.all atingiria esse limite imediatamente. Coloque um pequeno pool na frente do wrapper e mantenha-o em 4, para que uma vaga fique livre para testes manuais ou outra ferramenta na mesma conta:

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

Automatize edições dentro do seu app

Com o wrapper pronto, uma edição automatizada é uma cadeia curta de etapas:

1. Um plano: um LLM transforma um briefing em uma lista de edições em JSON.
2. Imagens fixas: gere ou edite imagens pela API.
3. Planos: renderize novos clipes a partir dessas imagens.
4. Trabalho na linha do tempo: corte, una e legende com o FFmpeg.
5. Revisão e entrega: verifique cada arquivo e publique.

Os três próximos padrões preenchem o meio dessa cadeia.

Edite o primeiro quadro e depois anime

A API não consegue pegar sua filmagem e aplicar nela uma edição por texto, mas consegue chegar perto. Extraia um quadro do clipe original, edite essa imagem fixa com o PicassoIA Image Editor Pro e depois renderize um novo plano que comece a partir do quadro editado com o PicassoIA Video ou o Seedance 2.5 Lite.

1. Extraia um quadro: ffmpeg -ss 2 -i source.mp4 -frames:v 1 frame.jpg
2. Envie-o para um armazenamento para que ele tenha uma URL pública.
3. Envie-o no array images e chame-o de "imagem 1" no prompt. O editor aceita até três imagens de referência, e os exemplos de edição na página retornam em cerca de um a dois segundos, então você pode rejeitar uma edição ruim antes de gastar uma renderização em vídeo.
4. Passe a imagem editada como image para um modelo de vídeo com um prompt de movimento.

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

Isso renderiza o plano novamente em vez de editar os pixels originais, então o movimento será diferente da sua filmagem original. Trate isso como uma forma de produzir uma variação, não como um retoque quadro a quadro. O Seedance 2.5 Lite também aceita um last_frame_image e duração de 10 segundos, o que ajuda quando um plano precisa cair em um quadro específico.

Deixe um LLM escrever o plano de edição

Codificar cada edição à mão não escala. Deixe um modelo de linguagem transformar um briefing em linguagem natural em uma lista de edições em JSON e depois faça seu código executar essa lista. O GPT 5 Structured foi feito para devolver JSON limpo, e o Claude Sonnet 5 e o Gemini 3.5 Flash são bons parceiros de rascunho quando você testa planos manualmente no app web. Em produção, chame o provedor de LLM que seu app já usa.

{
  "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 execute um plano às cegas. Valide-o contra um schema, rejeite campos desconhecidos, limite as durações e defina um teto para o número de planos. O modelo propõe; o seu código decide.

Corte, una e legende com o FFmpeg

As etapas de linha do tempo continuam determinísticas e baratas. Execute-as a partir do Node com child_process ou de qualquer executor de jobs:

# 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 com -c copy só funciona quando todos os clipes têm o mesmo codec, tamanho e taxa de quadros. Os clipes do PicassoIA Video saem sempre com 5 segundos e 24 fps, mas se você misturá-los com filmagens de celular, recodifique tudo para uma mesma especificação antes. O app web oferece os mesmos trabalhos manualmente pelo Trim Video, Video Merge e Autocaption.

Use o P Video Edit no PicassoIA

Quando você precisa de uma edição baseada em prompt em uma filmagem que já gravou, a ferramenta é o P Video Edit. Ele roda no app web do PicassoIA e aceita um clipe de até 15 segundos. Ele altera o vídeo seguindo uma instrução de texto simples, então um pedido como "mude o céu para um pôr do sol" ou "deixe a jaqueta vermelha" não exige linha do tempo.

Passo a passo no app web

1. Abra a página do P Video Edit e envie seu clipe (15 segundos no máximo).
2. Escreva uma instrução, por exemplo: Change the material of the sofa to light purple leather. Do not change anything else.
3. Opcional: anexe até quatro imagens de referência (jpg, jpeg, png ou webp) quando uma cor, textura ou objeto precisar combinar exatamente.
4. Ative o Draft para uma prévia mais rápida e de qualidade menor antes da renderização final.
5. Deixe o Prompt Upsampling ligado para instruções curtas. Desligue-o quando seu prompt já estiver preciso.
6. Mantenha o Save Audio ligado para que a trilha original continue sincronizada.
7. Execute, revise o resultado, ajuste o prompt e execute de novo. Defina um seed se quiser repetir um resultado exatamente.

Os exemplos executados na página do modelo levaram cerca de um a dois minutos cada.

Prompts que mantêm a cena intacta

Diga o que deve mudar e, em seguida, diga o que não deve mudar. Um prompt de exemplo na página do modelo segue esse padrão: Change only the SUV body paint to yellow. Ele termina com Keep the environment, lighting and camera movement unchanged. Mantenha uma mudança por execução e encadeie execuções se precisar de mais.

O catálogo tem mais editores. Estes valem um teste no mesmo clipe:

Custos, falhas e proteções

Planeje para falhas e custos

Trate toda previsão como algo que pode falhar. Um job com falha é definitivo, então reenvie-o como um novo job, limite as novas tentativas a duas e guarde a entrada original para poder reproduzi-la. Registre cada job por modelo e resolução nos seus próprios logs: preços e regras de planos mudam, então leia os termos atuais nas páginas da API e de preços antes de informar um custo por clipe a um cliente. Copie os arquivos finalizados para o seu próprio armazenamento logo após o sucesso e trate a URL do resultado como um link de entrega, não como um arquivo.

Verifique as entradas antes de renderizar

Se os usuários puderem digitar prompts ou enviar imagens, verifique-os antes. O Llama Guard 4 12B é um modelo de moderação de conteúdo que você pode testar no app web, e a mesma ideia vale para qualquer serviço de moderação que seu conjunto de ferramentas já use. Adicione também um limite de requisições por usuário, para que um cliente não ocupe todas as cinco vagas.

Execute sua própria edição hoje

A forma mais rápida de ver o pipeline é executar suas partes manualmente. Abra o PicassoIA, crie uma imagem fixa com o PicassoIA Image, altere um detalhe com o PicassoIA Image Editor Pro e depois anime o resultado com o PicassoIA Video. Alguns minutos de experimentos mostrarão quais prompts funcionam antes de você escrever qualquer linha de código de integração. Faça uma segunda passagem na mesma imagem fixa com o Seedance 2.5 Lite e compare o movimento.

Quando os resultados parecerem certos, conecte as mesmas etapas ao seu app com o wrapper deste artigo. Veja todos os modelos, incluindo os editores de vídeo, em picassoia.com/en/all-models, e crie suas próprias imagens hoje.