가이드
Sume 가이드: API, 포맷, 에이전트, 모델, 미디어 도구, 요금을 다룹니다. 답마다 날짜와 출처를 붙였습니다.
on_active_run으로 Sume AI 에이전트 중복 실행 막기
Sume의 on_active_run 필드는 실행 중에 들어온 두 번째 실행 요청의 처리를 정합니다. 그대로 실행하거나, 건너뛴 실행을 기록하거나, 409를 받고 아무것도 실행하지 않습니다.
Sume MCP 서버 OAuth 플로: 디스커버리·동의·PKCE·스코프
Sume 호스팅 MCP 서버는 자체 OAuth를 운영합니다. 401이 디스커버리 메타데이터를 가리키고, 사용자가 mcp.sume.com에서 동의하면 PKCE S256으로 한 시간짜리 토큰을 받습니다.
MCP 도구 호출 타임아웃: 긴 영상 Job은 jobs_wait로
Sume 호스팅 MCP 서버에서 jobs_wait 호출 한 번은 최대 55초까지 대기합니다. 긴 영상 Job은 나눠서 기다리고, id는 최대 20개까지 묶되 다시 제출하지 마세요.
Sume MCP 도구 목록: 읽기·쓰기·유료로 나눈 호스팅 도구
Sume MCP 도구를 계열별로 정리했습니다. 읽기만 하는 호스팅 도구, 쓰는 도구, 유료 Job을 시작하는 도구, 호스팅 MCP에 아예 없는 도구 이름을 구분합니다.
Sume MCP insufficient_scope·누락 도구·타임아웃 해결
Sume MCP의 insufficient_scope 오류는 OAuth 세션에 mcp:write가 없다는 뜻입니다. mcp_health부터 호출한 뒤 스코프, 누락된 도구, 타임아웃을 해결하세요.
MCP 프로그래밍 방식 도구 호출: Sume script_run 동작 방식
script_run은 Sume 호스팅 MCP의 프로그래밍 방식 도구 호출입니다. 짧은 JavaScript 프로그램이 호출 예산과 유료 예산 안에서 도구를 반복하거나 병렬로 호출합니다.
영상 편집 MCP 서버: AI 에이전트로 트림·필터·조립하기
Sume 호스팅 MCP 서버는 AI 에이전트에 영상 편집 도구를 제공합니다. 검사, 프레임, 트림, 필터, 오디오 분리, 합성, Timeline 렌더가 각각 Job으로 실행됩니다.
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 중 해당하는 원인을 고치세요.
AI 영상 생성 API 길이 제한: 클립당 최대 30초
Sume에서 30초 클립을 만드는 모델은 seedance-2.5(4–30초)와 wan-3.0(2–30초)이고, 다른 모델은 15초 이하입니다. 모델별 한도, 오류, 더 길게 만드는 법을 정리했습니다.
4K AI 영상 생성 API: 모델별 해상도, 360p부터 4K까지
Sume에서 4K는 gemini-omni-flash-1.1을 지정해 resolution 4K로 요청하세요. minimax-h3는 2K나 4K로 업스케일합니다. 영상 모델별 해상도와 가격 영향을 다룹니다.
Gemini Omni Flash 1.1 API: 텍스트·이미지·레퍼런스 영상
Sume에서 Gemini Omni Flash 1.1을 gemini-omni-flash-1.1로 호출하세요. 텍스트·이미지·레퍼런스로 360p부터 4K까지 3–10초 클립을 네이티브 오디오와 함께 만듭니다.
MiniMax H3·H3 Max 영상 API: 네이티브 768p·스테레오 오디오
Sume의 MiniMax H3·H3 Max(minimax-h3, minimax-h3-max)는 네이티브 480p·768p(H3 Max는 1080p도)로 5–15초 클립을 만들며, 스테레오 오디오가 항상 들어갑니다.
립싱크 API: 이미지와 오디오로 말하는 클립 만들기
스틸 이미지와 Sume에 호스팅된 오디오를 VEED Fabric 1.0이나 MiniMax H3 Max Lip Sync로 보내 말하는 클립을 받으세요. 입력, 제한, 초당 요금을 다룹니다.
Sume의 이미지 생성 API 모델: 편집·레퍼런스·마스크
Sume의 이미지 생성 API에는 모델이 17개 있습니다. 레퍼런스 이미지로 편집하는 모델, 모델별 레퍼런스 수, 텍스트 전용 모델, 마스크를 받는 모델을 확인하세요.
Wan 3.0 API: 2–30초 AI 영상, 오디오·프레임·레퍼런스
Sume에서 Wan 3.0을 wan-3.0으로 호출하세요. 프롬프트, 첫 프레임과 마지막 프레임, 또는 이미지·영상·오디오 레퍼런스로 480p, 720p, 1080p의 2–30초 클립을 만듭니다.
모션 컨트롤 API: 드라이빙 영상으로 이미지 움직이기
Sume의 Kling 3.0 Motion Control은 최대 30초 길이의 드라이빙 영상에서 움직임을 가져와 스틸 이미지를 움직입니다. 요청 필드, 제한, 가격을 다룹니다.
API로 영상에 배경 음악 넣기: 루프, 페이드, 더킹
Sume Timeline 1.0 렌더에 사운드트랙을 더하면 Sume에 호스팅된 음악을 음성 스파인 아래에 믹싱할 수 있습니다. 레벨, 루프, 페이드아웃, 말소리 아래 더킹을 설정하세요.
Sume API로 가로 영상을 세로 9:16으로 변환하기
영상 필터로 Sume에 호스팅된 16:9 클립에서 9:16 영역을 잘라 내거나, 클립을 1080×1920 Timeline 렌더에 넣고 cover, contain, blur 중 하나로 맞춥니다.
Sume API로 긴 영상을 짧은 클립으로 나누기
영상 검사로 Sume에 호스팅된 영상을 전사해 자를 지점을 찾고, 영상 트림으로 구간마다 잘라 낸 뒤 짧은 클립마다 크롭과 자막을 적용합니다.
Sume API로 영상의 오디오를 교체하거나 제거하기
영상 트림의 audio: drop으로 클립의 오디오를 제거하거나, Timeline 1.0에서 Sume에 호스팅된 새 스파인 위에 클립을 렌더링해 교체하거나, gain_db로 레벨을 다시 맞추세요.
영상 전환 효과(트랜지션) API: 크로스페이드·와이프·슬라이드
Sume Timeline 1.0 렌더의 클립 사이에 페이드, 와이프, 슬라이드, 디졸브 트랜지션을 넣을 수 있습니다. 각각 최대 1초이고 정수 프레임으로 스냅되며, 연속으로는 최대 8개입니다.
이미지 슬라이드쇼 영상 API: 이미지와 음악으로 MP4 만들기
Timeline 1.0으로 Sume에 호스팅된 이미지를 슬라이드쇼 MP4로 만드세요. 스틸은 영상 슬롯으로, 길이는 무음 스파인으로, 음악은 루프되는 사운드트랙으로 지정합니다.
한국어 자막 API: 두부 글자 없는 한글 자막 스타일과 폰트
Sume 자막 API로 한국어 자막을 입히려면 한글을 지원하는 스타일과 폰트를 고르세요. 한국어 문구가 두부 글자가 아닌 한글 서체로 렌더링됩니다.
자막 자동 생성 API: 전사하고 문구를 고친 뒤 입히기
Sume로 자막을 자동 생성하세요. 영상 검사로 클립을 전사하고 문구를 고친 뒤, script_text 정렬로 영상에 자막을 입힙니다.
자막 커스터마이즈 API: 색, 위치, 크기, 줄당 단어 수
Sume의 design 객체로 영상에 입히는 자막을 커스터마이즈하세요. punch와 tiktok-green을 뺀 모든 스타일에서 색, 위치, 크기, 구절당 단어 수를 덮어씁니다.
Sume API로 영상의 프레임 레이트나 해상도 바꾸기
영상 트림의 output 필드나 영상 필터의 scale, fps 필터로 Sume에 호스팅된 클립의 크기와 fps를 맞추고, Timeline이 출력 프레임 레이트를 고르는 방식을 알아봅니다.
AI 아바타 영상 API 요금: 초당·분당 비용
Sume는 AI 아바타 영상을 품질 등급별 초당 요율로 청구하며, 제품 이미지를 보내면 요율이 따로 적용됩니다. standard, plus, max의 분당 비용을 정리했습니다.
영상 생성 API 동기 vs 비동기: Sume의 네 가지 제출 모드
Sume의 제출 모드는 async, sync, subscribe, webhook입니다. sync와 subscribe는 최대 30초만 기다리므로, 영상은 async로 제출해 폴링하거나 웹훅을 받으세요.
Sume TypeScript SDK 빠른 시작: 설치·클라이언트·오류·재시도
@sume-com/sdk를 설치하고 createSumeClient로 클라이언트 하나를 만든 뒤, throw 대신 오류를 반환하는 타입 지정 오퍼레이션을 호출하세요. 재시도는 기본으로 들어 있습니다.
실패한 AI 영상 생성도 크레딧이 차감되나요? 예약·확정·환불
아닙니다. Sume는 제출 시 Job의 예상 USD 비용을 예약(선차감)하고, 완료될 때만 사용량을 확정하며, Job이 실패하거나 취소되면 예약을 해제하거나 환불합니다.
AI 영상 생성 Job은 왜 실패했나요? Job 오류 읽는 법
실패한 Sume Job에는 category, stage, retryable, public_reason, next_action이 담긴 공개 오류가 있습니다. 읽는 곳과 필드별로 할 일을 설명합니다.
TypeScript SDK에서 Sume Job·실행이 끝날 때까지 기다리기
waitForJob, waitForRun, subscribeFormatRun은 Sume Job이나 실행이 끝날 때까지 폴링합니다. 기본 타임아웃, throw하는 오류, 재시도를 정리했습니다.
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을 절대 취소하지 않습니다. 모든 한도와 직접 정할 마감 시간을 정리했습니다.
Sume request_id·job_id·run_id: 저장하고 문의할 ID
Job이나 실행 ID를 저장하고, 웹훅은 job_id나 실행 봉투의 request_id로 중복을 제거하고, Sume 지원팀에는 req_ 요청 ID를 Job이나 실행 ID와 함께 알려 주세요.
영상 편집 API 한도: Sume 미디어 도구 상한을 표 하나로 정리
Sume의 트림, 필터, 오디오 분리, 프레임, 검사, 자막, Timeline API의 소스·출력 길이, 개수, 크기 상한을 각 문서 페이지 링크와 함께 정리했습니다.
Sume 개발자 대시보드: API 키·사용량·Job·결제·플레이그라운드
Sume 개발자 대시보드를 페이지별로 소개합니다. API 키 생성, Billing & subscription에서 크레딧 구매, Jobs·Usage 확인, 플레이그라운드에서 Avatar 시험을 다룹니다.
영상 에이전트란 무엇인가요? 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와 지출 상한, 웹훅을 함께 씁니다.