가이드: 이미지를 영상으로

영상은 몇 초가 아니라 몇 분이 걸리므로, 영상 연동은 기다리는 요청 하나가 아니라 작업과 웹훅을 중심으로 만듭니다. 이 가이드는 실제 모델 ID로 흔한 작업들을 살펴봅니다.

이미지 한 장 움직이기

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

곧바로 taskId가 담긴 202를 받습니다. 몇 분 뒤 웹훅이 완료된 작업을 보내 주거나, recordInfo로 읽을 수 있습니다. 영상은 output.assets[0]에 있으며 durationSeconds, width, height가 함께 옵니다.

비용

대부분의 영상 모델은 출력 1초당 과금하며 해상도가 높을수록 단가가 오릅니다. alibaba/wan-3.0/image-to-video는 480p에서 초당 6.75크레딧, 720p에서 13.5, 1080p에서 27입니다. 그래서 위 요청은 34크레딧(5 × 6.75, 올림)을 잡아 두고, 성공하면 같은 금액이 듭니다.

• 프롬프트를 다듬는 동안에는 가장 낮은 해상도와 짧은 길이로 돌리고, 최종본에서 올리세요.
• 사용자에게 가격을 보여 주기 전에 jobs/quote로 정확한 금액을 받으세요.
• 실패하거나 만료된 영상은 비용이 없습니다.

첫 프레임과 마지막 프레임 정하기

많은 이미지→영상 모델은 last_image_url도 받습니다. 클립은 image_url에서 시작해 last_image_url에서 정확히 끝납니다. 변신 연출이나, 두 곳에 같은 이미지를 넣은 매끄러운 루프에 쓰기 좋습니다.

참조 영상: 캐릭터나 제품을 일관되게

reference-to-video 모델은 주어진 첫 프레임을 움직이는 대신 하나 이상의 참조 이미지(모델에 따라 참조 영상이나 오디오도)를 바탕으로 새 장면을 만듭니다.

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

프롬프트에서 참조 자료를 부르는 방식은 모델마다 다릅니다. 레퍼런스 페이지의 필드 설명을 확인하세요.

클립 늘리기

video-extend 모델은 기존 클립의 마지막 프레임에서 이어 만듭니다. 클립을 video_url에 넣고 다음에 일어날 일을 쓰세요.

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

클립을 이어 붙이는 연장 모델은 에셋 두 개를 돌려줍니다. 먼저 이어 붙인 전체 영상(role: "video"), 그다음 새로 만든 부분만(role: "segment")입니다.

소리

generate_audio가 있는 모델은 클립에 사운드를 입힙니다. 일부 모델은 끄면 가격이 내려갑니다. 이미 있는 영상에 소리를 넣고 싶다면 popnow/foley-v1/video-to-audio를 쓰세요. 같은 영상에 생성한 소리를 입혀 돌려줍니다.

영상에 잘 먹히는 프롬프트

장면만이 아니라 움직임을 쓰세요. 무엇이 움직이는지, 얼마나 빠른지, 카메라는 무엇을 하는지. "카메라가 천천히 다가가고 인물이 빛 쪽으로 돌아선다"는 모델에게 할 일을 주지만 "아름다운 등대"는 그렇지 않습니다. 생김새는 이미지가 이미 말해 주니 글자는 변화에 쓰세요.

실서비스 패턴

1. 원본 이미지를 업로드하거나 저장하고 popnow:// URI를 보관합니다.
2. 견적을 받아 가격을 보여 준 뒤, 내 작업 ID에서 만든 Idempotency-Key와 callBackUrl을 붙여 createTask를 호출합니다.
3. 웹훅에서 서명을 검증하고 먼저 응답한 다음 영상을 내 저장소로 내려받습니다.
4. 하루에 한 번 GET /api/v1/jobs로 최근 작업을 나열해 웹훅을 받지 못한 작업을 읽습니다.

나머지는 출시 전 점검표를 보세요.