Sume API 엔드포인트 목록: 경로, 스코프, 멱등성
Sume API의 공개 경로를 계열별로 정리한 색인입니다. 키가 필요 없는 경로, 계열별 스코프, Idempotency-Key 적용 위치, 계열별 설명 글을 담았습니다.
Sume API의 공개 경로는 https://api.sume.com/v1 아래에 있습니다. 헬스, 카탈로그, 배경 음악 경로는 키가 필요 없고, 나머지 경로는 모두 API 키가 필요합니다. 문서가 키 스코프를 명시하는 곳은 Formats, Actions, Agent Completions, 웹훅 시크릿과 테스트 전달 경로, Job 웹훅 재전송입니다. 아래 색인은 경로를 계열별로 묶고, 계열마다 필요한 스코프, Idempotency-Key가 적용되는 곳, 그 계열을 설명하는 글을 함께 보여 줍니다.
경로는 2026-09-27에 확인한 Sume API 레퍼런스의 경로 맵, Developer API 개요 (영문), 라이브 OpenAPI 레퍼런스에서 가져왔습니다. 스펙을 내려받고 클라이언트를 생성하는 방법은 Sume OpenAPI 스펙에서, 표면별 모델 ID 전체는 Sume의 모든 AI 모델에서 다룹니다.
Sume API에는 어떤 경로가 있나요?
대시(—)는 문서가 그 계열에 멱등성 규칙을 두지 않았다는 뜻입니다. 필드의 기준은 라이브 OpenAPI이므로, 정확한 스키마가 필요하면 내려받으세요.
| 계열 | 경로 | 키와 스코프 | Idempotency-Key |
|---|---|---|---|
| 헬스와 카탈로그 | GET /v1/health, GET /v1/catalog | 키 필요 없음 | — |
| 배경 음악 | GET /v1/bgm/catalog, GET /v1/bgm/categories, POST /v1/bgm/pick | 키 필요 없음 | — |
| 계정과 사용량 | GET /v1/me, GET /v1/balance, GET /v1/usage | 키 | — |
| 웹훅 시크릿 | GET /v1/webhooks/signing-secret, POST /v1/webhooks/signing-secret/rotate, POST /v1/webhooks/test-deliveries | account:read, 두 POST는 account:write 필요 | — |
| Job | GET /v1/jobs, GET /v1/jobs/{id}와 /status, /result, /events, POST /v1/jobs/{id}/cancel | 키 | —(취소 자체는 이미 취소된 Job에 대해 멱등) |
| Job 웹훅 재전송 | POST /v1/jobs/{id}/webhook/redeliver | jobs:write | — |
| 이미지 | POST /v1/images, GET /v1/images/models, GET /v1/images/models/{model_id}/endpoints | 키 | 생성 요청에 전송 |
| 영상 | POST /v1/videos, GET /v1/videos/{id}, GET /v1/videos/{id}/content, GET /v1/videos/models | 키 | 생성 요청에 전송, 재전송하면 원래 Job 반환 |
| Music Router | POST /v1/music-router/generate, GET /v1/music-router/models | 키 | 생성 요청에 전송 |
| 텍스트 음성 변환과 음성 인식 | POST /v1/tts-1.0/generate, POST /v1/tts-router/generate, GET /v1/tts-router/models, POST /v1/stt-1.0/transcribe | 키 | 각 생성 요청에 전송 |
| 배경 제거와 업스케일 | POST /v1/rmbg-1.0/remove, POST /v1/image-upscale-1.0/upscale, POST /v1/video-upscale-1.0/upscale | 키 | 각 생성 요청에 전송 |
| 립싱크와 모션 컨트롤 | POST /v1/veed/fabric-1.0, POST /v1/minimax/h3-max/lip-sync, POST /v1/kling/3.0/motion-control | 키 | 각 생성 요청에 전송 |
| 아바타와 스톡 아바타 | POST /v1/avatar-1.0/generate, GET /v1/avatar-1.0/avatars와 /{id}, POST /v1/avatar-catalog/search | 키 | 생성 요청에 전송 |
| 말하는 영상과 프리뷰 | POST /v1/avatar-1.0/talking-video, GET /v1/avatar-videos와 /{id}, /v1/avatar-video-previews(생성, 읽기, regenerate, generate-video) | 키 | 각 생성 요청에 전송 |
| 페이스 스왑(베타) | POST /v1/models/sume/avatar-face-swap/v1.0/runs | 키 | 생성 요청에 전송 |
| 자막 | POST /v1/video-captions, GET /v1/video-captions/{id} | 키 | 생성 요청에 전송 |
| 트림, 오디오 분리, 필터 | POST /v1/video-trim, POST /v1/audio-detach, POST /v1/video-filter, POST /v1/video-filter/check | 키 | 필수, 검사(check)에는 불필요 |
| 프레임과 검사 | POST /v1/video-frames, GET /v1/video-frames/{id}, POST /v1/video-inspect, GET /v1/video-inspect/{id} | 키 | 검사에는 필수, 프레임에도 전송 |
| Timeline | POST /v1/timeline-1.0/render, /plan, /audio, /compose | 키 | 필수, /plan에는 불필요 |
| 트렌딩 검색 | POST /v1/trending-videos/search | 키 | — |
| Formats | /v1/formats(목록, 생성), /v1/formats/{handle}/{slug}와 그 아래 /runs, /bulk-runs, /v1/format-runs/{run_id}(읽기, 취소, 재전송), /v1/format-run-queues/{queue_id} | formats:read, 생성·취소·재전송은 formats:write 필요 | 모든 실행 생성과 대량 실행 큐에 |
| Format 공유와 파일 | /v1/formats/{handle}/{slug}/grants, /v1/format-grants, /v1/formats/{handle}/{slug}/contents | formats:read, 쓰기는 formats:write 필요 | — |
| Actions(스케줄 실행) | /v1/actions와 /v1/actions/{action_id}(읽기), /v1/actions/{action_id}/runs(목록, 생성), /v1/action-runs/{run_id}(읽기, 취소) | actions:read, 실행 생성과 취소는 actions:write 필요 | 모든 실행 요청에, 1–255자 |
| Agent Completions | POST /v1/agent/completions, GET /v1/agent-runs, /v1/agent-runs/{run_id}(읽기, 취소) | agent_completions:read, 두 쓰기 요청은 agent_completions:write 필요 | 재전송하면 원래 영수증 반환 |
curl https://api.sume.com/reference/json \
-o sume-openapi.json키에는 어떤 스코프가 필요한가요?
표에서 ‘키’로 표시된 계열은 유효한 API 키가 필요하며, 문서는 이 계열들의 스코프를 명시하지 않습니다. 스코프가 있는 계열은 다음 규칙을 따릅니다.
- 스코프는 키를 만들 때 고정되며 나중에 추가할 수 없습니다. Actions나 Formats 스코프가 생기기 전에 만든 키는 해당 경로에서
403 insufficient_scope를 받습니다(Format에서는 절대404가 아닙니다). 새 키를 만들어 교체하세요. - 웹훅 시크릿 경로는
account:read로 읽고, 교체와 테스트 전달에는account:write가 필요합니다. 실제 Job 웹훅을 재전송하려면jobs:write가 필요합니다. - OAuth로 연결한 호스팅 MCP는 자체 스코프를 씁니다. 읽기 전용 도구에는
mcp:read, 변경을 일으키는 도구와 유료 도구에는mcp:write가 필요합니다.
레거시이거나 은퇴 예정인 경로는 무엇인가요?
아래 경로는 아직 응답하지만, 새 작업에 쓸 경로는 아닙니다. 전환 방법은 Video 1.0·Image 1.0에서 옮기기에서 다룹니다.
- Image 1.0(
POST /v1/image-1.0/generate)과 Video 1.0(POST /v1/video-1.0/generate)은 곧 은퇴합니다.POST /v1/images와POST /v1/videos를 쓰세요. - Music 1.0(
POST /v1/music-1.0/generate)은 단계적으로 은퇴하는 중이며, Music Router를 거쳐 처리됩니다. - Image Router 경로는
/v1/images로 대체되어 지원 중단되었고, 레거시 Video Router 경로는 새 연동을/v1/videos로 안내합니다. 둘 다 아직 동작합니다. /v1/models/…/runs아래의 model-run 별칭은 공개 OpenAPI에 남아 있고 계속 동작합니다. 둘 다 있으면 정식 경로를 우선하세요.POST /v1/avatar-1.0/image-to-video는POST /v1/veed/fabric-1.0의 지원 중단된 별칭입니다.
이 목록에서 빠진 것은 무엇인가요?
일부 경로는 구현되어 있지만 공개 OpenAPI에서 의도적으로 빠져 있습니다. /v1/assets 계열, /v1/generation/admission-preview, /v1/avatars와 /v1/avatar-videos의 POST 생성이 여기에 해당합니다. 문서는 이 경로들이 라이브 OpenAPI에 나타나기 전까지 공개 계약으로 취급하지 말라고 안내합니다.
OpenAPI 문서에는 이 색인이 건너뛴 경로도 있으며, 실험적인 경로와 개발 환경에 먼저 나오는 경로가 여기에 포함됩니다. 해당 문서 페이지에 이런 경로가 표시되어 있으니, 경로를 기반으로 개발하기 전에 그 경로의 문서 페이지를 읽으세요.
출처
관련 글
개발자 카테고리의 다른 글
- Sume API 오류 코드 총정리: 표면별 색인과 다음 조치
Sume API 오류 코드를 표면별로 정리했습니다. 공통 코드, 유료 생성, Format, Scheduled 실행, Agent Completions, 미디어 도구, 호스팅 MCP를 다룹니다.
- Sume API 용어집: Format 실행, 지출 상한, 멱등성 키
Sume API 용어를 한두 문장씩 설명합니다. Format, 실행, Job, 지출 상한, 멱등성 키, 지갑, 에이전트 수수료, 웹훅, 아티팩트 등을 관련 글 링크와 함께 정리했습니다.
- 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