Image-to-Video API: 첫 프레임과 마지막 프레임 지정

Sume API로 스틸 이미지를 영상으로 만들려면 frame_images 배열을 담아 POST /v1/videos를 보내세요. frame_type: "first_frame"인 항목은 클립의 첫 프레임을, 선택 사항인 "last_frame" 항목은 마지막 프레임을 지정합니다. 카탈로그의 모든 영상 모델은 첫 프레임을 받고, grok-imagine-video-1.5를 제외한 모든 모델은 마지막 프레임도 받습니다.

아래 필드 규칙은 영상 생성 문서 (영문)에서 가져왔습니다. 모델별 지원 여부는 GET /v1/videos/models가 반환하는 카탈로그에서 2026-09-26에 확인했습니다.

첫 프레임과 마지막 프레임은 어떻게 보내나요?

frame_images의 각 항목에는 type: "image_url", url을 담은 image_url 객체, 그리고 값이 first_frame 또는 last_frame인 frame_type이 들어갑니다. 아래 요청은 문서의 이미지로 영상 만들기 예제를 고쳐, 1080p Seedance 2.0 클립의 처음과 끝을 모두 고정한 것입니다.

• 이미지 URL은 가져올 수 있는 공개 HTTPS URL이어야 합니다. localhost, 사설 네트워크 URL, HTTPS가 아닌 URL, 서명된·비공개 URL은 Job이 제출되기 전에 거부됩니다.
• 재시도를 안전하게 하려면 Idempotency-Key를 보내세요. 재전송하면 원래 Job이 반환됩니다.
• 호출은 Job id와 polling_url을 담아 202를 반환합니다. status가 completed가 될 때까지 폴링한 뒤 unsigned_urls[0]에서 내려받으세요.

curl -X POST https://api.sume.com/v1/videos \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: i2v-first-last-001" \
  -d '{
    "model": "seedance-2",
    "prompt": "A character walking through a forest",
    "frame_images": [
      {
        "type": "image_url",
        "image_url": { "url": "https://example.com/first-frame.png" },
        "frame_type": "first_frame"
      },
      {
        "type": "image_url",
        "image_url": { "url": "https://example.com/last-frame.png" },
        "frame_type": "last_frame"
      }
    ],
    "resolution": "1080p"
  }'

어떤 모델이 첫 프레임, 마지막 프레임, 또는 둘 다를 받나요?

각 모델은 받는 frame_type 값을 supported_frame_images에 나열합니다. 텍스트로 영상 만들기도 지원하는 모델은 프레임을 보내지 않으면 프롬프트만으로 실행됩니다. grok-imagine-video-1.5는 이미지로 영상 만들기 전용입니다. 첫 프레임이 필수이고 끝 프레임은 받지 않습니다.

프레임과 레퍼런스를 함께 보내면 어떻게 되나요?

frame_images가 우선합니다. 요청에 frame_images와 input_references가 모두 있으면 Sume는 이를 이미지로 영상 만들기로 처리하고, 레퍼런스는 모델에 전달하지 않습니다. 프레임 이미지는 클립의 첫 프레임이나 마지막 프레임을 지정하고, 레퍼런스는 정확한 프레임이 아니라 시각적 가이드입니다. 레퍼런스는 Reference-to-Video API에서 다룹니다.

이미지로 영상 만들기 요청은 왜 거부됐나요?

POST /v1/videos는 보낸 프레임을 모델의 카탈로그 항목과 대조하고, 맞지 않으면 400과 오류 코드 unsupported_capability로 거부합니다. 거부되는 경우는 다음과 같습니다.

• first_frame 없이 보낸 last_frame: “frame_images with a last_frame also requires a first_frame.”
• grok-imagine-video-1.5의 last_frame처럼 모델이 나열하지 않은 frame_type: “grok-imagine-video-1.5 does not support frame_type last_frame.” 오류 details에는 모델의 supported 값이 담깁니다.
• resolution, aspect_ratio, duration도 같은 방식으로 모델의 목록과 대조됩니다. 길이는 모델별 AI 영상 길이 제한을 참고하세요.

코드가 아직 image_url과 end_image_url을 보낸다면 어떻게 하나요?

이 둘은 이전 경로의 평면 필드입니다. 곧 은퇴하는 Video 1.0과, 바뀌지 않고 계속 동작하는 Video Router는 첫 프레임을 image_url로, 끝 프레임을 end_image_url로 받습니다. 필드별로 옮기는 방법은 Video 1.0·Image 1.0 곧 은퇴에 있습니다.

model이 카탈로그 ID일 때는 프레임 규칙 두 가지가 경로마다 다릅니다. POST /v1/videos는 평면 필드를 400 invalid_request로 거부하므로, 이 경로에는 frame_images를 보내세요. POST /v1/video-router/generate는 첫 프레임과 reference_*_urls가 한 요청에 함께 오면 거부하지만, /v1/videos에서는 프레임이 우선합니다.

이미지로 만든 영상 클립의 요금은 어떻게 청구되나요?

다른 영상 Job과 같습니다. 제출 시 워크스페이스 USD 잔액에서 공급사 정가 × 1.25로 비용이 예약되고, 기본 5.5% 에이전트 수수료가 더해집니다. 요율은 각 모델이 GET /v1/videos/models의 pricing_skus에 나열한 값을 씁니다. API 요금을 참고하세요.