Guida: trasforma le immagini in video

Un video richiede minuti, non secondi, quindi un’integrazione video si costruisce attorno ad attività e webhook, non a una singola richiesta in attesa. Questa guida percorre i lavori più comuni con ID di modelli reali.

Anima un’immagine

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"
  }'

Ricevi subito un 202 con un taskId. Qualche minuto dopo il webhook consegna l’attività completata, oppure la leggi con recordInfo. Il video è in output.assets[0], con durationSeconds, width e height.

Quanto costa

La maggior parte dei modelli video addebita al secondo di output, e la tariffa sale con la risoluzione. Per alibaba/wan-3.0/image-to-video sono 6,75 crediti al secondo a 480p, 13,5 a 720p e 27 a 1080p: la richiesta qui sopra trattiene quindi 34 crediti (5 × 6,75, arrotondato per eccesso) e costa altrettanto se va a buon fine.

• Mentre affini i prompt parti dalla risoluzione più bassa e da una durata breve, poi alzale per il render finale.
• Chiedi il prezzo esatto a jobs/quote prima di mostrarlo a un utente.
• Un video fallito o scaduto non costa nulla.

Scegli il primo e l’ultimo fotogramma

Molti modelli da immagine a video accettano anche last_image_url. La clip parte da image_url e finisce esattamente su last_image_url: è così che si fa una trasformazione o un loop perfetto (usa la stessa immagine in entrambi).

Video da riferimento: personaggio o prodotto coerenti

I modelli reference-to-video costruiscono una scena nuova attorno a una o più immagini di riferimento (e, per alcuni modelli, a video o audio di riferimento) invece di animare un primo fotogramma dato:

{
  "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
  }
}

Il modo in cui un modello richiama i riferimenti nel prompt cambia da modello a modello; lo spiegano le descrizioni dei campi nella sua pagina di riferimento.

Allunga una clip

I modelli video-extend proseguono una clip esistente dal suo ultimo fotogramma. Invia la clip come video_url e descrivi cosa succede dopo:

{
  "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"
  }
}

I modelli di estensione che uniscono le clip restituiscono due file: prima il video unito (role: "video"), poi la sola parte nuova (role: "segment").

Audio

I modelli con generate_audio aggiungono una colonna sonora alla clip; disattivarla può abbassare il prezzo su alcuni modelli. Per sonorizzare un video che hai già, usa popnow/foley-v1/video-to-audio, che restituisce lo stesso video con l’audio generato.

Prompt che funzionano per i video

Descrivi il movimento, non solo la scena: cosa si muove, quanto in fretta e cosa fa la camera. «La camera si avvicina lentamente mentre la persona si gira verso la luce» dà al modello qualcosa da fare; «un faro bellissimo» no. L’immagine dice già com’è fatto tutto: usa le parole per ciò che cambia.

Uno schema per la produzione

1. Carica o salva l’immagine di partenza e conserva il suo URI popnow://.
2. Chiedi un preventivo, mostra il prezzo e poi chiama createTask con un Idempotency-Key ricavato dal tuo ID di lavoro e una callBackUrl.
3. Nel webhook verifica la firma, conferma la ricezione e poi scarica il video nel tuo archivio.
4. Una volta al giorno elenca le attività recenti con GET /api/v1/jobs e leggi quelle il cui webhook non è mai arrivato.

Il resto è nella checklist per la produzione.