개요

Sume Public API는 워크스페이스 범위의 Sume 앱 기능을 얇게 노출하는 프로그래밍 인터페이스입니다. 서버 연동, CLI 자동화, MCP 래퍼, 에이전트 도구를 위해 설계되었습니다.

엔드포인트 그룹

그룹	엔드포인트	용도
Account	`GET /me`, `GET /credits`	인증, 워크스페이스 범위, 플랜, 크레딧, 활성 생성 용량을 확인합니다.
Brand	`GET /brand`, `GET /brand/current`	워크스페이스에서 사용할 수 있는 정리된 Brand DNA 프로필을 읽습니다.
Avatars	`GET /avatars`, `GET /avatars/{avatarId}`	광고와 Face Swap 워크플로에 사용할 아바타를 선택합니다.
Jobs	`GET /jobs`, `GET /jobs/{jobId}`, `GET /jobs/{jobId}/result`	작업을 나열하고, 상태를 폴링하고, 결과를 가져옵니다.
Generation	`POST /images/generations`, `POST /videos/generations`, `POST /ads/videos`, `POST /face-swap`, `POST /reference-analysis`	비동기 미디어 또는 분석 작업을 만듭니다. 크레딧을 사용할 수 있습니다.
Uploads	`POST /uploads/presign`, `POST /assets`	영상을 업로드하고 Asset Library ingest 또는 기능별 워크플로로 finalize합니다.
Asset Library	`GET /assets`, `GET /assets/{assetId}`	색인된 장면 에셋을 검색하고 재사용 가능한 클립/소스 메타데이터를 조회합니다.

비동기 워크플로

대부분의 쓰기 엔드포인트는 작업을 만듭니다.

/me와 /credits로 계정과 크레딧을 확인합니다.
POST /videos/generations 같은 엔드포인트로 작업을 만듭니다.
작업이 종료 상태에 도달할 때까지 GET /jobs/{jobId}를 폴링합니다.
GET /jobs/{jobId}/result로 결과를 가져옵니다.
반환된 공개 미디어 URL이나 메타데이터를 다음 단계에서 사용합니다.

curl https://www.sume.so/api/v1/videos/generations \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A creator demonstrates a vitamin serum in a bright studio.",
    "aspect_ratio": "9:16",
    "duration": 5,
    "generate_audio": false
  }'

업로드 워크플로

엔드포인트가 사용자 제공 미디어를 필요로 할 때 업로드를 사용합니다.

curl https://www.sume.so/api/v1/uploads/presign \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_name": "reference.mp4",
    "content_type": "video/mp4",
    "size_bytes": 12000000
  }'

반환된 upload_url로 바이트를 업로드할 때는 함께 반환된 required_headers를 사용합니다. Asset Library ingest는 다음 요청으로 finalize합니다.

curl https://www.sume.so/api/v1/assets \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "object_key": "uploads/...",
    "file_name": "reference.mp4"
  }'

페이지네이션

목록 엔드포인트는 cursor pagination을 사용합니다.

{
  "object": "list",
  "data": [],
  "has_more": false,
  "next_cursor": null
}

계속 조회하려면 next_cursor를 cursor로 다시 전달합니다.

오류 envelope

{
  "error": {
    "code": "invalid_request",
    "message": "A human-readable error message.",
    "details": {}
  },
  "request_id": "req_..."
}

정확한 요청/응답 스키마는 /api/openapi.json을 참고하세요.