API로 AI 영상 워크플로 만들기: Sume Format과 SKILL.md

Sume API로 AI 영상 워크플로를 만들려면 slug를 담아 POST /v1/formats를 보내세요. 그러면 API 키의 워크스페이스에 최소한의 SKILL.md가 든 새 Format이 열리고, 그다음 Contents API로 그 파일을 여러분의 레시피로 교체합니다. 백엔드는 완성된 Format을 POST /v1/formats/{handle}/{slug}/runs로 호출합니다.

Format은 백엔드가 이름으로 호출하는 저장된 레시피입니다. 채팅에서 Format을 작성하는 방법은 Sume Format이란?에서 다룹니다. 아래 내용은 2026-09-26에 확인한 Format 패키지 편집하기, Format API (영문) 페이지, Sume API 레퍼런스에서 가져왔습니다.

새 Format은 어느 워크스페이스에 속하나요?

키가 속한 워크스페이스입니다. POST /v1/formats에는 formats:write가 필요하고 주소에 {handle}이 없으므로, 다른 사람의 워크스페이스에 Format을 만들 방법은 없습니다. 팀 키는 그 워크스페이스의 handle로 호출되는 팀 Format을 만들고, 개인 키는 여러분 자신의 handle에 Format을 만듭니다.

formats:write가 없는 키는 403 insufficient_scope를 받습니다. 기존 키에 스코프를 덧붙일 수는 없으므로, 이 스코프가 있는 새 키를 발급하세요. 서비스 계정 키도 같은 403을 받습니다. 서비스 계정 키로는 패키지를 만들거나 편집할 수 없습니다.

POST /v1/formats는 어떤 필드를 받나요?

본문은 파일이 아니라 Format 자체를 설명합니다. 패키지 파일은 Contents API로 다루므로, 누가 썼든 같은 규칙 하나를 따릅니다.

Format을 만들고 레시피를 쓰려면 어떻게 하나요?

호출 세 번이면 됩니다. 만들기 요청은 새 Format과 함께 201로 응답하며, 여기에는 skl_… id, handle, slug, version, package_sha, contents_url, vanity_invoke_url이 담깁니다. package_sha와 contents_url은 보관하세요. 앞의 것은 다음 쓰기의 If-Match 전제 조건이고, 뒤의 것은 그 쓰기를 보낼 주소입니다. 초기 SKILL.md를 교체하는 것이 원래 의도된 다음 호출입니다. 그 파일은 이미 있으므로, 교체하려면 읽기로 얻은 blob sha가 필요합니다.

# 1. Open the Format in your key's workspace
curl -sS -X POST "https://api.sume.com/v1/formats" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"slug":"plate-shots","title":"Plate shots","description":"Studio plate photography."}'

# 2. Read the seed SKILL.md for its sha
curl -sS "https://api.sume.com/v1/formats/acme/plate-shots/contents/SKILL.md" \
  -H "Authorization: Bearer $SUME_API_KEY"

# 3. Replace it: content is the whole new file, base64-encoded
curl -sS -X PUT "https://api.sume.com/v1/formats/acme/plate-shots/contents/SKILL.md" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "If-Match: $PACKAGE_SHA" \
  -H "Content-Type: application/json" \
  -d '{"message": "write the recipe", "content": "LS0tCm5hbWU6IHBsYXRlLXNob3Rz…", "sha": "0ee8…"}'

Format 패키지에는 무엇이 들어 있어야 하나요?

패키지 규칙은 무엇이든 커밋되기 전에 검사되며, 거부된 패키지는 아무것도 커밋하지 않습니다. 첫 쓰기에서 만나게 되는 규칙은 다음과 같습니다.

• SKILL.md는 패키지 루트에 두며, frontmatter의 name은 Format의 slug와 같아야 합니다.
• 다른 파일은 루트에 두거나 references/ 또는 agents/ 아래 한 단계 깊이까지 둘 수 있고, 형식은 .md, .json, .yaml, .yml, .txt입니다.
• 경로가 거부되면 skill_path_invalid 응답에 허용 규칙 전체가 함께 오므로, 한 번 거부된 것만으로 이름을 고칠 수 있습니다.
• 쓰기마다 새 commit.tree.sha(다음 If-Match 값)와 version이 돌아옵니다. 여러 파일을 한 번에 커밋하는 방법은 If-Match로 Sume Format 파일 편집하기에서, 레시피에 무엇을 담을지는 SKILL.md 레시피 작성법에서 다룹니다.

만들기 요청은 어떤 오류를 돌려줄 수 있나요?

앞의 네 가지는 문서 페이지에 나와 있습니다. 마지막 두 가지는 문서 페이지에는 없는 현재 동작입니다.

• 409 skill_slug_taken: 워크스페이스에 그 slug의 Format이 이미 있습니다. 만들기는 절대 덮어쓰지 않으므로 다른 slug를 고르세요.
• 409 skill_slug_reserved: Sume가 제공하는 Format이 그 slug를 전역으로 쓰고 있습니다.
• 503 format_git_unavailable: 패키지 히스토리를 열 수 없었습니다. 저장소는 카탈로그 행보다 먼저 열리므로 Format은 만들어지지 않았습니다.
• 403 insufficient_scope: 키에 formats:write가 없거나, 서비스 계정 키입니다.
• 400 skill_slug_invalid: 예약된 slug인 runs, bulk-runs, grants에 반환됩니다. 이 slug는 API 경로와 충돌하기 때문입니다.
• 400 skill_limit_exceeded: 키를 소유한 사용자가 이미 커스텀 Format을 50개 소유하고 있을 때 반환됩니다. 이 상한은 워크스페이스가 아니라 그 사용자의 Format을 셉니다.

기존 Format에서 시작할 수도 있나요?

네. Sume가 제공하는 Format을 바꾸고 싶다면 Format 라이브러리에서 fork하세요. 사본의 주소는 {your_handle}/{slug}입니다. 에이전트 대시보드나 채팅에서 Format을 작성할 수도 있습니다.

어떻게 만들었든 POST /v1/formats/{handle}/{slug}/runs로 호출하세요. API로 한 번도 실행하지 않은 Format은 첫 실행 전까지 status: inactive와 api_trigger_enabled: false로 보일 수 있지만 그래도 실행됩니다. 그러니 이 필드 값을 연동의 조건으로 삼지 마세요.