Format API

이 문서는 영문 원고를 AI로 번역한 내용이라 표현이 어색할 수 있습니다.

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

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

Agents UI, Models, SDK, Dashboard 등 Sume 표면 전체 맵은 Sume 기초에서 시작하세요.

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이 못 하는 일을 낼 수 있습니다. 단일 짧은 클립은 모델 호출 한 번이고, 라이브 커머스·product-promo 결과물은 여러 도구 호출과 조립을 거친 게시 준비(post-ready) 비디오입니다.

멘탈 모델

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

PieceWhat it is
The recipeFormat 자체입니다. 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}로 폴링합니다. 대량 실행을 보세요.

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

런타임 흐름

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

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

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

TypeScript SDK의 subscribeFormatRun은 대신 폴링하고, run이 종료될 때까지 상태 업데이트를 줍니다.

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

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

원본 Video 1.0(또는 유사) 호출은 그 모델의 길이·프레이밍 한도 안의 생성 클립 하나를 돌려줍니다. 긴 게시 준비 작업 — 예를 들어 제품 삽입이 있는 약 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 / Avatar talking-videoFormat (예: live-commerce, product promo)
작업 단위모델 Job 하나여러 도구를 호출할 수 있는 샌드박스 Agent run 하나
전형적 출력클립 하나조립된 post-ready 결과물(+ 선택적 JSON)
스타일 / 플레이북호출마다 프롬프트SKILL.md에 저장(버전된 레시피)
누가 오케스트레이션호출자 코드Format (샌드박스의 Agent + 도구)
적합한 경우직접 조립할 원자적 생성패키지 워크플로가 필요한 파트너 제품

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

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

Format API를 언제 쓰나요

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

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

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

Instruction 조합

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

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은 무인입니다를 참고하세요.

크기는 얼마여야 하나

본문에는 별도의 한도가 없습니다. 패키지의 모든 파일이 공유하는 한도 — 파일당 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}는 아래 형태를 돌려줍니다.

FieldNotes
statusactive 또는 inactive입니다. API 호출 트리거가 프로비저닝되기 전에는 inactive이며, inactive Format은 API 실행을 거절합니다.
api_trigger_enabledtrue이면 POST /v1/formats/{handle}/{slug}/runs와 …/bulk-runs(및 opaque 경로)가 허용됩니다.
handle / vanity_invoke_url사용자 대면 주소입니다. 링크와 curl에는 이를 우선하세요. first-party Format은 null입니다.
invoke_urlOpaque 경로입니다. 영구적이므로 이름 변경이 저장된 URL을 깨면 안 될 때는 반드시 저장해야 합니다.
version수정할 때마다 증가합니다. 실제로 사용된 버전은 run receipt의 format.version에 메아리칩니다.
sourcefirst_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에는 팀 키가 필요합니다를 보세요.

다음