영상 프레임으로 YouTube 썸네일 만들기: 추출·업스케일 API

Sume API로 영상 프레임에서 YouTube 썸네일을 만들려면 POST /v1/video-frames로 프레임을 소스 크기 그대로 추출하세요(at 시각 하나, format: "png", max_edge 없음). 그 프레임이 YouTube가 영상 썸네일에 권장하는 3840×2160보다 작으면 프레임의 URL을 POST /v1/image-upscale-1.0/upscale로 보내세요. 1920×1080 프레임이 이 크기가 되려면 upscale_factor: 2가 필요합니다.

YouTube의 규칙은 YouTube 고객센터의 맞춤 썸네일 도움말 Add custom thumbnails on YouTube에서 인용했으며, 이 페이지는 바뀔 수 있습니다. Sume 관련 사실은 영상 프레임, 영상 검사, Image API (영문) 문서와 Sume API 레퍼런스에서 가져왔습니다. 모두 2026-09-27에 확인했습니다. 프레임 호출 자체는 영상에서 프레임을 추출하는 방법에서 다룹니다.

YouTube는 썸네일에 어떤 크기와 형식을 요구하나요?

YouTube는 맞춤 썸네일을 가능한 한 크게 만들라고 안내하며, 이 이미지는 삽입된 플레이어의 미리보기 이미지로도 쓰입니다. 직접 만든 썸네일을 올리려면 인증된 계정이 필요하고, Shorts 맞춤 썸네일은 현재 컴퓨터의 YouTube Studio에서만 추가할 수 있습니다. 16:9 맞춤 썸네일을 단 세로 영상에는 홈, 탐색, 구독 페이지에서 자동 생성된 4:5 썸네일이 표시되므로, 썸네일의 모양을 영상의 모양에 맞추세요.

어떤 영상에서 프레임을 가져올 수 있나요?

이미 워크스페이스의 media.sume.com에 있는 클립만 가능합니다. 아바타 영상이나 Timeline 1.0 렌더처럼 앞서 실행한 Sume Job의 출력이 여기에 해당합니다. 프레임 도구는 공개 인터넷에서 영상을 가져오지 않으며, 에셋 업로드 경로는 공개 API에서 숨겨져 있습니다. 미디어 가져오기(POST /v1/media-imports)는 YouTube 링크나 임의의 영상 URL을 받지 않으며, 둘 다 unsupported_platform으로 거부됩니다.

• 영상 프레임은 최대 300초 길이의 소스를 읽으며, 그보다 긴 소스는 duration_out_of_range로 거부합니다.
• 최대 1,800초 길이의 소스라면 대신 영상 검사에 스틸을 요청하세요. at, format: "png", 그리고 소스의 긴 변 길이로 설정한 max_edge를 담은 frames 객체를 보내면 됩니다. 검사의 max_edge는 2160이 상한입니다.

프레임은 어떻게 고르고 추출하나요?

먼저 무료로 살펴보세요. frames 필드 없이 검사하면 긴 변 768픽셀의 구간 중간(mid-bin) 스틸 여덟 장을 과금 없이 반환합니다. 그다음 고른 순간을 영상 프레임으로 소스 크기 그대로 추출하세요. 이 호출도 과금되지 않습니다.

resource_status가 ready가 될 때까지 GET /v1/video-frames/:id를 폴링한 뒤 frames[0]을 읽으세요. 여기에는 url과 함께, 아래에서 업스케일 배율을 정하는 width와 height가 담깁니다. 추출에 실패한 시각은 Job을 실패시키지 않고 url: null로 돌아오므로, 먼저 이 값을 확인하세요.

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

프레임을 YouTube 권장 크기로 어떻게 업스케일하나요?

프레임의 URL을 image_url로 Image Upscale 1.0에 보내세요. 이 필드는 공개 HTTPS 이미지를 받으며, 완료된 Sume Job은 media.sume.com 아래의 공개 아티팩트를 반환합니다. upscale_factor는 1부터 4까지이고 기본값은 2입니다. output_format은 png(기본값), jpg, webp 중 하나이며, YouTube 페이지에는 JPG와 PNG가 나와 있습니다.

• 16:9 프레임에 필요한 배율은 3840을 프레임 너비로 나눈 값입니다. 1920×1080 프레임은 2, 1280×720 프레임은 3입니다.
• 9:16 Shorts 프레임에 필요한 배율은 2160을 프레임 너비로 나눈 값입니다. 1080×1920은 2, 720×1280은 3입니다.
• 배율은 4가 상한이므로, 너비가 960픽셀 미만인 16:9 프레임은 Job 한 번으로 3840에 이를 수 없습니다. 너비가 640픽셀 이상인 프레임은 이미 YouTube의 최솟값을 충족합니다.
• 이미지는 GET /v1/jobs/:id/result에서 읽으세요. 각 아티팩트에는 url이 있고, 보고된 경우 width, height, size_bytes도 있습니다. size_bytes를 모바일 한도인 2 MB와 비교해 확인하세요.
• 업스케일 비용은 API 요금에 나온 이미지당 $0.20이며, 기본적으로 5.5% 에이전트 수수료가 더해집니다. 나머지 필드는 AI 이미지 업스케일러 API에서 다룹니다.

curl -X POST https://api.sume.com/v1/image-upscale-1.0/upscale \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: thumbnail-upscale-001" \
  -d '{
    "image_url": "https://media.sume.com/artifacts/artf_demo/frame.png",
    "upscale_factor": 2,
    "output_format": "jpg"
  }'

업스케일 대신 프레임의 스타일을 바꿀 수 있나요?

네, 이미지 모델로 바꿀 수 있습니다. 프레임을 레퍼런스로 POST /v1/images에 넘기세요. 형식은 input_references: [{ "type": "image_url", "image_url": { "url": "…" } }]입니다. 레퍼런스 URL은 공개 HTTPS여야 하며, input_references 최댓값이 0인 모델은 레퍼런스를 거부합니다. 레퍼런스를 최대 16개 받는 openai/gpt-image-2.5에서는 image_size: { "width": 3840, "height": 2160 }이 사용자 지정 픽셀 규칙에 정확히 맞습니다. 두 변 모두 16의 배수이고, 3840은 최대 변 길이이며, 8,294,400픽셀은 상한입니다.

결과는 원래 프레임이 아니라 새로 생성된 이미지입니다. 호출은 최대 30초까지 대기하며, 그보다 오래 걸리는 생성은 폴링할 Job과 함께 202로 응답합니다. 비용은 모델 엔드포인트의 pricing에 n을 곱한 금액입니다. 요청 방법은 레퍼런스 이미지 기반 이미지 생성 API에서 다룹니다.

이 워크플로가 하지 않는 일은 무엇인가요?

Sume 단계는 완성된 이미지 파일에서 끝납니다.

• 외부 영상 없음: 소스는 Sume에 호스팅된 영상이어야 합니다.
• 일괄 업스케일 없음: Image Upscale 1.0은 Job당 image_url 하나를 받으며, 배율은 최대 4입니다.
• YouTube 업로드 없음. 파일은 YouTube Studio에서 직접 추가해야 하며, YouTube는 채널이 하루에 업로드할 수 있는 맞춤 썸네일 수를 제한합니다.