가이드
Sume 가이드: API, 포맷, 에이전트, 모델, 미디어 도구, 요금을 다룹니다. 답마다 날짜와 출처를 붙였습니다.
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 API 크레딧 부족 오류 402: 충전 후 재시도하기
Sume의 402 insufficient_credits는 잔액이 요청의 예상 비용에 못 미쳐 아무것도 실행되지 않았다는 뜻입니다. GET /v1/balance로 확인하고 충전한 뒤 재시도하세요.
Sume 생성 Job과 Format·Action·Agent 실행의 차이
Sume Job은 /v1/jobs에서 추적하는 생성 요청 하나이고, 실행은 Format, 스케줄, Agent Completion이 시작한 에이전트 턴 하나입니다. ID, 웹훅, 대기 방법이 다릅니다.
Sume 웹훅이 도착하지 않나요? 전달·서명 디버깅 방법
Sume 웹훅이 도착하지 않으면 Job이나 실행의 webhook_delivery를 읽고, 테스트 전송으로 엔드포인트를 확인한 뒤, 실제 이벤트를 다시 보내세요.
AI 영상 한 편 생성 비용: Sume API 실행 한 번에 든 비용
Sume 실행이나 영상 Job 하나의 비용은 run_id나 job_id로 GET /v1/usage를 호출해 debited_usd를 읽으면 됩니다. 에이전트 턴을 포함한 지갑 차감액입니다.
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을 폴링하고 영상을 내려받으세요. 짧은 다섯 단계와 그다음 갈 곳을 정리했습니다.
렌더링 전 영상 타임라인 JSON 검증: Sume plan 사전 검사
POST /v1/timeline-1.0/plan은 Timeline 1.0 문서를 과금 없이 검사하고 길이, 과금 대상 분 수, 비용 추정치, 필터그래프 요약을 반환합니다.
영상 편집 API 한도: Sume 미디어 도구 상한을 표 하나로 정리
Sume의 트림, 필터, 오디오 분리, 프레임, 검사, 자막, Timeline API의 소스·출력 길이, 개수, 크기 상한을 각 문서 페이지 링크와 함께 정리했습니다.
Sume 개발자 대시보드: API 키·사용량·Job·결제·플레이그라운드
Sume 개발자 대시보드를 페이지별로 소개합니다. API 키 생성, Billing & subscription에서 크레딧 구매, Jobs·Usage 확인, 플레이그라운드에서 Avatar 시험을 다룹니다.
여러 AI 영상 샷에서 캐릭터 일관성 유지하기: API 입력 3가지
문서화된 Sume API 입력 세 가지로 모든 샷에 같은 캐릭터 소스를 보낼 수 있습니다. 재사용 가능한 Avatar 1.0 아바타, 첫 프레임 스틸 한 장, 또는 이미지 레퍼런스입니다.
영상 에이전트란 무엇인가요? Sume의 정의와 실행 방식
Sume 문서에서 영상 에이전트는 생성 도구를 조합해 바로 게시할 수 있는 영상을 만드는 샌드박스 에이전트입니다. 채팅으로 브리프를 주거나 HTTP로 호출하세요.
Sume Format 구조화 출력: JSON Schema대로 받는 JSON
JSON Schema를 output_schema로 바인딩하면 Sume Format 실행이 그 형태로 output을 돌려줍니다. 미디어 URL은 모두 실행이 만든 미디어와 대조됩니다.
Sume Format 대량 실행: 요청 한 번에 렌더 100개까지
Sume 대량 실행 요청은 일반 Format 실행 1–100개를 서버에서 큐에 넣고 1–16개를 동시에 진행합니다. 큐 URL 하나를 폴링하고, 각 자식은 일반 실행으로 읽으세요.
Sume Format 실행 수명주기: 상태, 웹훅, 폴링
Sume Format 실행은 queued에서 processing을 거쳐 종료 상태로 갑니다. 결과는 서명된 format.run.terminal 웹훅 한 번이나 폴링, 또는 둘 다로 확인합니다.
Sume Format으로 제품에 AI 영상 생성을 임베드하는 방법
AI 영상 생성을 임베드하려면 서버가 Sume API 키 하나를 들고 고객마다 Format을 실행합니다. 유도한 Idempotency-Key와 지출 상한, 웹훅을 함께 씁니다.
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로 중복을 제거하세요.
유료 API를 호출하는 AI 에이전트의 안전한 자동화
에이전트는 기본적으로 읽기 전용으로 두고 비밀 값은 로그에서 빼세요. 호스팅 MCP에서는 idempotency_key를 보내고, dry_run으로 미리 보고, max_spend_usd로 상한을 두세요.
AI 영상 에이전트 스케줄 실행: cron, API 트리거, 영수증
Sume 스케줄은 cron 주기로 실행되고 실행 영수증을 돌려주는, 저장된 에이전트 자동화입니다. 대시보드에서 만들고, 실행 시작과 모니터링은 API로 합니다.
Sume Avatar 1.0 API로 재사용 가능한 AI 아바타 만들기
POST /v1/avatar-1.0/generate에 avatar_handle과 프롬프트·프로필·이미지 중 한 가지 입력을 보내세요. Job을 폴링한 뒤 handle을 아바타 영상에 재사용하세요.
말하는 아바타 영상 API: 스크립트로 아바타 영상 생성하기
POST /v1/avatar-1.0/talking-video는 준비된 아바타와 4-60초 분량의 스크립트를 말하는 영상으로 만듭니다. 옵션, 자막, 폴링, 초당 요금을 다룹니다.
다중 장면 아바타 영상 API: 순서 있는 장면으로 영상 하나 만들기
스크립트 하나 대신 순서 있는 video_inputs를 보내 말하는 장면과 무음 장면을 4-60초 아바타 영상 하나로 합성하세요. 장면 필드, 규칙, 제한을 다룹니다.
아바타 영상 프리뷰: 렌더링 전에 첫 프레임 승인하기
아바타 영상 프리뷰를 만들어 첫 프레임 스틸을 받고, 필요하면 다시 생성한 뒤, 프리뷰 id로 generate-video를 호출해 최종 영상을 렌더링하세요.
Avatar Face Swap API(베타): 영상에 아바타 얼굴 입히기
Avatar Face Swap 1.0은 준비된 아바타의 얼굴을 짧은 공개 소스 영상에 입히는 Sume의 베타 엔드포인트입니다. 필수 필드, 제한, 폴링을 다룹니다.
Sume API로 영상에 자막을 입히는 방법
공개 HTTPS 영상 URL을 POST /v1/video-captions로 보내면 음성 인식이나 직접 넣은 텍스트로 타이밍을 맞춘 자막 영상을 Job 기반으로 받습니다.
Timeline 1.0 API로 롱폼 영상을 조립하는 방법
Timeline 1.0은 오디오 스파인 하나와 순서가 있는 영상 슬롯 1–200개를 MP4 하나로 렌더링합니다. 모든 URL은 Sume에 호스팅되어야 하며, plan 사전 검사는 과금되지 않습니다.
Sume 타임라인 합성·타임라인 오디오 API 사용법
타임라인 합성은 스틸 하나와 영상 하나를 같은 화면에 담아 새 MP4로 만듭니다. 타임라인 오디오는 Sume에 호스팅된 오디오를 이어 붙이거나 나눠 재사용할 파일로 만듭니다.
영상 검사 API: 클립 프로브, 스틸 샘플링, 전사문 받기
POST /v1/video-inspect는 Sume에 호스팅된 클립 하나를 읽어 프로브 정보, 샘플링한 스틸, 선택적 전사문을 반환합니다. 프로브와 스틸은 과금되지 않습니다.
Sume API로 영상에서 프레임을 추출하는 방법
POST /v1/video-frames는 Sume에 호스팅된 클립 하나에서 지정한 시각의 스틸을 소스 크기의 내구성 있는 이미지로 반환합니다. 이 호출은 과금되지 않습니다.
Sume API로 영상 트림, 필터, 오디오 분리하기
영상 트림은 구간을 잘라, 영상 필터는 dim이나 crop을 적용해 새 MP4를 만들고, 오디오 분리는 wav나 mp3를 추출합니다. 모두 Sume에 호스팅된 클립 하나를 받습니다.
음악 생성 API: Sume Music Router와 Lyria 3.5
Sume Music Router는 POST /v1/music-router/generate로 텍스트 프롬프트를 트랙으로 만듭니다. sume/music-auto가 엔진을 고르며, 현재는 Lyria 3.5입니다.
레퍼런스 이미지 기반 이미지 생성 API: POST /v1/images
Sume의 POST /v1/images에 프롬프트와 공개 HTTPS 레퍼런스 이미지를 보내세요. 카탈로그 모델을 고정하거나 sume/auto를 보내면 되고, 모델별 한도는 카탈로그에 나와 있습니다.