---
title: 개요
description: 카탈로그, Job, 사용량, 미디어 입력, 생성 워크플로를 위한 현재 Sume Developer API 표면을 살펴보세요.
---

Sume Developer API는 `api.sume.com`의 공개 서버 API입니다. 워크스페이스 단위로 동작하며 API 키로 인증합니다. 내구성 있는 Job, 공개 미디어 산출물, 사용량 추적, 대시보드 관측에 맞춰져 있습니다.

## 베이스 URL

```text
https://api.sume.com/v1
```

이 페이지의 엔드포인트 경로는 모두 `/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 대시보드](https://www.sume.com/dashboard/api-keys)에서 API 키를 만들고, 서버 환경에서 보내세요.

```bash
export SUME_API_KEY="sume_live_..."

curl https://api.sume.com/v1/me \
  -H "Authorization: Bearer $SUME_API_KEY"
```

API는 `x-api-key: sume_live_...`도 받습니다.

* 요청 본문에 워크스페이스나 사용자 식별자를 넣지 마세요. 범위는 API 키에서 해석됩니다.

## 현재 엔드포인트 맵

아래 표는 탐색용 요약입니다. **정확한 요청·응답 스키마**는 라이브 OpenAPI(`https://api.sume.com/reference/json`)를 참고하세요. 메서드·경로 메모는 읽기 쉬운 [API 레퍼런스](/api/reference)를, 워크플로 설명은 모델 가이드를 우선하세요. 복제된 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](/agents/actions)를 참고하세요. |
| 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](/formats)와 [대량 실행](/formats/bulk-runs)을 참고하세요. |
| Agent Completions | `POST /v1/agent/completions`, `GET /v1/agent-runs`, `GET /v1/agent-runs/:id`, `POST /v1/agent-runs/:id/cancel` | — | 임시 작업으로 Agent 실행. [Agent Completions](/agents/completions)를 참고하세요. |

전체 메서드·경로 표와 OpenAPI hide-list 메모는 [API 레퍼런스](/api/reference)에서 살펴보세요.

`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을 만들고, 나중에 폴링하거나 복구할 수 있는 응답을 돌려줍니다.

```text
submit generation (canonical or /models/.../runs)
  -> receive job id
  -> poll /v1/jobs/:id/status
  -> fetch /v1/jobs/:id/result when completed
  -> use media.sume.com artifact URLs
```

대부분의 연동은 `job_id`를 반드시 저장하고 백오프로 폴링해야 합니다. 공개 HTTPS 콜백 엔드포인트가 있고 종료 이벤트를 서버가 받아야 한다면 웹훅을 사용하세요.

유료 생성은 큐 우선 접수입니다. 워크스페이스 동시성 한도는 실제로 `processing` 중인 Job에 적용되며, 큐 용량이 남아 있으면 유효한 제출은 `queued`로 계속 접수될 수 있습니다. 티어 한도, `generation_limits`, 큐 가득 참 동작은 [생성 접수](/workflows/generation-admission)에서 살펴보세요.

## OpenAPI

로컬 docs 프리뷰는 스냅샷을 다음 경로에서 제공합니다.

```text
/api/openapi.json
```

프로덕션의 라이브 스키마:

```text
https://api.sume.com/reference/json
```

Swagger UI:

```text
https://api.sume.com/reference
```

정확한 요청·응답의 소스 오브 트루스는 라이브 스키마입니다. docs 저장소 스냅샷은 이 엔드포인트에서 갱신됩니다(README / `pnpm openapi:sync` 참고).