2026-09-23포맷

Sume Format이란? 에이전트 스레드를 API 호출 한 번으로

Sume Format은 백엔드가 handle과 slug로 호출하는 저장된 영상 레시피입니다. POST 한 번으로 새 샌드박스에서 실행되고, 미디어와 선택적 typed JSON을 돌려줍니다.

읽는 시간 6분Sume

Sume Format은 한 종류의 영상을 만드는 저장된 제작 레시피로, 하우스 스타일과 출력 계약, 에이전트가 따르는 플레이북으로 이뤄집니다. 백엔드는 HTTP 요청 한 번으로 handle과 slug를 지정해 Format을 호출합니다. Sume는 생성 도구가 갖춰진 새 샌드박스에서 Format을 실행하고 media.sume.com에 있는 완성된 미디어를 돌려주며, 요청하면 직접 정의한 형태의 JSON 객체도 함께 돌려줍니다.

이 글에서는 Format을 어디서 만드는지, 실행 한 번이 무엇을 하는지, 어떻게 호출하는지 설명합니다. 아래의 API 세부 사항은 모두 Format API 문서 (영문)에서 가져왔습니다.

Format은 어디서 만드나요?

Format은 에이전트 탭에서 만듭니다. 에이전트에게 브리프를 주고, 초안을 검토하고, 원하는 결과가 나올 때까지 다듬은 뒤 “이 내용을 product-promo라는 Format으로 저장해 줘.”처럼 레시피 저장을 요청하면 됩니다. 저장된 Format은 SKILL.md 본문과 참고 파일로 이뤄지며, 여러분의 handle과 직접 정한 slug가 그 주소가 됩니다.

채팅 스레드는 사람이 과정에 계속 참여하는 곳입니다. Format은 레시피가 확정된 뒤 여러분의 시스템이 호출하는 대상입니다.

Format 실행 한 번은 무엇을 하나요?

실행은 Format이 첨부된 무인 에이전트 턴 한 번입니다. 실행은 도중에 멈춰 사람에게 무언가를 묻지 않습니다. 채팅에서 만든 레시피라면 요청했을 승인이 미리 부여되어 있고, 실행은 지출 상한 안에서 계속 진행됩니다.

요청은 202로 접수되고, status_url, result_url, events_url, cancel_url이 담긴 영수증이 돌아옵니다.
새 샌드박스가 부팅되고 Format 패키지가 디스크에 놓입니다.
에이전트가 레시피를 따라 생성 도구를 호출해 호스트 테이크, B-roll, 보이스오버, 자막, 타임라인 조립을 처리합니다.
미디어는 media.sume.com에 미러링됩니다. URL은 내구성 있는 공개 URL이므로 저장해 둘 수 있습니다.
종료 영수증은 서명된 웹훅(format.run.terminal)이나 폴링으로 받습니다.

백엔드에서 Format을 어떻게 호출하나요?

API 키에서 formats:read와 formats:write 스코프가 있는 API 키를 만들어 서버에만 두고, 그다음 실행을 만드세요. Idempotency-Key에는 요청마다 새로 만든 UUID가 아니라 만드는 대상에서 파생한 값(주문 ID와 버전)을 보내세요. 그래야 재시도가 두 번째 실행을 시작하지 않습니다.

curl -sS -X POST "https://api.sume.com/v1/formats/acme/product-promo/runs" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-8823-v1" \
  -d '{
    "instruction": "Vertical 9:16, 15 seconds. Use the product page as the brief.",
    "input": { "product_url": "https://shop.example.com/p/8823" },
    "generation_spend_cap_usd": 20,
    "communication": { "webhook_url": "https://acme.example.com/hooks/sume" }
  }'

요청으로 무엇을 제어할 수 있나요?

Format 호출하기 (영문) 문서에 나온 요청 필드, 2026-09-23 확인.
필드	역할
`instruction`	여러분이 직접 쓴 작업 내용이며, 최대 8,000자입니다. 생략하면 Format의 기본 instruction으로 실행합니다.
`input`	JSON 객체로 보내는 호출자 데이터입니다. 최상위 키는 최대 64개, 크기는 최대 2 MiB입니다.
`output_schema`	JSON Schema를 바인딩하면 `output`이 그 형태로 돌아옵니다. 구조화 출력 (영문)을 참고하세요.
`generation_spend_cap_usd`	이 실행의 생성 비용 상한이며, 플랫폼 최대치인 $500까지 지정할 수 있습니다. 생략하면 Format의 상한을 물려받습니다.
`communication.webhook_url`	실행이 완료되거나 실패하면 서명된 POST를 한 번 받는 공개 HTTPS URL입니다.
`previous_run_id`	처음부터 새로 시작하지 않고, 이 Format의 이전 실행을 다음 턴으로 이어 갑니다.

문단 대신 typed JSON으로 받을 수 있나요?

네. 기본적으로 완료된 실행은 미디어와 약간의 텍스트를 돌려줍니다. output_schema(또는 OpenAI 형태의 별칭인 response_format)를 바인딩하면 실행의 output이 여러분의 스키마에 맞게 투영되므로, 자체 레코드에 바로 기록할 수 있습니다. 미디어 필드는 내구성 있는 URL을 담은 SumeMediaFile을 참조합니다. 지원하는 키워드와 모든 실패 모드는 구조화 출력 (영문) 페이지에 있습니다.

Format을 여러 번 실행하려면 어떻게 하나요?

대량 실행 큐를 쓰세요. 요청 하나에 항목을 1개에서 100개까지 담을 수 있고 각 항목의 본문은 단일 실행과 같으며, concurrency 창으로 동시에 진행할 실행을 1개에서 16개까지 정합니다. 대량 요청은 다른 엔진이 아니라 일반 실행을 모은 서버 측 큐입니다. 자세한 내용은 대량 실행을 참고하세요.

Format, Agent Completion, Scheduled 중 무엇을 써야 하나요?

세 가지 모두 같은 에이전트를 실행하고 같은 형태의 영수증을 돌려줍니다. 차이는 지시문이 어디서 오는지, 그리고 Sume가 무엇을 대신 저장해 두는지입니다.

Agent Completions 문서 기준, 2026-09-23 확인.
표면	언제 쓰는지	시작점
Format	저장된 워크플로가 있고 입력만 바뀝니다.	`POST /v1/formats/{handle}/{slug}/runs`
Scheduled	저장된 자동화에 스케줄이나 트리거가 필요합니다.	`POST /v1/actions/{handle}/{slug}/runs`
Agent Completion	작업 자체가 호출마다 달라집니다.	`POST /v1/agent/completions`

비용은 얼마이고, 누가 쓸 수 있나요?

Format은 유료 요금제에 포함됩니다. 실행 비용은 워크스페이스의 잔액 하나에서 모델별 공개 요율대로 차감되며, 실행이 유효 상한을 넘겨 지출하는 일은 없습니다. 영수증에는 상한과 실행의 실제 지출액이 모두 표시됩니다. 요금제는 요금제에, 모델별 요율은 API 요금에 있습니다.

영상을 만드는 실행은 몇 초가 아니라 몇 분이 걸리므로, 처음부터 비동기 경로를 전제로 설계하세요. 웹훅을 받거나 영수증의 status_url을 폴링하면 됩니다.

출처

작성자 Sume