---
title: API 레퍼런스
description: 현재 Sume Developer API의 라우트 맵, 인증 메모, 응답 패턴입니다.
---

이 페이지는 Sume Developer API의 **사람이 읽기 쉬운 라우트 맵**입니다. 두 번째
스키마가 아닙니다. 정확한 JSON 요청·응답 형태, enum, 필드 요구 사항은 라이브
OpenAPI 문서를 쓰세요 — 여기 Markdown 표는 뒤처질 수 있습니다.

## OpenAPI 스키마

로컬 docs 스냅샷:

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

라이브 스키마(이 docs 스냅샷의 소스 오브 트루스):

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

다운로드:

```bash
curl https://api.sume.com/reference/json \
  -o sume-openapi.json
```

체크인된 스냅샷을 로컬에서 갱신:

```bash
pnpm openapi:sync
# or: node scripts/sync-openapi.mjs
```

## 인증

헬스 체크를 제외한 모든 `/v1` API 엔드포인트에는 Sume API 키가 필요합니다.

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

`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에서 숨김](#공개-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 개요](/models),
[미리보기](/models/avatar-video-previews), [페이스 스왑](/models/face-swap),
[캡션](/models/video-captions), [트렌딩](/models/trending-videos).

## 아바타 리소스, 미리보기, 카탈로그, 캡션, 트렌딩

| 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 트렌딩 비디오 메타데이터를 검색합니다. |

종료 이벤트 페이로드, 서명 헤더, 재시도 동작은 [웹훅](/workflows/webhooks)을
참고하세요.

## 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로 스케줄 실행하기](/agents/actions/api-trigger)를 참고하세요.

## 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 호출하기](/formats/call), 큐 계약은 [대량 실행](/formats/bulk-runs), 스키마 규칙은
[구조화 출력](/formats/structured-output), 준비된 Format은
[Format 카탈로그](/formats/catalog)를 참고하세요.

## 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](/agents/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](/workflows/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를 포함할 수 있습니다.

```json
{
  "id": "job_...",
  "status": "completed",
  "result": {
    "artifacts": [
      {
        "id": "artifact_...",
        "url": "https://media.sume.com/artifacts/...",
        "media_type": "image",
        "content_type": "image/png"
      }
    ]
  }
}
```

공개 결과는 `media.sume.com` URL을 써야 합니다. 원본 provider URL과 provider task
URL은 공개 결과 계약의 일부가 아닙니다.

## 오류 envelope

오류는 `error` 안에 request id가 있는 일관된 envelope를 씁니다.

```json
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body, parameters, or headers.",
    "request_id": "req_..."
  }
}
```

지원을 위해 request id를 보관하고, 로그에서 API 키, 서명 URL, 비공개 미디어 URL,
사용자 id, 워크스페이스 id, 원본 provider 식별자를 마스킹하세요.