Sume API 용어집: Format 실행, 지출 상한, 멱등성 키
Sume API 용어를 한두 문장씩 설명합니다. Format, 실행, Job, 지출 상한, 멱등성 키, 지갑, 에이전트 수수료, 웹훅, 아티팩트 등을 관련 글 링크와 함께 정리했습니다.
Sume API에서 Format 실행은 저장된 레시피를 한 번 실행하는 것으로, 새 샌드박스 하나, 에이전트 턴 한 번, 영수증 하나로 이뤄집니다. 지출 상한은 실행 한 번이 생성에 쓸 수 있는 최대 금액이고, 멱등성 키는 재시도한 생성 요청을 두 번째 유료 실행이 아니라 원래 실행의 재전송으로 바꿔 주는 헤더입니다.
용어마다 2026-09-27에 확인한 Sume 문서를 바탕으로 한두 문장씩 설명하고, 그 용어를 다루는 글의 링크를 붙였습니다. 제품 맵은 Sume 기초에서 시작하세요.
Format, 실행, Job은 무엇인가요?
실행은 에이전트를 구동하고, Job은 모델 호출 한 번입니다.
| 용어 | 뜻 | 더 읽기 |
|---|---|---|
| Format | 저장된 제작 레시피. SKILL.md 본문과 참고 파일로 이뤄지며, handle과 slug로 호출함 | Sume Format이란? |
| Format run(Format 실행) | 새 샌드박스 하나, 에이전트 턴 한 번, 영수증 하나(arun_…). 끝내지 못한 실행은 failed로 돌아옴 | Format 실행 수명주기 |
| Formats by Sume(Sume 제공 Format) | 예약된 sume handle에 있는 기성 Format. 실행과 그 지출은 호출한 키에 귀속됨 | Sume Format 카탈로그 |
| Bulk run(대량 실행) | 요청 한 번으로 큐에 넣는 Format 실행 최대 100개. 동시에 띄우는 수(concurrency)는 1–16 | Format 대량 실행 |
| Agent Completion | 호출할 때마다 보내는 임시 작업을 에이전트가 수행하는 것. 아무것도 저장하지 않으며 generation_spend_cap_usd가 필수 | Agent Completions |
| Scheduled(스케줄) | 정해진 주기로 실행되는 저장된 에이전트 자동화. API 네임스페이스는 /v1/actions | 에이전트 스케줄 실행 |
| Generation job(생성 Job) | 모델 호출 한 번. /v1/jobs/{id}에서 다시 읽으며, 실행은 별도의 리소스 | Sume Job과 실행의 차이 |
지출 상한, 지갑, 에이전트 수수료는 무슨 뜻인가요?
호출 한 번에 들 수 있는 비용과, 호출이 거절되는 경우를 다룹니다.
| 용어 | 뜻 | 더 읽기 |
|---|---|---|
| Spend cap(지출 상한) | generation_spend_cap_usd. 실행 한 번의 생성 지출 한도로, 플랫폼 최대치 $500까지. 상한을 정한 적 없는 Format은 $400으로 보고됨 | AI 에이전트 지출 상한 |
| Wallet(지갑) | 잔액 하나. 영상 생성, Sume Agent, Format, API가 모두 여기서 차감됨 | Sume 요금 체계 |
| Agent fee(에이전트 수수료) | 모델 금액 위에 더해 청구됨. 사용량은 기본적으로 모델별 공개 요율에 5.5% 에이전트 수수료를 더해 청구됨 | Sume 에이전트 수수료 |
| Reserve, capture, refund(예약·확정·환불) | 유료 생성은 제출 시 추정 금액을 예약하고, 성공하면 확정하며, 확정 전에 실패하거나 취소되면 환불함 | 실패한 Job도 비용이 드나요? |
debited_usd_micros(차감액) | 실행 한 번에 대해 지갑에서 실제로 차감된 금액. 단위는 USD micros(1,000,000이 $1.00) | 실행 한 번의 비용 |
| Concurrency(동시성) | 동시에 processing 상태일 수 있는 유료 생성 Job 수로, 요금제가 정함. 넘친 Job은 queued로 대기하고, 큐가 가득 차면 429 queue_full | 동시성과 큐 |
| Rate limit(요청 한도) | 키별 분당 요청 예산. 읽기와 쓰기 버킷이 따로 있으며, 넘으면 429 rate_limited | 오류와 요청 한도 |
멱등성 키는 무엇이고, 어떤 요청 용어를 알아야 하나요?
요청을 어떻게 재시도하고, 결과를 어떻게 전달받고, 어떻게 추적하는지 다룹니다.
| 용어 | 뜻 | 더 읽기 |
|---|---|---|
| Idempotency key(멱등성 키) | Idempotency-Key 헤더. 같은 키와 같은 본문이면 원래 실행이 돌아오고, 본문이 다르면 409 idempotency_conflict | 멱등성 키 |
| Receipt(영수증) | 생성 요청이 돌려주는 실행 객체. status와 함께, 따라갈 status_url, result_url, events_url, cancel_url이 담김 | Sume API 상태 값 |
| Webhook(웹훅) | 실행이 완료되거나 실패하면 보내는 서명된 POST 한 번. Format은 format.run.terminal을 보내고, Job은 job.completed, job.failed, job.canceled 중 하나를 보냄 | 서명된 웹훅 |
mode(통신 모드) | Job 제출이 결과를 알려 주는 방식. async, sync 또는 subscribe(최대 30초 대기), webhook 중 하나. 생략하면 async지만, POST /v1/images에서는 기본값이 sync | 동기 vs 비동기 |
request_id(요청 ID) | 나타나는 위치에 따라 값이 다름. 오류 본문에서는 지원팀에 알려 줄 req_… ID이며, 모든 응답에 실리는 x-sume-request-id 헤더로도 전달됨 | request_id·job_id·run_id 비교 |
출력과 접근 권한을 설명하는 용어는 무엇인가요?
무엇을 돌려받는지, 그리고 누가 그것을 요청할 수 있는지 다룹니다.
| 용어 | 뜻 | 더 읽기 |
|---|---|---|
| Artifact(아티팩트) | 실행이 생성한 내구성 있는 파일. 만료되지 않고 URL을 가진 누구에게나 공개되는 media.sume.com URL로 제공됨 | 영상 URL은 만료되나요? |
primary_output_url(대표 결과 URL) | 실행에서 보여 줄 단 하나의 결과. 실행이 completed가 아니면 null | 제품에 AI 영상 임베드하기 |
output_schema(출력 스키마) | 실행의 output 형태를 정하는 JSON Schema로, strict 부분집합 안이어야 함. 부분집합을 벗어난 스키마는 400 output_schema_invalid | 출력 스키마 템플릿 |
sume/auto(자동 모델 선택) | Sume가 영상 모델 계열을 고르게 하는 model 값. 어떤 계열이 실행됐는지는 응답에 절대 나오지 않음 | OpenRouter 호환 영상 API |
| API key and scopes(API 키와 스코프) | 워크스페이스 범위의 키로, 서버에서 보냄. formats:read, formats:write 같은 스코프는 키를 만들 때 고정됨 | Sume API 키 동작 방식 |
| Workspace(워크스페이스) | 키와 지출이 해석되는 단위. 팀 Format에는 그 팀 워크스페이스에서 만든 키가 필요 | 다른 워크스페이스와 Format 공유하기 |
출처
관련 글
개발자 카테고리의 다른 글
- Sume API 헤더: 인증, 멱등성 키, If-Match, 요청 한도
Sume API가 읽거나 보내는 모든 HTTP 헤더를 정리했습니다. API 키, Content-Type, Idempotency-Key, If-Match, 요청 ID, 요청 한도, 웹훅 서명을 다룹니다.
- Sume API 출력 파일 형식: MP4·PNG·WebP·WAV·MP3
Sume API 엔드포인트별로 반환하는 파일입니다. Timeline과 편집 도구는 MP4, 이미지는 PNG·JPEG·WebP, 오디오는 WAV나 MP3, 전사문은 JSON입니다.
- Sume API 페이지네이션: cursor·starting_after·한도
Sume 목록 엔드포인트별 페이지 넘김 방식입니다. Format과 실행 목록은 cursor와 has_more, /v1/jobs는 starting_after를 쓰고, limit만 받는 목록에는 커서가 없습니다.
- Sume API 상태 값 정리: Job, 실행, 큐, 웹훅
Sume API 상태 값을 한곳에 모았습니다. Job, /v1/videos, Format·Agent 실행, 대량 실행 큐, 웹훅 전달, 사용량 행, 공유 권한, 잔액까지 다룹니다.
작성자 Sume