Video 1.0·Image 1.0 곧 은퇴: sume/auto로 옮기기

Sume Video 1.0과 Image 1.0은 곧 은퇴하며, 둘 다 이미 Router Auto 경로의 호환 별칭으로 동작합니다. 두 제품의 URL은 레거시 요청 형태를 계속 받지만, Sume는 같은 Auto 모델 선택을 실행하고 Job에 sume/auto를 표시합니다. 문서는 새 연동이라면 model: "sume/auto"로 POST /v1/videos나 POST /v1/images를 호출하라고 안내합니다.

아래 내용은 Video 1.0 (영문)과 Image 1.0 (영문) 페이지, 그리고 이 페이지들이 안내하는 Video generation (영문), Video Router (영문), Image API (영문) 페이지에서 가져왔습니다.

“retiring soon”은 지금 내 연동에 어떤 의미인가요?

문서에는 “retiring soon”(곧 은퇴)이라고만 적혀 있고 날짜는 없습니다. 그때까지 레거시 URL은 계속 동작합니다.

• Video 1.0 URL은 Auto 경로와 같은 Auto 모델 선택, 기능 검증, 요금을 사용합니다. Job 영수증에는 sume/auto가 표시됩니다.
• routing_preset은 지원 중단되어 무시되며, 어떤 값을 보내도 Auto를 씁니다.
• Image 1.0 URL은 아바타 레퍼런스와 투명 배경을 포함한 레거시 형태를 계속 받으며, job.model: "sume/auto"를 반환합니다.

sume/auto로 영상 요청은 어떻게 보내나요?

레거시 영상 URL은 model 필드를 받지 않습니다. POST /v1/videos에서는 Auto 경로를 유지하려면 model: "sume/auto"를, 패밀리를 고정하려면 카탈로그 id를 보내세요. 이 경로는 OpenRouter 영상 생성 API를 필드 단위로 똑같이 따릅니다. OpenRouter 호환 영상 API를 참고하세요.

호출은 id, polling_url, status: "pending"과 함께 202를 반환합니다. completed가 될 때까지 GET /v1/videos/{jobId}를 폴링한 뒤 unsigned_urls[0]이나 GET /v1/videos/{jobId}/content?index=0에서 내려받으세요. 같은 Job은 GET /v1/jobs/{id}/status와 GET /v1/jobs/{id}/result에서도 볼 수 있습니다.

curl -X POST "https://api.sume.com/v1/videos" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: video-auto-001" \
  -d '{
    "model": "sume/auto",
    "prompt": "A vertical UGC-style product clip on a desk, natural light",
    "aspect_ratio": "9:16",
    "duration": 5
  }'

Video 1.0 필드는 어디로 옮기나요?

Video 1.0은 URL 필드를 평면 구조로 받습니다. POST /v1/videos는 이미지를 두 배열로 받습니다. 첫 프레임과 마지막 프레임은 frame_images, 레퍼런스 이미지는 input_references입니다. resolution, aspect_ratio, 정수 초 단위 duration은 이름이 그대로입니다.

이미지 호출은 POST /v1/images로 어떻게 옮기나요?

Auto 선택을 유지하려면 model: "sume/auto"를, 패밀리를 고정하려면 카탈로그 id를 보내세요. 그다음 본문과 응답 처리를 조정합니다. 이 경로 전체는 레퍼런스 이미지 기반 이미지 생성에서 다룹니다.

• 레퍼런스 이미지는 image_urls(URL 1–10개)에서 타입이 image_url인 input_references 항목으로 옮깁니다. 둘 다 공개 HTTPS URL만 받습니다.
• 이미지 수는 num_images(1–4)에서 n(1–10, 모델별 상한은 더 낮음)으로 바뀝니다.
• 이 경로의 기본값은 sync입니다. 최대 30초 동안 블로킹하며 data[].url과 함께 200을 반환하거나, 이미지가 아직 준비되지 않았으면 표준 Job 봉투와 함께 202를 반환합니다. 상태 코드로 분기하세요.
• 문서화된 예외가 하나 있습니다. 현재 투명 배경 스틸이 필요하면, Image API 페이지는 transparency: true를 쓴 Image 1.0을 쓰라고 안내합니다.

전환한 뒤에도 그대로인 것은 무엇인가요?

두 경로 모두 Auto는 어떤 패밀리가 실행됐는지 숨깁니다. 응답은 sume/auto를 그대로 돌려주며, 문서는 출력에서 관찰되는 특성으로 패밀리를 추정하는 로직을 만들지 말라고 안내합니다. POST /v1/videos에서 Auto의 해석은 정규화된 요청과 카탈로그 버전만으로 정해지는 순수 함수이므로, 멱등 재전송은 가격과 라우팅이 똑같습니다. 재시도를 안전하게 하려면 Idempotency-Key를 보내세요. 재전송하면 원래 Job이 반환됩니다.

영상 Job은 제출 시 워크스페이스 USD 잔액에서 금액을 예약하며, 두 경로 모두 usage.cost가 청구 금액을 알려 줍니다. 요율은 API 요금에 있습니다.

Video Router와 Image Router 경로는 어떻게 되나요?

POST /v1/video-router/generate는 바뀌지 않은 채 계속 제공되며, 같은 모델 id로 같은 Job을 만듭니다. 모델 어휘를 공유하므로 POST /v1/videos로 옮기는 일은 id를 다시 매핑할 필요 없이 경로와 본문만 바꾸는 작업입니다. 레거시 POST /v1/image-router/generate와 GET /v1/image-router/models 경로도 그대로 동작하지만, POST /v1/images로 대체되어 지원 중단되었으며 새 파라미터는 추가되지 않습니다.

전환하기 전에 무엇을 확인해야 하나요?

문서화된 다음 제한을 알아 두면 예상치 못한 문제를 대부분 피할 수 있습니다.

• 레거시 영상 URL에서는 4k가 거부됩니다. 4K가 필요하면 sume/auto로 POST /v1/videos를 쓰세요.
• 현재 Auto 패밀리는 항상 오디오를 생성하므로 레거시 URL에서는 generate_audio를 생략하세요. Auto는 bitrate_mode를 거부합니다.
• POST /v1/videos에서 size는 400 unsupported_parameter를 반환합니다. 모든 v1 모델이 supported_sizes: null을 보고하기 때문입니다. resolution과 aspect_ratio를 쓰세요. seed를 받는 v1 모델은 없으며, 비어 있지 않은 provider.options는 400 unsupported_parameter를 반환합니다.
• POST /v1/images에서 stream: true는 400 streaming_not_supported를 반환하고, seed, output_compression, 명시적 픽셀 size는 400 unsupported_parameter를 반환합니다.
• POST /v1/videos의 웹훅은 x-sume-webhook-signature로 서명된 Sume 표준 Job 웹훅 봉투를 씁니다.