Guía: convierte imágenes en video

El video tarda minutos, no segundos, así que una integración de video se construye alrededor de tareas y webhooks, no de una única solicitud que espera. Esta guía recorre los trabajos habituales con IDs de modelo reales.

Anima una imagen

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

Recibes al instante un 202 con un taskId. Unos minutos después, el webhook entrega la tarea terminada, o la lees con recordInfo. El video está en output.assets[0], con durationSeconds, width y height.

Cuánto cuesta

La mayoría de los modelos de video cobran por segundo de salida, y la tarifa sube con la resolución. Para alibaba/wan-3.0/image-to-video son 6,75 créditos por segundo a 480p, 13,5 a 720p y 27 a 1080p, así que la solicitud de arriba retiene 34 créditos (5 × 6,75, redondeado hacia arriba) y cuesta lo mismo si sale bien.

• Empieza con la resolución más baja y una duración corta mientras ajustas los prompts, y súbelas para el render final.
• Pide el precio exacto a jobs/quote antes de enseñárselo a un usuario.
• Un video fallido o caducado no cuesta nada.

Elige el primer y el último fotograma

Muchos modelos de imagen a video también aceptan last_image_url. El clip empieza en image_url y termina exactamente en last_image_url: así se hace una transformación o un bucle perfecto (usa la misma imagen en los dos).

Video de referencia: mantén coherente un personaje o un producto

Los modelos reference-to-video construyen una escena nueva alrededor de una o varias imágenes de referencia (y, en algunos modelos, video o audio de referencia) en lugar de animar un primer fotograma 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 nombra sus referencias en el prompt de una forma distinta; las descripciones de los campos en su página de referencia lo explican.

Alarga un clip

Los modelos video-extend continúan un clip existente desde su último fotograma. Envía el clip como video_url y describe lo que pasa después:

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

Los modelos de extensión que unen los clips devuelven dos archivos: primero el video unido (role: "video") y después la parte nueva sola (role: "segment").

Sonido

Los modelos con generate_audio añaden una banda sonora al clip; desactivarlo puede bajar el precio en algunos modelos. Para ponerle sonido a un video que ya tienes, usa popnow/foley-v1/video-to-audio, que devuelve el mismo video con sonido generado.

Prompts que funcionan en video

Describe el movimiento, no solo la escena: qué se mueve, a qué velocidad y qué hace la cámara. «La cámara se acerca despacio mientras la persona se gira hacia la luz» le da al modelo algo que hacer; «un faro precioso», no. La imagen ya dice cómo son las cosas: gasta las palabras en lo que cambia.

Un patrón para producción

1. Sube o guarda la imagen de origen y conserva su URI popnow://.
2. Cotiza, muestra el precio y luego llama a createTask con un Idempotency-Key derivado de tu propio ID de trabajo y un callBackUrl.
3. En el webhook, verifica la firma, confirma la recepción y después descarga el video a tu propio almacenamiento.
4. Una vez al día, lista las tareas recientes con GET /api/v1/jobs y lee las que nunca recibieron webhook.

El resto está en la lista de comprobación para producción.