Guia: transforme imagens em vídeo

Vídeo leva minutos, não segundos, então uma integração de vídeo gira em torno de tarefas e webhooks, e não de uma requisição que fica esperando. Este guia passa pelos usos mais comuns com IDs de modelo reais.

Anime uma imagem

curl -X POST "https://api.popnow.ai/api/v1/jobs/createTask" \
  -H "Authorization: Bearer $POPNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "model": "alibaba/wan-3.0/image-to-video",
    "input": {
      "image_url": "https://media.popnow.ai/movie/lighthouse.webp",
      "prompt": "Waves roll in slowly, clouds drift, the camera pushes gently toward the lighthouse",
      "resolution": "480p",
      "duration_seconds": 5
    },
    "callBackUrl": "https://your-app.example.com/hooks/popnow"
  }'

Você recebe na hora um 202 com um taskId. Alguns minutos depois, o webhook entrega a tarefa pronta, ou você a lê com recordInfo. O vídeo fica em output.assets[0], com durationSeconds, width e height.

Quanto custa

A maioria dos modelos de vídeo cobra por segundo gerado, e o preço sobe com a resolução. No alibaba/wan-3.0/image-to-video, são 6,75 créditos por segundo em 480p, 13,5 em 720p e 27 em 1080p — então a requisição acima reserva 34 créditos (5 × 6,75, arredondado para cima) e custa o mesmo se der certo.

• Comece com a menor resolução e uma duração curta enquanto ajusta os prompts, e aumente para o render final.
• Peça o preço exato ao jobs/quote antes de mostrá-lo a um usuário.
• Vídeo que falha ou expira não custa nada.

Defina o primeiro e o último quadro

Muitos modelos de imagem para vídeo também aceitam last_image_url. O clipe começa em image_url e termina exatamente em last_image_url — é assim que se faz uma transformação ou um loop perfeito (use a mesma imagem nos dois).

Vídeo por referência: personagem ou produto consistente

Modelos reference-to-video constroem uma cena nova em torno de uma ou mais imagens de referência (e, em alguns modelos, vídeo ou áudio de referência), em vez de animar um primeiro quadro dado:

{
  "model": "minimax/h3/reference-to-video",
  "input": {
    "prompt": "The same lighthouse at night, its beam sweeping over a calm sea while the camera circles slowly",
    "reference_image_urls": ["https://media.popnow.ai/movie/lighthouse.webp"],
    "duration_seconds": 6
  }
}

Cada modelo se refere às referências no prompt de um jeito; as descrições dos campos na página de referência dele explicam como.

Deixe um clipe mais longo

Modelos video-extend continuam um clipe existente a partir do último quadro. Envie o clipe como video_url e descreva o que acontece em seguida:

{
  "model": "minimax/h3/video-extend",
  "input": {
    "video_url": "https://media.popnow.ai/showcase/moon-picnic-loop.mp4",
    "prompt": "The camera keeps drifting right as the picnic blanket ripples in the breeze"
  }
}

Modelos de extensão que juntam os clipes devolvem dois arquivos: primeiro o vídeo unido (role: "video"), depois só a parte nova (role: "segment").

Som

Modelos com generate_audio adicionam trilha sonora ao clipe; desligar pode baratear o preço em alguns modelos. Para colocar som num vídeo que você já tem, use popnow/foley-v1/video-to-audio, que devolve o mesmo vídeo com som gerado.

Prompts que funcionam em vídeo

Descreva movimento, não só a cena: o que se mexe, com que velocidade e o que a câmera faz. "A câmera se aproxima devagar enquanto a pessoa se vira para a luz" dá ao modelo algo para fazer; "um farol lindo", não. A imagem já mostra como as coisas são — use as palavras para o que muda.

Um padrão para produção

1. Faça upload ou salve a imagem de origem e guarde o URI popnow:// dela.
2. Cote, mostre o preço e então chame createTask com um Idempotency-Key derivado do seu próprio ID de trabalho e um callBackUrl.
3. No webhook, verifique a assinatura, confirme o recebimento e depois baixe o vídeo para o seu próprio armazenamento.
4. Uma vez por dia, liste as tarefas recentes com GET /api/v1/jobs e leia as que nunca receberam webhook.

O resto está no checklist de produção.