Guide: turn images into video

Video takes minutes, not seconds, so a video integration is built around tasks and webhooks rather than one waiting request. This guide walks through the common jobs with real model IDs.

Animate one image

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

You get a 202 with a taskId right away. A few minutes later the webhook delivers the finished task, or you read it with recordInfo. The video is in output.assets[0], with durationSeconds, width and height.

What it costs

Most video models charge per second of output, and the rate rises with resolution. For alibaba/wan-3.0/image-to-video that is 6.75 credits per second at 480p, 13.5 at 720p and 27 at 1080p — so the request above holds 34 credits (5 × 6.75, rounded up) and costs the same when it succeeds.

• Start at the lowest resolution and a short duration while you tune prompts, then raise them for the final render.
• Ask jobs/quote for the exact price before showing it to a user.
• A failed or expired video costs nothing.

Choose the first and last frame

Many image-to-video models take last_image_url as well. The clip starts on image_url and ends exactly on last_image_url, which is how you make a transformation or a smooth loop (use the same image for both).

Reference video: keep a character or product consistent

reference-to-video models build a new scene around one or more reference images (and, on some models, reference video or audio) instead of animating a given first frame:

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

How each model refers to its references in the prompt differs; the field descriptions on its reference page say how.

Make a clip longer

video-extend models continue an existing clip from its last frame. Send the clip as video_url and describe what happens next:

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

Extension models that join the clips return two assets: the joined video first (role: "video"), then the new part alone (role: "segment").

Sound

Models with generate_audio add a soundtrack to the clip; turning it off can lower the price on some models. To add sound to a video you already have, use popnow/foley-v1/video-to-audio, which returns the same video with generated sound.

Prompts that work for video

Describe motion, not just the scene: what moves, how fast, and what the camera does. "The camera slowly pushes in while the subject turns toward the light" gives the model something to do; "a beautiful lighthouse" does not. The picture already says what things look like — spend the words on what changes.

A production pattern

1. Upload or save the source image, and keep its popnow:// URI.
2. Quote, show the price, then createTask with an Idempotency-Key derived from your own job ID and a callBackUrl.
3. In the webhook, verify the signature, acknowledge, then download the video into your own storage.
4. Once a day, list recent tasks with GET /api/v1/jobs and read any whose webhook you never received.

See Production checklist for the rest.