API 레퍼런스
이 문서는 영문 원고를 AI로 번역한 내용이라 표현이 어색할 수 있습니다.
이 페이지는 Sume Developer API의 사람이 읽기 쉬운 라우트 맵입니다. 두 번째 스키마가 아닙니다. 정확한 JSON 요청·응답 형태, enum, 필드 요구 사항은 라이브 OpenAPI 문서를 쓰세요 — 여기 Markdown 표는 뒤처질 수 있습니다.
OpenAPI 스키마
로컬 docs 스냅샷:
라이브 스키마(이 docs 스냅샷의 소스 오브 트루스):
다운로드:
체크인된 스냅샷을 로컬에서 갱신:
인증
헬스 체크를 제외한 모든 /v1 API 엔드포인트에는 Sume API 키가 필요합니다.
x-api-key: $SUME_API_KEY도 받습니다. API 응답은 전체 시크릿 키를 절대 반환하지
않습니다.
계정, 카탈로그, 사용량
| Method | Path | Notes |
|---|---|---|
GET | /v1/health | 버전드 API 헬스입니다. |
GET | /v1/catalog | 사용 가능한 능력, 엔드포인트, 런타임 준비 상태, 모델, 가격 메타데이터입니다. |
GET | /v1/me | 현재 API 키, 소유자, 워크스페이스 컨텍스트입니다. |
GET | /v1/balance | USD 기준 사용 가능 잔액입니다. |
GET | /v1/usage | 예약·확정·환불·충전 같은 사용량 원장 항목입니다. |
Jobs
| Method | Path | Notes |
|---|---|---|
GET | /v1/jobs | 워크스페이스 Job 목록입니다. status/type으로 필터할 수 있습니다. |
GET | /v1/jobs/:id | 공개 Job envelope를 읽습니다. |
GET | /v1/jobs/:id/status | 폴링용 가벼운 상태 읽기입니다. |
GET | /v1/jobs/:id/result | 완료된 결과 페이로드이며, 가능하면 공개 artifact URL을 포함합니다. |
POST | /v1/jobs/:id/cancel | queued 또는 processing Job에 대한 취소를 요청합니다. |
GET | /v1/jobs/:id/events | 디버깅·복구용 공개 타임라인 이벤트입니다. |
종료 Job 상태는 completed, failed, canceled입니다. 비종료 상태는 queued와
processing입니다.
미디어 입력
생성 요청은 라이브 OpenAPI 스키마에 문서화된 필드에 fetch 가능한 공개 HTTPS 미디어
URL을 직접 받습니다(예: Avatar photo input.image_url, Avatar Video
product_image / scene.image_url).
localhost, 사설 네트워크, 비 HTTPS, 이미지가 아닌 응답은 생성 제출 전에 거절됩니다. 1st-party 업로드 헬퍼는 일반 연동의 기본 공개 API 경로가 아닙니다 (공개 OpenAPI에서 숨김을 참고하세요).
정식 생성 경로
새 연동에는 이 제품형 엔드포인트를 선호하세요.
| Method | Path | Family | Notes |
|---|---|---|---|
POST | /v1/avatar-1.0/generate | Avatar 1.0 | 정식 아바타 생성입니다. |
POST | /v1/avatar-1.0/talking-video | Avatar 1.0 | 정식 talking-video 생성입니다. |
GET | /v1/avatar-1.0/avatars | Avatar 1.0 | Avatar 1.0 아바타 목록입니다. |
GET | /v1/avatar-1.0/avatars/:id | Avatar 1.0 | Avatar 1.0 아바타 하나를 읽습니다. |
POST | /v1/image-1.0/generate | Image 1.0 | 정식 이미지 생성입니다. |
POST | /v1/video-1.0/generate | Video 1.0 | 정식 비디오 생성입니다. |
POST | /v1/music-1.0/generate | Music 1.0 | 정식 음악 생성입니다. |
호환 model-run 별칭
이 /v1/models/sume/.../runs 경로는 공개 OpenAPI에 남아 있고 계속 동작합니다.
둘 다 있을 때는 위의 정식 경로를 선호하세요.
| Method | Path | Public model | Notes |
|---|---|---|---|
POST | /v1/models/sume/avatar/v1.0/runs | sume/avatar/v1.0 | 레거시 Avatar 1.0 생성입니다. |
POST | /v1/models/sume/avatar-1.0/generate/runs | sume/avatar-1.0/generate | Avatar 1.0 generate의 별칭입니다. |
POST | /v1/models/sume/avatar-1.0/talking-video/runs | sume/avatar-1.0/talking-video | Avatar 1.0 talking video의 별칭입니다. |
POST | /v1/models/sume/avatar-video/v1.0/runs | sume/avatar-video/v1.0 | 레거시 Avatar Video 1.0 생성입니다. |
POST | /v1/models/sume/avatar-face-swap/v1.0/runs | sume/avatar-face-swap/v1.0 | Avatar Face Swap 1.0 Beta입니다. |
POST | /v1/models/sume/image-1.0/runs | sume/image-1.0 | Image 1.0 generate의 별칭입니다. |
POST | /v1/models/sume/video-1.0/runs | sume/video-1.0 | Video 1.0 generate의 별칭입니다. |
POST | /v1/models/sume/music-1.0/runs | sume/music-1.0 | Music 1.0 generate의 별칭입니다. |
제출 엔드포인트는 OpenAPI 스키마에 문서화된 곳에서 공통 communication 필드
mode, webhook_url, wait_timeout_seconds를 지원합니다.
아바타 생성은 최상위 avatar_handle과 input 유니온을 씁니다:
prompt, props, 또는 photo. Avatar Video는 최상위 avatar_handle과
정확히 하나의 script 또는 video_inputs를 씁니다. Avatar Video는
quality: "standard" | "plus" | "max"를 받으며 기본값은 **plus**입니다.
상세 가이드: Avatar 개요, 미리보기, 페이스 스왑, 캡션, 트렌딩.
아바타 리소스, 미리보기, 카탈로그, 캡션, 트렌딩
| Method | Path | Notes |
|---|---|---|
GET | /v1/avatars | 아바타 리소스 목록(호환 목록 경로)입니다. |
GET | /v1/avatars/:id | 아바타 리소스 하나를 읽습니다. |
GET | /v1/avatar-videos | avatar-video 리소스 목록입니다. |
GET | /v1/avatar-videos/:id | avatar-video 리소스 하나를 읽습니다. |
POST | /v1/avatar-catalog/search | 아바타 카탈로그를 검색합니다. |
POST | /v1/avatar-video-previews | avatar-video 미리보기를 만듭니다. |
GET | /v1/avatar-video-previews/:id | 미리보기를 읽습니다. |
POST | /v1/avatar-video-previews/:id/regenerate | 미리보기를 다시 생성합니다. |
POST | /v1/avatar-video-previews/:id/generate-video | 미리보기에서 비디오를 생성합니다. |
POST | /v1/video-captions | 비디오 캡션 Job을 제출합니다. |
GET | /v1/video-captions/:id | 비디오 캡션 리소스를 읽습니다. |
POST | /v1/trending-videos/search | TikTok 트렌딩 비디오 메타데이터를 검색합니다. |
종료 이벤트 페이로드, 서명 헤더, 재시도 동작은 웹훅을 참고하세요.
Actions
Agents Actions는 자체 run 리소스와 상태 어휘를 가집니다. Job이 아니며
/v1/jobs 아래에 나타나지 않습니다. 두 쓰기만 actions:write가 필요하고, 나머지는
모두 actions:read가 필요합니다.
| Method | Path | Notes |
|---|---|---|
GET | /v1/actions | Action 목록입니다. limit, status, trigger_type 필터입니다. |
GET | /v1/actions/:action_id | Action 하나를 읽습니다. |
GET | /v1/actions/:action_id/runs | Action의 run 목록입니다. |
POST | /v1/actions/:action_id/runs | API 호출 트리거로 run을 시작합니다. actions:write가 필요합니다. |
GET | /v1/actions/:action_id/runs/:run_id | Action 아래에서 별칭된 run 하나를 읽습니다. |
GET | /v1/action-runs/:run_id | run receipt를 읽습니다. |
GET | /v1/action-runs/:run_id/status | 폴링용으로 잘린 상태 페이로드입니다. |
GET | /v1/action-runs/:run_id/result | 종료 receipt입니다. 아직 실행 중이면 409 run_not_completed입니다. |
POST | /v1/action-runs/:run_id/cancel | 멱등한 취소입니다. actions:write가 필요합니다. |
Action을 생성·수정·삭제하는 공개 엔드포인트는 없고,
/v1/action-runs/:run_id/events 엔드포인트도 없습니다 — run receipt의
events_url 필드는 항상 null입니다.
요청 본문, 멱등성 규칙, 전체 오류 표는
고급: API로 스케줄 실행하기를 참고하세요.
Formats
Formats는 Actions와 평행한 자체 run 리소스를 가집니다. 쓰기(run 생성, bulk-run 큐
생성, 취소)만 formats:write가 필요하고, 나머지는 모두 formats:read가 필요합니다.
| Method | Path | Notes |
|---|---|---|
GET | /v1/formats | 키에 보이는 Format 목록: 소유분과 1st-party 카탈로그입니다. limit 필터입니다. |
GET | /v1/formats/:format_id | Format 하나를 읽습니다. SKILL.md 본문은 절대 반환되지 않습니다. |
GET | /v1/formats/:format_id/runs | Format의 run 목록이며, 최신이 먼저입니다. |
POST | /v1/formats/:format_id/runs | API 호출 트리거로 run을 시작합니다. formats:write가 필요합니다. |
POST | /v1/formats/:format_id/bulk-runs | concurrency 창(1–16)으로 run을 최대 100개까지 큐에 넣습니다. formats:write가 필요합니다. 202 큐 receipt입니다. |
GET | /v1/formats/:handle/:slug | handle과 slug로 소유한 Format을 읽습니다. |
GET | /v1/formats/:handle/:slug/runs | handle과 slug로 주소를 잡은 run 목록입니다. |
POST | /v1/formats/:handle/:slug/runs | handle과 slug로 주소를 잡은 run을 시작합니다. formats:write가 필요합니다. |
POST | /v1/formats/:handle/:slug/bulk-runs | 같은 bulk 큐를 handle과 slug로 주소 잡습니다. formats:write가 필요합니다. |
GET | /v1/format-run-queues/:queue_id | bulk 큐 진행(counts + item 상태)입니다. formats:read가 필요합니다. |
GET | /v1/format-runs/:run_id | run receipt를 읽습니다. |
GET | /v1/format-runs/:run_id/status | 폴링용으로 잘린 상태 페이로드입니다. |
GET | /v1/format-runs/:run_id/result | 종료 receipt입니다. 아직 실행 중이면 409 run_not_completed입니다. |
GET | /v1/format-runs/:run_id/events | run 하나의 phase 타임라인이며, 오래된 것이 먼저입니다. |
POST | /v1/format-runs/:run_id/cancel | 멱등한 취소입니다. formats:write가 필요합니다. |
Actions와 마찬가지로 Format을 생성·수정·삭제하는 공개 엔드포인트는 없습니다 —
Agents 대시보드에서 작성하세요. 큐레이션된 Formats by Sume는 유효한 키라면 누구나
sume/{slug}로 바로 호출할 수 있고, run은 그 키에 청구됩니다. 요청 본문과 전체 오류 표는
Format 호출하기, 큐 계약은 대량 실행, 스키마 규칙은
구조화 출력, 준비된 Format은
Format 카탈로그를 참고하세요.
Agent Completions
Agent Completion은 저장 없이 임시 프롬프트로 Agent를 실행합니다. 읽기는
agent_completions:read, 두 쓰기는 agent_completions:write가 필요합니다.
| Method | Path | Notes |
|---|---|---|
POST | /v1/agent/completions | completion을 시작합니다. 비동기만 — choices[]가 아니라 202와 receipt를 반환합니다. |
GET | /v1/agent-runs | completion 목록이며, 최신이 먼저입니다. |
GET | /v1/agent-runs/:run_id | run receipt를 읽습니다. |
GET | /v1/agent-runs/:run_id/status | 폴링용으로 잘린 상태 페이로드입니다. |
GET | /v1/agent-runs/:run_id/result | 종료 receipt입니다. 아직 실행 중이면 409 run_not_completed입니다. |
POST | /v1/agent-runs/:run_id/cancel | 멱등한 취소입니다. |
요청 형태와 OpenAI chat completion과의 차이는 Agent Completions를 참고하세요.
공개 OpenAPI에서 숨김
일부 경로는 API에 구현되어 있지만 공개 OpenAPI 문서에서 의도적으로
생략됩니다(hidePreLaunchCompatibilityOpenApiPaths).
https://api.sume.com/reference/json에 다시 나타날 때까지 문서화된 공개 계약으로
취급하지 마세요.
| Hidden path family | Status |
|---|---|
/v1/assets, /v1/assets/upload-url, /v1/assets/:id, /v1/assets/:id/complete, /v1/assets/:id/download-url | 구현됨; 공개 OpenAPI에서 숨김. 생성 요청에는 공개 HTTPS 미디어 URL을 선호하세요. |
/v1/generation/admission-preview | 구현됨; 공개 OpenAPI에서 숨김. 유료 Job의 admission 동작은 Generation admission에 설명되어 있습니다. |
POST /v1/avatars, POST /v1/avatar-videos | 이 리소스 경로에서의 POST 생성은 숨김; 대신 정식 / model-run 제출 엔드포인트를 쓰세요. |
/health (unversioned) | 숨김; GET /v1/health를 쓰세요. |
/v1/models/{model_owner}/{model_name}/{model_version}/runs | 일반 템플릿 경로는 숨김; 위에 나열된 구체 모델 경로를 쓰세요. |
관련 asset-library 워크플로 메모는 업로드 헬퍼가 OpenAPI에 없어도 URL-first 입력을 설명할 수 있습니다.
결과와 artifact 형태
완료된 Job은 공개 artifact를 포함할 수 있습니다.
공개 결과는 media.sume.com URL을 써야 합니다. 원본 provider URL과 provider task
URL은 공개 결과 계약의 일부가 아닙니다.
오류 envelope
오류는 error 안에 request id가 있는 일관된 envelope를 씁니다.
지원을 위해 request id를 보관하고, 로그에서 API 키, 서명 URL, 비공개 미디어 URL, 사용자 id, 워크스페이스 id, 원본 provider 식별자를 마스킹하세요.