Sume API 상태 값 정리: Job, 실행, 큐, 웹훅
Sume API 상태 값을 한곳에 모았습니다. Job, /v1/videos, Format·Agent 실행, 대량 실행 큐, 웹훅 전달, 사용량 행, 공유 권한, 잔액까지 다룹니다.
개발자
Sume API로 개발할 때 필요한 글입니다. API 키와 호스트, 작업과 실행, 폴링, 웹훅, 멱등성, 오류와 요청 한도, SDK, CLI, MCP 인증을 다룹니다.
먼저 읽을 글: Sume API 빠른 시작: 다섯 단계로 첫 영상 생성 호출하기
Sume API 오류 코드 총정리: 표면별 색인과 다음 조치
Sume API 오류 코드를 표면별로 정리했습니다. 공통 코드, 유료 생성, Format, Scheduled 실행, Agent Completions, 미디어 도구, 호스팅 MCP를 다룹니다.
Sume API 페이지네이션: cursor·starting_after·한도
Sume 목록 엔드포인트별 페이지 넘김 방식입니다. Format과 실행 목록은 cursor와 has_more, /v1/jobs는 starting_after를 쓰고, limit만 받는 목록에는 커서가 없습니다.
Sume API 헤더: 인증, 멱등성 키, If-Match, 요청 한도
Sume API가 읽거나 보내는 모든 HTTP 헤더를 정리했습니다. API 키, Content-Type, Idempotency-Key, If-Match, 요청 ID, 요청 한도, 웹훅 서명을 다룹니다.
Sume API 용어집: Format 실행, 지출 상한, 멱등성 키
Sume API 용어를 한두 문장씩 설명합니다. Format, 실행, Job, 지출 상한, 멱등성 키, 지갑, 에이전트 수수료, 웹훅, 아티팩트 등을 관련 글 링크와 함께 정리했습니다.
AI 영상 생성 API 고르는 법: 12가지 체크리스트
AI 영상 생성 API는 Job, 재시도, 웹훅, 지출 상한, 실패, 출력물을 어떻게 다루는지를 보고 고르세요. 항목마다 Sume의 답을 붙인 체크리스트입니다.
AI 생성 영상 URL은 만료되나요? Sume의 결과물 보관 방식
Format 실행과 Agent Completions에서는 만료되지 않습니다. Sume는 그 미디어를 만료되지 않는 media.sume.com URL로 돌려주며, 링크를 가진 누구나 열 수 있습니다.
Sume API에서 생성한 영상 다운로드하기: 401과 302
Sume의 unsigned_urls는 API 키가 필요하고 302 리다이렉트로 응답합니다. curl -L이나 코드로 MP4를 내려받고, 401, 404, 409를 각각 해결하세요.
웹훅 URL이 유효하지 않다고 거부되나요? Sume 웹훅 URL 규칙
웹훅 URL이 공개 HTTPS가 아니면 Sume는 400 invalid_request로 응답합니다. 스킴, 호스트, 포트, 자격 증명 규칙과 전달 시점의 검사를 정리했습니다.
Sume API 미디어 URL 규칙: 엔드포인트별 허용 URL
Sume 생성 엔드포인트는 공개 HTTPS 미디어 URL을 가져옵니다. 트림, 필터, 프레임, 검사, Timeline은 워크스페이스에 있는 media.sume.com URL만 받습니다.
Sume Job 타입과 동시성: 슬롯을 차지하는 호출
Sume 엔드포인트별 Job 타입과 슬롯 사용 여부입니다. 트림과 Timeline을 포함한 모든 생성 Job은 동시성 슬롯을 차지하고, 프레임과 검사는 차지하지 않습니다.
Sume API 엔드포인트 목록: 경로, 스코프, 멱등성
Sume API의 공개 경로를 계열별로 정리한 색인입니다. 키가 필요 없는 경로, 계열별 스코프, Idempotency-Key 적용 위치, 계열별 설명 글을 담았습니다.
Sume API 출력 파일 형식: MP4·PNG·WebP·WAV·MP3
Sume API 엔드포인트별로 반환하는 파일입니다. Timeline과 편집 도구는 MP4, 이미지는 PNG·JPEG·WebP, 오디오는 WAV나 MP3, 전사문은 JSON입니다.
브라우저에서 Sume API 호출 시 CORS 오류: 해결 방법
브라우저는 내 사이트에서 api.sume.com으로 직접 보내는 호출을 차단하며, API 키는 프론트엔드 코드에 절대 넣으면 안 됩니다. 서버에서 Sume를 호출해 프록시하세요.
Sume MCP 서버 OAuth 플로: 디스커버리·동의·PKCE·스코프
Sume 호스팅 MCP 서버는 자체 OAuth를 운영합니다. 401이 디스커버리 메타데이터를 가리키고, 사용자가 mcp.sume.com에서 동의하면 PKCE S256으로 한 시간짜리 토큰을 받습니다.
Sume MCP insufficient_scope·누락 도구·타임아웃 해결
Sume MCP의 insufficient_scope 오류는 OAuth 세션에 mcp:write가 없다는 뜻입니다. mcp_health부터 호출한 뒤 스코프, 누락된 도구, 타임아웃을 해결하세요.
Sume 에이전트 실행 오류: action_run_in_progress 등
스케줄 실행이 이미 진행 중인데 reject를 보내면 409 action_run_in_progress, ID가 내 Agent Completion 실행이 아니면 404 agent_run_not_found입니다.
CI와 헤드리스 서버에서 Sume CLI 실행하기
CI에서는 버전을 고정한 릴리스 바이너리, 시크릿 저장소의 SUME_API_KEY, 격리된 SUME_CONFIG_DIR, doctor 사전 점검, --json 출력으로 Sume CLI를 실행하세요.
Sume CLI 명령어 레퍼런스: 계정, Job, 에셋, skills
Sume CLI에는 생성 외에도 로그인과 계정, health·doctor 점검, 스키마 탐색, Job, 에셋, 배치 헬퍼, skills, 별칭 명령어가 있습니다.
Sume CLI가 안 될 때: 로그인·API 베이스·Job·미디어 해결법
Sume CLI가 안 될 때는 읽기 전용 점검 네 가지를 먼저 실행한 뒤, 키 누락, 잘못된 API 베이스, 끝나지 않은 Job, 거부된 미디어 URL 중 해당하는 원인을 고치세요.
영상 생성 모델 목록 API: GET /v1/videos/models
GET /v1/videos/models는 Sume의 모든 영상 모델을 해상도, 화면 비율, 길이, 프레임·레퍼런스 유형, 오디오 여부, 가격 SKU와 함께 보여 줍니다.
영상 생성 Job 상태 API 폴링하기: Sume의 /v1/jobs
terminal이 true일 때까지 GET /v1/jobs/{id}/status를 next_poll_after_seconds 간격으로 폴링하고, result_ready가 true면 /result를 읽으세요.
영상 생성 API 동기 vs 비동기: Sume의 네 가지 제출 모드
Sume의 제출 모드는 async, sync, subscribe, webhook입니다. sync와 subscribe는 최대 30초만 기다리므로, 영상은 async로 제출해 폴링하거나 웹훅을 받으세요.
Sume TypeScript SDK 빠른 시작: 설치·클라이언트·오류·재시도
@sume-com/sdk를 설치하고 createSumeClient로 클라이언트 하나를 만든 뒤, throw 대신 오류를 반환하는 타입 지정 오퍼레이션을 호출하세요. 재시도는 기본으로 들어 있습니다.
AI 영상 생성 Job은 왜 실패했나요? Job 오류 읽는 법
실패한 Sume Job에는 category, stage, retryable, public_reason, next_action이 담긴 공개 오류가 있습니다. 읽는 곳과 필드별로 할 일을 설명합니다.
TypeScript SDK에서 Sume Job·실행이 끝날 때까지 기다리기
waitForJob, waitForRun, subscribeFormatRun은 Sume Job이나 실행이 끝날 때까지 폴링합니다. 기본 타임아웃, throw하는 오류, 재시도를 정리했습니다.
Job 목록 API: 상태별 영상 Job 필터링과 잃어버린 ID 복구
GET /v1/jobs는 워크스페이스 Job을 최신순으로 페이지당 100개까지, status·type·run_id로 걸러 나열합니다. starting_after로 넘기고 idempotency_key로 매칭하세요.
Sume API 카탈로그: 사용 가능한 모델·엔드포인트·가격 조회
GET /v1/catalog는 Sume API 기능을 모델 ID, 호출 URL, 가용성, 런타임 준비 상태, 가격과 함께 나열합니다. API 키가 필요 없습니다.
Sume API OpenAPI 스펙: 다운로드·탐색·클라이언트 생성
api.sume.com/reference/json에서 Sume API의 라이브 OpenAPI 스펙을 내려받고, Swagger UI에서 살펴보고, TypeScript 외의 언어용 클라이언트를 생성하세요.
Sume 생성 Job과 Format·Action·Agent 실행의 차이
Sume Job은 /v1/jobs에서 추적하는 생성 요청 하나이고, 실행은 Format, 스케줄, Agent Completion이 시작한 에이전트 턴 하나입니다. ID, 웹훅, 대기 방법이 다릅니다.
Sume 웹훅이 도착하지 않나요? 전달·서명 디버깅 방법
Sume 웹훅이 도착하지 않으면 Job이나 실행의 webhook_delivery를 읽고, 테스트 전송으로 엔드포인트를 확인한 뒤, 실제 이벤트를 다시 보내세요.
AI 영상 생성은 얼마나 걸리나요? Sume Job, 실행, 한도
Sume 문서 기준 영상 Job 하나는 30초에서 몇 분, 롱폼 Format 실행은 15~30분이 걸립니다. 실행 단계와 멈춤 신호, 한도를 정리했습니다.
AI 영상 생성 API 진행 상황 업데이트: 푸시 스트림 없이
Sume에는 SSE나 WebSocket 진행 상황 스트림이 없습니다. Job 이벤트나 Format 실행의 phase 타임라인을 폴링하고, 아바타 장면 스틸을 보여 주되 ETA는 약속하지 마세요.
Sume API로 AI 영상 생성 Job이나 실행을 취소하는 방법
Sume 생성 Job은 생성이 시작되기 전에만 취소되고, Format·Action·Agent 실행 취소는 멱등입니다. 경로, 응답, 과금, 웹훅을 정리했습니다.
영상 생성 API 타임아웃: Sume 대기 상한, SDK 기본값, 만료
Sume의 sync 제출은 최대 30초, SDK 대기는 기본 10–20분을 기다리지만, 클라이언트 타임아웃은 Job을 절대 취소하지 않습니다. 모든 한도와 직접 정할 마감 시간을 정리했습니다.
영상 생성 API 400 오류: 지원되지 않는 파라미터와 해결법
POST /v1/videos 400 원인과 해결: invalid_request, unsupported_parameter(size·seed·provider.options), unsupported_capability.
Sume request_id·job_id·run_id: 저장하고 문의할 ID
Job이나 실행 ID를 저장하고, 웹훅은 job_id나 실행 봉투의 request_id로 중복을 제거하고, Sume 지원팀에는 req_ 요청 ID를 Job이나 실행 ID와 함께 알려 주세요.
Sume API 빠른 시작: 다섯 단계로 첫 영상 생성 호출하기
Sume API 키를 만들고, sume/auto로 POST /v1/videos 요청을 한 번 보낸 뒤, Job을 폴링하고 영상을 내려받으세요. 짧은 다섯 단계와 그다음 갈 곳을 정리했습니다.
Sume 개발자 대시보드: API 키·사용량·Job·결제·플레이그라운드
Sume 개발자 대시보드를 페이지별로 소개합니다. API 키 생성, Billing & subscription에서 크레딧 구매, Jobs·Usage 확인, 플레이그라운드에서 Avatar 시험을 다룹니다.
AI 영상 API 멱등성 키: 이중 과금 없이 재시도하기
멱등성 키를 쓰면 재시도한 생성 요청이 두 번째 유료 작업 대신 원래 실행이나 Job을 돌려줍니다. Sume의 Idempotency-Key가 API별로 어떻게 동작하는지 설명합니다.
무인 AI 에이전트 지출 상한: Sume가 실행별 지출을 제한하는 법
무인 에이전트에는 지출을 승인할 사람이 없어 Sume는 실행마다 생성 비용에 상한을 둡니다. Agent Completions에서는 필수이고, Format 실행은 최대 $500입니다.
영상 API 미디어 입출력: 공개 URL 입력, Sume URL 출력
Sume 생성 요청은 미디어를 정해진 필드의 공개 HTTPS URL로 받으며 별도 업로드 단계가 없습니다. 결과는 저장해 둘 Sume 호스팅 media.sume.com URL로 돌아옵니다.
Sume CLI로 터미널에서 아바타 영상 생성하기
Sume CLI를 설치하고 브라우저로 로그인한 뒤 말하는 아바타 영상을 제출하세요. Image, Video, Music 1.0에는 아직 CLI 제출 명령어가 없습니다.
Sume API 키 동작 방식: 스코프, 인증 헤더, 호스트, 교체
Sume API 키는 워크스페이스 단위 시크릿으로, Bearer나 x-api-key 중 하나로만 보냅니다. 스코프는 생성 시 고정되고, 키는 발급된 호스트에서만 동작합니다.
Sume 영상 Job 동시성과 큐: 한도와 queue_full
Sume는 유효한 유료 Job을 queued로 받아 요금제 동시성 한도 안에서 실행합니다. 제출이 429 queue_full로 실패하는 것은 큐까지 가득 찼을 때뿐입니다.
Sume API 오류와 요청 한도: 오류 코드, 429, 재시도 시점
Sume API 오류는 안정적인 코드와 request id를 담은 하나의 봉투로 옵니다. 읽기와 쓰기는 분당 예산이 따로 있고, queue_full은 요청 한도가 아닙니다.
Sume 영상 실행용 서명된 웹훅: 이벤트, 재시도, 검증
Format·Action·Agent Completion 실행이 완료되거나 실패하면 Sume가 HMAC-SHA256 서명 POST를 한 번 보냅니다. 원본 본문을 검증하고 request_id로 중복을 제거하세요.
Claude Code·Cursor·Codex를 호스팅 MCP로 Sume에 연결
mcp.sume.com/mcp의 Sume 호스팅 MCP 서버를 쓰면 코딩 에이전트가 이미지, 영상, 오디오, 아바타를 생성할 수 있습니다. 설정 방법, OAuth 스코프, 지출 게이트를 정리했습니다.