Sume API 빠른 시작: 다섯 단계로 첫 영상 생성 호출하기

첫 Sume API 호출은 다섯 단계면 됩니다. 대시보드에서 API 키를 만들고, model: "sume/auto"와 프롬프트를 담아 POST https://api.sume.com/v1/videos 요청을 한 번 보내고, Job이 끝날 때까지 반환된 polling_url을 폴링하고, unsigned_urls에서 영상을 내려받은 다음, 무엇을 만들지 고르면 됩니다.

각 단계는 2026-09-26에 확인한 Sume 문서 영상 생성 (영문), 인증, API 개요 (영문)를 따릅니다. 영상 생성은 비동기 Job입니다. 호출하면 곧바로 ID가 돌아오고, 영상은 나중에 도착합니다.

1단계: Sume API 키는 어떻게 만드나요?

API Keys 대시보드에서 키를 만드세요. 키는 워크스페이스 단위이고, 대시보드는 키를 만들 때만 전체 시크릿을 보여 주므로 곧바로 시크릿 매니저에 저장하세요.

키는 서버에 두고, 프론트엔드 JavaScript나 모바일 앱에는 절대 넣지 마세요. 키는 Authorization: Bearer나 x-api-key 중 하나로만 보내세요. 둘을 함께 실은 요청은 401 unauthorized가 됩니다. GET /v1/me는 키와, 그 키로 해석되는 워크스페이스를 확인해 줍니다. 자세한 내용은 Sume API 키 동작 방식에 있습니다.

export SUME_API_KEY="sume_live_..."

curl https://api.sume.com/v1/me \
  -H "Authorization: Bearer $SUME_API_KEY"

2단계: 첫 영상 요청은 어떻게 보내나요?

POST /v1/videos에는 model과 prompt가 필수입니다. Sume가 모델을 고르게 하려면 sume/auto를 보내세요. Auto의 기본값은 720p, 8초이며 16:9 또는 9:16 비율의 3–10초 클립을 받습니다. 대신 모델을 고정하려면 seedance-2처럼 GET /v1/videos/models에 나오는 접두사 없는 카탈로그 id를 보내세요. Idempotency-Key 헤더를 붙이면 재시도가 안전해집니다. 같은 키로 다시 보내면 원래 Job이 돌아옵니다.

curl -sS -X POST "https://api.sume.com/v1/videos" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: first-video-001" \
  -d '{
    "model": "sume/auto",
    "prompt": "A golden retriever playing fetch on a sunny beach",
    "aspect_ratio": "16:9",
    "duration": 5
  }'

3단계: 영상이 준비됐는지는 어떻게 알 수 있나요?

제출하면 202 Accepted와 함께 id, polling_url, status: "pending", 그리고 sume/auto를 그대로 되돌려 주는 model 필드가 옵니다. status가 completed, failed, cancelled 중 하나가 될 때까지 polling_url인 GET /v1/videos/{jobId}를 폴링하세요. 문서는 폴링 간격으로 약 30초를 권하며, 영상 생성은 모델과 파라미터에 따라 보통 30초에서 몇 분이 걸립니다. 자세한 내용은 AI 영상 생성에 걸리는 시간에 있습니다.

폴링을 건너뛰려면 HTTPS URL인 callback_url을 보내세요. Job이 종료 상태에 도달하면 Sume가 서명된 웹훅을 POST합니다. 같은 Job은 GET /v1/jobs/{id}/status에서도 볼 수 있습니다. 클라이언트 연결이 끊기거나 타임아웃되면, 유료 작업을 중복 제출하지 말고 ID를 보관했다가 Jobs API로 복구하세요.

4단계: 완성된 영상은 어떻게 받나요?

status가 completed가 되면 unsigned_urls에 다운로드 URL이 들어 있습니다. content 엔드포인트를 직접 호출할 수도 있습니다. index의 기본값은 0이며, 모델이 출력을 여러 개 돌려줄 때 그중 하나를 고릅니다. 폴링 응답에는 Sume 청구 금액인 usage.cost도 나오며, 이 금액은 제출 시점에 워크스페이스 USD 잔액에서 예약됩니다.

failed가 나오면, 문서의 문제 해결 목록은 error 필드를 읽고, 프롬프트를 모델 가이드라인 안에서 작성하고, 레퍼런스 이미지가 있다면 지원되는 형식이며 공개 HTTPS로 접근할 수 있는지 확인하라고 안내합니다.

curl "https://api.sume.com/v1/videos/job_123/content?index=0" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  --output video.mp4

5단계: 첫 호출 다음에는 어디로 가야 하나요?

무엇을 만드는지에 따라 다음 페이지를 고르세요.

• 클립 하나가 아닌 패키지된 워크플로: 대부분의 파트너 연동은 저장된 레시피인 Format을 한 번 호출하는 방식입니다. Sume Format이란?부터 시작하세요.
• 사람이 루프에 남아야 할 때: 설치할 것 없이 에이전트 탭에서 에이전트에게 브리프를 준 다음 레시피를 저장하세요. 영상 에이전트란 무엇인가요?를 참고하세요.
• 모델 한도: GET /v1/videos/models는 모델마다 해상도, 화면 비율, 길이, 가격 SKU를 나열합니다. 영상 모델 목록 조회를 참고하세요.
• TypeScript: @sume-com/sdk는 공개 OpenAPI 스키마의 모든 오퍼레이션을 다룹니다. TypeScript SDK 빠른 시작을 참고하세요.
• 정확한 필드: 라이브 스키마는 https://api.sume.com/reference/json이고, Swagger UI는 api.sume.com/reference에 있습니다.
• 이전 코드: Video 1.0은 곧 은퇴합니다. 새 연동은 sume/auto와 함께 POST /v1/videos를 씁니다(마이그레이션 가이드).

첫 호출이 실패하면 어떻게 하나요?

첫 호출에서 자주 만나는 오류는 다음과 같습니다. 전체 목록은 Sume API 오류와 요청 한도에 있습니다.

• 401 unauthorized: 키가 없거나, 형식이 잘못됐거나, 폐기된 경우, 또는 요청에 인증 헤더를 둘 다 보낸 경우입니다.
• 400 unsupported_parameter: /v1/videos에 size나 비어 있지 않은 provider.options가 들어온 경우입니다. size 대신 resolution과 aspect_ratio를 쓰세요. seed도 거부됩니다.
• 404 model_not_found: 존재하지 않는 모델 id입니다. Sume는 org/slug가 아니라 접두사 없는 카탈로그 id를 씁니다.
• 402 insufficient_credits: 워크스페이스 잔액으로 예상 비용을 감당할 수 없습니다. Billing & subscription에서 크레딧을 구매하세요.
• 429 queue_full 또는 429 rate_limited: 워크스페이스에 남은 수락 Job 용량이 없거나 요청 예산을 다 쓴 경우입니다. 기다렸다가 같은 Idempotency-Key로 재시도하세요.