API로 영상의 마지막 프레임을 추출해 AI 클립 잇기

Sume API로 영상의 마지막 프레임을 추출하려면 무료 POST /v1/video-inspect 프로브에서 클립의 duration_seconds와 fps를 읽은 뒤, POST /v1/video-frames에 끝 바로 앞 시각의 PNG를 요청하세요. 요청하는 모든 시각은 0 <= t < duration을 만족해야 하기 때문입니다. 반환된 media.sume.com 이미지는 POST /v1/videos의 first_frame이 되어 다음 클립을 여는 데 쓸 수 있습니다.

아래 내용은 2026-09-26에 확인한 영상 프레임, 영상 검사, 영상 생성 (영문) 문서와 Sume API 레퍼런스를 기준으로 합니다.

왜 영상 길이와 같은 시각의 프레임은 요청할 수 없나요?

영상 프레임은 클립 안쪽의 순간만 받습니다. 각 at 값은 0 <= t < duration을 만족해야 하며, 그렇지 않으면 워커가 frame_time_out_of_range로 실패하면서 프로브된 길이를 알려 줍니다. 그러니 길이부터 확인하세요. frames: false로 검사하면 스틸 없이 프로브만 하며, 프로브는 과금되지 않습니다. 검사의 기본값은 mode: sync이고, 가능하면 30초 안에 200으로 응답합니다.

프로브에는 다른 컨테이너 정보와 함께 duration_seconds와 fps가 담깁니다. 검사는 여러분 워크스페이스의 media.sume.com 클립만, 최대 1,800초까지 읽습니다.

curl -X POST https://api.sume.com/v1/video-inspect \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: clip-a-probe-001" \
  -d '{
    "video_url": "https://media.sume.com/artifacts/artf_demo/clip-a.mp4",
    "frames": false
  }'

마지막 프레임은 어느 타임스탬프인가요?

끝에서 한 프레임 간격만큼 앞선 시각, 즉 t = duration_seconds - 1 / fps를 요청하세요. 이 공식은 문서의 규칙이 아니라 저희가 직접 계산한 것이며, 한 프레임만큼 여유를 두고 [0, duration) 안에 머뭅니다. 24 fps의 5초 클립이면 4.9583…초가 나오며, 소수 자릿수를 줄인다면 4.958처럼 내림하세요.

이 작업에는 검사 스틸이 아니라 영상 프레임을 쓰세요. 검사 문서는 한 t 시점의 정확한 소스 크기 프레임을 영상 프레임으로 안내하며, 검사 스틸은 기본적으로 긴 변이 768픽셀로 제한되지만 영상 프레임은 이 제한을 두지 않습니다.

프레임을 원본 크기로 추출하려면 어떻게 하나요?

그 시각 하나를 담은 at과 무손실 옵션인 format: "png"를 보내고, max_edge는 생략해 소스 프레임 크기를 유지하세요. 문서는 이를 리스테이지 경로라고 부릅니다. 제출, 폴링, 결과 형태는 다른 추출과 같으니 영상에서 프레임을 추출하는 방법을 참고하세요.

클립을 이을 때 중요한 세부 사항이 하나 있습니다. 추출에 실패한 순간은 Job을 실패시키지 않고 url이 null인 채로 돌아오므로, 넘기기 전에 frames[0].url을 확인하세요.

curl -X POST https://api.sume.com/v1/video-frames \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: clip-a-last-frame-001" \
  -d '{
    "video_url": "https://media.sume.com/artifacts/artf_demo/clip-a.mp4",
    "at": [4.958],
    "format": "png"
  }'

추출한 프레임을 다음 클립으로 어떻게 잇나요?

프레임을 frame_images에 담아 POST /v1/videos로 넘기세요. 각 항목은 type: "image_url"이며 image_url.url과, 값이 first_frame 또는 last_frame인 frame_type을 담습니다. first_frame으로 넘기면 이전 클립의 끝 장면이 새 클립의 시작이 됩니다. GET /v1/videos/models에서 supported_frame_images에 first_frame이 나열된 모델을 지정하세요. input_references도 함께 보내면 frame_images가 우선하며, 요청은 이미지로 영상 만들기로 처리됩니다. 생성 쪽은 첫 프레임과 마지막 프레임을 지정하는 Image-to-Video API에서 다룹니다.

curl -X POST https://api.sume.com/v1/videos \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: clip-b-001" \
  -d '{
    "model": "seedance-2",
    "prompt": "The camera keeps moving forward along the same path",
    "frame_images": [
      {
        "type": "image_url",
        "image_url": { "url": "https://media.sume.com/artifacts/artf_demo/last.png" },
        "frame_type": "first_frame"
      }
    ]
  }'

생성한 클립의 Sume 호스팅 URL은 어디서 얻나요?

영상 프레임과 검사에는 여러분 워크스페이스의 media.sume.com URL이 필요한데, /v1/videos 폴링은 그 대신 API 호스트의 unsigned_urls를 반환합니다. 같은 Job은 GET /v1/jobs/{id}/result에서도 볼 수 있으며, Sume는 생성된 출력을 결과에 나타나기 전에 미러링해 media.sume.com 아래의 Sume 호스팅 아티팩트로 반환합니다. 이어 붙일 클립마다 프로브, 프레임 추출, 생성을 반복한 뒤 Timeline 1.0으로 클립을 이어 붙이세요.

한도는 어떻게 되나요?

두 미디어 단계는 무료이고, 생성만 모델별로 과금됩니다. GET /v1/videos/models는 모델마다 pricing_skus를 알려 주며, GET /v1/catalog에도 가격 메타데이터가 있습니다.