---
title: Format API
description: 저장해 둔 작성 레시피를 백엔드에서 호출하세요. HTTP 한 번으로 샌드박스에서 실행되고, 제공한 스키마가 결과를 typed JSON으로 만듭니다.
---

Format은 저장해 둔 작성 레시피입니다. 하우스 스타일, 출력 계약, 제작 플레이북을 담고 있는 객체로 이해하면 됩니다. HTTP로 호출하면 Sume가 실행하고, 내구성 있는 미디어와 직접 정의한 형태의 JSON 객체를 돌려줍니다.

대부분의 파트너가 연동하는 표면입니다. 직접 유지하는 프롬프트 대신 호출 한 번이고, 파싱해야 하는 transcript 대신 typed 레코드 하나입니다.

Agents UI, Models, SDK, Dashboard 등 Sume 표면 전체 맵은 [Sume 기초](/the-basics)에서
시작하세요.

```bash
curl -sS -X POST "https://api.sume.com/v1/formats/chase/product-promo/runs" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"instruction":"Make two ad images for the linked product.","input":{"product_url":"https://example.com/p"}}'
```

## Format이 왜 존재하는가

Sume는 **비디오 에이전트** 플랫폼입니다. Image, Video, Avatar, TTS, timeline 등 관련
도구는 HTTP·MCP API로도 쓸 수 있지만, 그 호출을 직접 이어 붙이면 어려운 부분이
남습니다. 다음에 어떤 클립을 만들지, 제품 사실을 어떻게 가져올지, VO를 어떻게 쓸지,
타임라인을 어떻게 조립할지, 한 단계가 깨졌을 때 어떻게 깨끗이 실패할지가 그 부분입니다.

Format은 그 판단을 저장한 것입니다. 파트너는 vanity URL
(`POST /v1/formats/{handle}/{slug}/runs`)을 호출하고, Sume는 레시피와 생성 도구를 갖춘
샌드박스 Agent를 띄웁니다. 오케스트레이션 그래프를 직접 소유하지 않아도 아티팩트와
(선택적) 구조화 출력을 받습니다.

그래서 Format은 원본 [Video 1.0](/models/video)이 못 하는 일을 낼 수 있습니다. 단일
짧은 클립은 모델 호출 한 번이고, 라이브 커머스·product-promo 결과물은 여러
도구 호출과 조립을 거친 **게시 준비(post-ready)** 비디오입니다.

```text
Format run = fresh sandbox + recipe (SKILL) + instruction/input + tools
           → artifacts + optional structured output
```

## 멘탈 모델

네 조각이며, 네 개를 한꺼번에 잡는 것이 중요합니다.

| Piece | What it is |
|---|---|
| **The recipe** | Format 자체입니다. `SKILL.md` 본문과 참고 파일이며, Agents 대시보드나 채팅에서 Agent에게 요청해 작성합니다. *어떻게* — 하우스 스타일, 분기 규칙, 품질 기준입니다. |
| **The sandbox** | 모든 run은 새로 만든 샌드박스(파일시스템·셸·Sume 생성 도구가 있는 원격 Linux 워크스페이스)를 받습니다. 레시피 파일이 그곳에 놓이고, run은 그 안에서 작업합니다. 이전 호출자의 디스크는 새지 않습니다. |
| **The call** | 요청마다 넣는 `instruction`과 `input`입니다. *무엇을* — 제품 URL, 브리프, 로케일, SKU입니다. |
| **The schema** | 선택적 JSON Schema입니다. 보내면 끝난 run이 그 스키마로 투영되어 prose 대신 typed JSON이 돌아옵니다. |

연동에 핵심이 되는 성질이 두 가지 따라옵니다.

**한 run은 한 단위의 작업입니다.** 새 스레드, Agent 턴 한 번, receipt 하나입니다. 부분 전달은 없습니다. 끝내지 못한 run은 `failed`로 돌아오며, 절반만 끝난 `completed`는 없습니다. bulk 요청(`POST …/bulk-runs`)은 두 번째 실행 엔진이 아니라 그 run들의 서버 측 큐입니다. 각 item은 여전히 Format run 하나이고, 큐는 `concurrency`개만 동시에 띄웁니다. 목록은 `GET /v1/format-run-queues/{queue_id}`로 폴링합니다. [대량 실행](/formats/bulk-runs)을 보세요.

**Sume는 작성된 레시피로 run을 이끕니다.** Format 본문이 instruction보다 앞에 조합되므로, 작업보다 먼저 하우스 스타일이 자리를 잡습니다. 호출마다 system prompt를 다시 보내고 버티길 바라는 구조가 아닙니다.

## 런타임 흐름

`POST` 이후에 일어나는 일입니다.

```text
POST /v1/formats/{handle}/{slug}/runs
  -> 202 with a run receipt (status: queued)
  -> sandbox boots; recipe files land on disk
  -> Agent reads SKILL.md (+ references it asks for)
  -> Agent uses tools as the recipe requires, for example:
       talking / avatar video, image-to-video B-roll,
       TTS / voiceover, captions, timeline assembly
  -> artifacts mirrored to media.sume.com
  -> poll GET /v1/format-runs/{run_id}/status until terminal
  -> GET /v1/format-runs/{run_id}/result
  -> read `output` (your schema), `artifacts[]`, `primary_output_url`
```

Agent는 모델 엔드포인트 하나에 묶이지 않습니다. 라이브 커머스 스타일 Format은 호스트
테이크, 제품 B-roll, 보이스 트랙을 만든 뒤 타임라인에서 하나의 export로 합칠 수
있습니다. 연동 측에서는 여전히 Format run **하나**와 receipt **하나**만 보입니다.

작업이 실제이기 때문에 비동기입니다. 프로모나 수 분짜리 비디오는 밀리초가 아니라 분
단위 벽시계입니다. 폴링은 항상 동작하고, [Run 웹훅](/agents/run-webhooks)은 루프 없이
같은 receipt를 `api.dev.sume.com`과 `api.sume.com`에서 밀어 줍니다. push 스트림은
없지만, Format run의 `events_url`을 폴링하면 phase 타임라인(무엇을, 언제부터 하고
있는지)을 읽을 수 있습니다 — 로그 피드가 아닙니다.

TypeScript SDK의 [`subscribeFormatRun`](/sdk/runs)은 대신 폴링하고, run이 종료될 때까지
상태 업데이트를 줍니다.

구조화 출력은 run이 종료 상태에 도달한 **뒤에**, 실제로 만든 결과물에 대한 별도
constrained pass로 만들어집니다. 이 순서가 설계 전부이며, 자세한 내용은
[구조화 출력](/formats/structured-output)에서 살펴보세요.

## 수 분짜리 post-ready 비디오가 가능한 이유

원본 [Video 1.0](/models/video)(또는 유사) 호출은 그 모델의 길이·프레이밍 한도 안의
생성 클립 하나를 돌려줍니다. 긴 게시 준비 작업 — 예를 들어 제품 삽입이 있는 약 5분
라이브 커머스 호스트 비디오 — 은 “Video 1.0에 5분을 요청”하는 일이 아닙니다. 오케스트레이션입니다.

1. 제품·브리프에서 비트 계획 (레시피 안).
2. 맞는 도구로 호스트·B-roll 세그먼트 생성.
3. 레시피가 요구하면 VO 합성 또는 부착.
4. 타임라인에서 세그먼트를 하나의 export로 조립.
5. 내구성 있는 `media.sume.com` URL(과 선택적 typed `output`)을 반환.

Format이 1–5단계를 소유합니다. 백엔드는 호출, 폴링(또는 웹훅이 켜진 뒤 웹훅),
결과 활용을 소유합니다.

## Format vs 원본 비디오 API

| | [Video 1.0](/models/video) / [Avatar talking-video](/models/avatar-videos) | **Format** (예: live-commerce, [product promo](/formats/product-promo)) |
|---|---|---|
| 작업 단위 | 모델 Job 하나 | 여러 도구를 호출할 수 있는 샌드박스 Agent run 하나 |
| 전형적 출력 | 클립 하나 | 조립된 post-ready 결과물(+ 선택적 JSON) |
| 스타일 / 플레이북 | 호출마다 프롬프트 | `SKILL.md`에 저장(버전된 레시피) |
| 누가 오케스트레이션 | 호출자 코드 | Format (샌드박스의 Agent + 도구) |
| 적합한 경우 | 직접 조립할 원자적 생성 | 패키지 워크플로가 필요한 파트너 제품 |

이미지·클립 하나만 필요하고 조립은 다른 곳에서 할 때는 모델 API로 내려가세요. 제품 가치가
완성된 패키지에 있을 때는 Format vanity 호출을 우선하세요.

프로비저닝된 Format이 있는 엔터프라이즈 파트너(예: Mobidoo)는
`/enterprise/{slug}/formats` 포털 페이지에서 레시피 목록과 채워진 호출 예시도 받습니다.

## Format API를 언제 쓰나요

| You want | Use |
|---|---|
| 스타일은 고정이고 입력만 바뀌는 패키지 워크플로 | **Format API** — 이 페이지 |
| 모델 호출 한 번만 | 모델 엔드포인트: [Image 1.0](/models/image), [Video 1.0](/models/video), [Music 1.0](/models/music) |
| 같은 저장 작업을 주기로 | [Scheduled](/agents/actions) |
| 저장할 가치 없는 임시 작업 | [Agent Completions](/agents/completions) |
| 사람이 승인하며 진행 | [sume.com/agents](https://www.sume.com/agents)의 Agents 채팅 UI |

원본 모델 엔드포인트와의 경계가 유용합니다. `POST /v1/image-1.0/generate`는 이미지를 만들고, Format은 *어떤* 이미지를 만들지 정하고 만든 뒤 라벨된 결과를 건넵니다. 제품 가치가 그 사이 판단에 있다면, 그 판단은 자체 오케스트레이션 코드가 아니라 Format에 두는 편이 맞습니다.

Format은 대시보드나 채팅에서 작성합니다. Developer API는 목록·읽기·실행 시작(하나, 또는 bulk 큐)·run과 큐 모니터링만 할 수 있고, 생성·수정은 할 수 없습니다.

## Instruction 조합

Format run마다 서버는 Agent instruction을 아래 정확한 순서로 조합합니다.

````text
[Format: product-promo v3]
<a pointer at the Format's SKILL.md in the run's workspace>

[Format attached: product-promo v3 → /workspace/skills/product-promo/SKILL.md]
<where the whole package lives in the run's workspace>

[Format run instruction]
<your `instruction`, or the Format's default when you omit it>

[Sume action input]
<`input`이 통째로 기록된 /workspace/inputs/sume-action-input.json을 가리키는 포인터>
````

Format 본문이 **먼저** 옵니다. *어떻게*가 작업보다 먼저 자리를 잡아야 합니다. `instruction`은 마지막에 오므로, 둘이 어긋나면 모델은 호출자가 요청한 내용을 따릅니다.

알아둘 규칙 세 가지입니다.

- **패키지는 첨부될 뿐, 인라인되지 않습니다.** `SKILL.md`와 참고 파일은 run마다 `/workspace/skills/<slug>/`에 기록되고 `[Format attached]`가 그 경로를 알려줍니다. 그래서 본문이 *`references/style.md`를 읽어라*고 하면 동작합니다. 턴에는 그 포인터만 실립니다. 본문 크기와 무관하게 `SKILL.md` 텍스트는 턴에 복사되지 않습니다.
- **`input`은 데이터이지 지시가 아닙니다.** 크기와 무관하게 `/workspace/inputs/sume-action-input.json`에 통째로 기록되고, 턴에는 행동 전에 읽어야 할 호출자 공급 데이터임을 알리는 유한한 포인터만 실립니다.
- **API 경유 run은 무인입니다.** 대화형 채팅용 본문은 사람 승인을 기다릴 수 있습니다. API에서는 그 승인이 미리 부여되고, spend cap 안에서 계속 진행됩니다. [API 경유 run은 무인입니다](/formats/call#runs-over-the-api-are-unattended)를 참고하세요.

### `SKILL.md` 크기는 얼마여야 하나

본문에는 별도의 한도가 없습니다. 패키지의 모든 파일이 공유하는 한도 — 파일당 100 MiB, 패키지당 100 MiB — 만 적용되고, 그것도 run 시점이 아니라 Format을 저장하는 시점에 검사합니다. 저장된 Format은 실행됩니다. `SKILL.md`는 짧은 색인으로 두고, Agent가 필요할 때 `references/`를 읽게 하세요.

크기는 전달 방식도 바꾸지 않습니다. 본문은 run마다 파일로 첨부되고 Agent가 그것을 읽습니다. 크기가 바꾸는 것은 얼마나 잘 *지켜지는가*입니다. 규칙이 한 번씩만 적힌, Agent가 한 번에 읽어낼 수 있는 본문은 같은 규칙이 스무 페이지에 묻힌 본문보다 더 정확히 지켜집니다. 그러므로:

- **Agent가 한 번에 붙잡을 수 있는 명세를 쓰세요.** 정체성, 타협 불가 규칙을 한 줄씩, 단계 색인, 도구 목록 — 세부는 본문이 가리키는 `references/*`에 둡니다.
- **본문을 키우는 대신 세부를 참고 파일로 밀어내세요.** 참고 파일은 같은 디렉터리에 `SKILL.md`와 나란히 첨부되고, 열리기 전까지 턴에 아무 비용도 들지 않습니다.
- **규칙이 확실히 닿게 하려고 분량을 늘리지 마세요.** 짧은 본문에 한 번 적힌 규칙이 긴 본문에 세 번 적힌 같은 규칙보다 낫습니다. 긴 쪽을 거절하는 장치는 없습니다 — 다만 덜 지켜질 뿐이고, 그쪽이 더 비싼 실패입니다.

## Format의 구조

`GET /v1/formats`와 `GET /v1/formats/{format_id}`는 아래 형태를 돌려줍니다.

```json
{
  "id": "skl_...",
  "object": "format",
  "slug": "product-promo",
  "handle": "chase",
  "title": "Product promo",
  "description": "House style for product promo videos.",
  "source": "custom",
  "version": 3,
  "status": "active",
  "api_trigger_enabled": true,
  "model": "...",
  "generation_spend_cap_usd_micros": 1000000,
  "created_at": "2026-07-20T12:00:00.000Z",
  "updated_at": "2026-07-30T09:00:00.000Z",
  "invoke_url": "https://api.sume.com/v1/formats/skl_.../runs",
  "vanity_invoke_url": "https://api.sume.com/v1/formats/chase/product-promo/runs"
}
```

| Field | Notes |
|---|---|
| `status` | `active` 또는 `inactive`입니다. API 호출 트리거가 프로비저닝되기 전에는 `inactive`이며, `inactive` Format은 API 실행을 거절합니다. |
| `api_trigger_enabled` | `true`이면 `POST /v1/formats/{handle}/{slug}/runs`와 `…/bulk-runs`(및 opaque 경로)가 허용됩니다. |
| `handle` / `vanity_invoke_url` | 사용자 대면 주소입니다. 링크와 curl에는 이를 우선하세요. first-party Format은 `null`입니다. |
| `invoke_url` | Opaque 경로입니다. 영구적이므로 이름 변경이 저장된 URL을 깨면 안 될 때는 반드시 저장해야 합니다. |
| `version` | 수정할 때마다 증가합니다. 실제로 사용된 버전은 run receipt의 `format.version`에 메아리칩니다. |
| `source` | `first_party`는 큐레이션된 카탈로그입니다. Formats by Sume는 어떤 키로든 `sume/{slug}`로 호출하며, run은 그 키에 청구됩니다. |

`SKILL.md` 본문은 의도적으로 이 형태에 없습니다. 모델에게 전달되며 호출자에게는 돌아가지 않습니다.

정확한 요청·응답 스키마는 라이브 OpenAPI(`https://api.sume.com/reference/json`)를 참고하세요. 이 페이지의 표는 읽기 쉬운 요약이며 두 번째 스키마가 아닙니다.

## Format API가 아직 지원하지 않는 것

- **push 스트림이 없습니다.** SSE도 WebSocket도 없습니다. Format run receipt의 `events_url`은 폴링용 phase 타임라인이며, 로그 스트림이 아닙니다.
- **페이지네이션이 없습니다.** 목록 응답은 항상 `has_more: false`, `next_cursor: null`입니다.
- **API로 작성할 수 없습니다.** Developer API는 Format을 만들거나 수정·삭제할 수 없습니다. 대시보드를 쓰거나 채팅에서 Agent에게 요청하세요.
- **팀 Format은 팀(워크스페이스) 키가 필요합니다.** 팀 워크스페이스가 소유한 Format은 vanity·opaque 경로 모두로 호출할 수 있지만, **그 워크스페이스에서 만든** API 키여야 합니다. 개인 키는 `403 workspace_key_required`로 실패합니다. [팀 Format에는 팀 키가 필요합니다](/formats/call#team-formats-need-a-team-key)를 보세요.

## 다음

- [Sume 기초](/the-basics) — Agents, Formats, Models, 클라이언트 제품 맵
- [Format 호출하기](/formats/call) — 인증, 스코프, 호출 계약, 모든 오류
- [대량 실행](/formats/bulk-runs) — run을 최대 100개까지 큐에 넣고 `GET /v1/format-run-queues/{id}`를 폴링
- [구조화 출력](/formats/structured-output) — 스키마 규칙, 투영, 실패 모드
- [실행과 결과](/formats/runs) — receipt 필드별 설명, 폴링, 취소
- [실행 기다리기 (SDK)](/sdk/runs) — `subscribeFormatRun` / `waitForRun`
- [Format 카탈로그](/formats/catalog) — 준비된 first-party Format
- [Product promo](/formats/product-promo) · [Avatar UGC video](/formats/avatar-ugc)
- [제품에 Format 임베드하기](/cookbooks/embed-a-format) — 파트너 연동 전체