개요
이 문서는 영문 원고를 AI로 번역한 내용이라 표현이 어색할 수 있습니다.
Sume Developer API는 api.sume.com의 공개 서버 API입니다. 워크스페이스 단위로 동작하며 API 키로 인증합니다. 내구성 있는 Job, 공개 미디어 산출물, 사용량 추적, 대시보드 관측에 맞춰져 있습니다.
베이스 URL
이 페이지의 엔드포인트 경로는 모두 /v1을 포함합니다. 라이브 OpenAPI 스키마가 API 서비스 루트에서 제공되기 때문입니다.
제품, API, 미디어 도메인
| Domain / URL | 용도 |
|---|---|
https://www.sume.com | 공개 회사·제품 사이트입니다. |
https://www.sume.com/dashboard | 대시보드 홈입니다. |
https://www.sume.com/dashboard/api-keys | Developer API 키를 만들고 관리합니다. |
https://www.sume.com/dashboard/jobs | Job을 조회합니다. |
https://www.sume.com/dashboard/usage | 사용량과 잔액 요약입니다. |
https://www.sume.com/dashboard/subscription | 결제와 구독(플랜, 크레딧 충전)입니다. |
https://www.sume.com/playground | Avatar playground(사람이 실험하는 공간)입니다. |
https://www.sume.com/agents | Agents 제품 표면입니다. |
https://api.sume.com/v1 | 공개 Developer API입니다. |
https://api.sume.com/reference | Swagger UI입니다. |
https://api.sume.com/reference/json | 라이브 OpenAPI JSON(스키마 소스 오브 트루스)입니다. |
https://media.sume.com | 완료된 Job이 돌려주는 1st-party 미디어·아티팩트 URL입니다. |
인증
API Keys 대시보드에서 API 키를 만들고, 서버 환경에서 보내세요.
API는 x-api-key: sume_live_...도 받습니다.
- 요청 본문에 워크스페이스나 사용자 식별자를 넣지 마세요. 범위는 API 키에서 해석됩니다.
현재 엔드포인트 맵
아래 표는 탐색용 요약입니다. 정확한 요청·응답 스키마는 라이브 OpenAPI(https://api.sume.com/reference/json)를 참고하세요. 메서드·경로 메모는 읽기 쉬운 API 레퍼런스를, 워크플로 설명은 모델 가이드를 우선하세요. 복제된 Markdown 표를 두 번째 스키마로 취급하지 마세요.
새 연동에는 정규 제품 경로( /v1/{family}-1.0/...)를 우선하세요. /v1/models/sume/.../runs 별칭은 호환을 위해 계속 지원됩니다.
| Area | Canonical | Compatibility / aliases | Use for |
|---|---|---|---|
| Health | GET /v1/health | — | 서비스 준비 상태 확인 |
| Catalog | GET /v1/catalog | — | 능력, 모델, 런타임 준비, 가격 메타데이터 탐색 |
| Account | GET /v1/me | — | API 키와 해석된 워크스페이스 컨텍스트 확인 |
| Balance and usage | GET /v1/balance, GET /v1/usage | — | USD 잔액과 사용량 원장 조회 |
| Jobs | GET /v1/jobs, GET /v1/jobs/:id, GET /v1/jobs/:id/status, GET /v1/jobs/:id/result, POST /v1/jobs/:id/cancel, GET /v1/jobs/:id/events | — | Job 목록·조회·폴링·취소·복구·감사 |
| Avatar 1.0 | POST /v1/avatar-1.0/generate, POST /v1/avatar-1.0/talking-video, GET /v1/avatar-1.0/avatars, GET /v1/avatar-1.0/avatars/:id | POST /v1/models/sume/avatar/v1.0/runs, POST /v1/models/sume/avatar-1.0/generate/runs, POST /v1/models/sume/avatar-1.0/talking-video/runs, GET /v1/avatars, GET /v1/avatars/:id | 아바타·토킹 비디오 생성과 조회 |
| Avatar Video 1.0 | GET /v1/avatar-videos, GET /v1/avatar-videos/:id | POST /v1/models/sume/avatar-video/v1.0/runs | 제품/장면 아바타 비디오 실행과 리소스 조회 |
| Avatar Video Previews | POST /v1/avatar-video-previews, GET /v1/avatar-video-previews/:id, POST /v1/avatar-video-previews/:id/regenerate, POST /v1/avatar-video-previews/:id/generate-video | — | 프리뷰 → generate-video 흐름 |
| Avatar catalog | POST /v1/avatar-catalog/search | — | 재사용 카탈로그 아바타 검색 |
| Avatar Face Swap (Beta) | — | POST /v1/models/sume/avatar-face-swap/v1.0/runs | 페이스 스왑 모델 실행 |
| Image 1.0 | POST /v1/image-1.0/generate | POST /v1/models/sume/image-1.0/runs | 이미지 생성 |
| Video 1.0 | POST /v1/video-1.0/generate | POST /v1/models/sume/video-1.0/runs | 비디오 생성 |
| Music 1.0 | POST /v1/music-1.0/generate | POST /v1/models/sume/music-1.0/runs | 음악 생성 |
| Video captions | POST /v1/video-captions, GET /v1/video-captions/:id | — | 캡션 Job과 리소스 조회 |
| Trending videos | POST /v1/trending-videos/search | — | TikTok 트렌딩 비디오 메타데이터 검색 |
| Actions | GET /v1/actions, GET /v1/actions/:id, POST /v1/actions/:id/runs, GET /v1/action-runs/:id, POST /v1/action-runs/:id/cancel | — | Agents 스케줄 호출과 모니터링. Scheduled를 참고하세요. |
| Formats | GET /v1/formats, GET /v1/formats/:id, POST /v1/formats/:id/runs, POST /v1/formats/:id/bulk-runs, GET /v1/formats/:handle/:slug, POST /v1/formats/:handle/:slug/runs, POST /v1/formats/:handle/:slug/bulk-runs, GET /v1/format-run-queues/:id, GET /v1/format-runs/:id, POST /v1/format-runs/:id/cancel | — | 저장된 Agents 작성 레시피 호출(run 하나, 또는 bulk 큐)과 모니터링. Formats와 대량 실행을 참고하세요. |
| Agent Completions | POST /v1/agent/completions, GET /v1/agent-runs, GET /v1/agent-runs/:id, POST /v1/agent-runs/:id/cancel | — | 임시 작업으로 Agent 실행. Agent Completions를 참고하세요. |
전체 메서드·경로 표와 OpenAPI hide-list 메모는 API 레퍼런스에서 살펴보세요.
www.sume.so의 예전 소비자 제품 경로(/credits, /uploads/presign, /brand, /ads/videos, /face-swap, /reference-analysis 등)는 현재 sume.com 개발자 플랫폼 API에 포함되지 않습니다.
내부 보이스 기능, 원본 provider 모델 id, provider task URL은 /v1/catalog와 OpenAPI 스키마에 나타나지 않는 한 공개 API 표면이 아닙니다.
Job-first 워크플로
모델 실행·호환 submit 엔드포인트는 작업을 받아 Job을 만들고, 나중에 폴링하거나 복구할 수 있는 응답을 돌려줍니다.
대부분의 연동은 job_id를 반드시 저장하고 백오프로 폴링해야 합니다. 공개 HTTPS 콜백 엔드포인트가 있고 종료 이벤트를 서버가 받아야 한다면 웹훅을 사용하세요.
유료 생성은 큐 우선 접수입니다. 워크스페이스 동시성 한도는 실제로 processing 중인 Job에 적용되며, 큐 용량이 남아 있으면 유효한 제출은 queued로 계속 접수될 수 있습니다. 티어 한도, generation_limits, 큐 가득 참 동작은 생성 접수에서 살펴보세요.
OpenAPI
로컬 docs 프리뷰는 스냅샷을 다음 경로에서 제공합니다.
프로덕션의 라이브 스키마:
Swagger UI:
정확한 요청·응답의 소스 오브 트루스는 라이브 스키마입니다. docs 저장소 스냅샷은 이 엔드포인트에서 갱신됩니다(README / pnpm openapi:sync 참고).