AI 영상 출력용 JSON 스키마: 복사해 쓰는 템플릿 5개
Sume에서 AI 영상 출력에 쓸 JSON Schema 템플릿입니다. 영상 하나, 영상과 게시 문구, 포스터, 화면 비율, 자막 큐를 모두 strict 부분집합 안에서 복사해 쓸 수 있습니다.
포맷
API로 Sume 포맷을 다루는 글입니다. 포맷 생성과 버전 관리, 호출, 대량 실행, 구조화된 출력, 웹훅, 실패한 실행 디버깅을 다룹니다.
Sume API로 AI 영상의 장면 하나를 다시 생성하기
AI 영상의 장면 하나를 다시 생성하려면 previous_run_id로 Sume Format 실행을 이어 가며 그 장면을 지정하세요. 그 클립만 다시 만들고 나머지는 그대로 둘 수 있습니다.
Sume Format 실행 실패: 오류 코드, 세부 정보, 대응 방법
실패한 Sume Format 실행은 error.code에 원인을 담습니다. 코드별 details 필드, 청구되는 비용, 이어 갈지 재시도할지를 정리했습니다.
프롬프트 인젝션과 사용자 입력: AI 에이전트 API에 데이터 넘기기
고객 텍스트는 Sume 실행의 instruction이 아니라 input 객체에 넣으세요. 에이전트는 이를 데이터로 읽으라는 안내를 받으며, 문서는 이를 샌드박스가 아닌 신뢰 경계라고 부릅니다.
Sume Format 레시피용 SKILL.md 파일 작성법
Sume Format 레시피는 SKILL.md 파일과 참고 파일로 이뤄집니다. SKILL.md는 짧은 색인으로 두고, 세부 내용은 references/로 옮기고, 패키지 규칙을 지키세요.
Sume 실행이 AI 생성 영상을 전달했는지 확인하는 방법
Sume 실행을 전달 완료로 세기 전에 status와 primary_output_url을 확인하고, filled_by를 읽고, 파일을 프로브하세요. Sume가 검사하는 것과 하지 않는 것을 정리했습니다.
장면 원장으로 실패한 AI 영상 실행의 부분 결과 받기
출력 스키마가 부분 결과를 허용하면 실패한 Sume Format 실행도 만든 장면을 보고합니다. nullable 필드를 쓰고, minItems는 빼고, primary 키를 지정하세요.
If-Match 낙관적 동시성: API로 Sume Format 파일 편집
다른 작성자의 변경을 덮어쓰지 않고 API로 Sume Format 파일을 편집하세요. 쓰기마다 파일의 blob sha를 보내고, If-Match가 패키지 전체를 지킵니다.
API로 AI 영상 워크플로 만들기: Sume Format과 SKILL.md
POST /v1/formats로 Sume Format을 만든 뒤 Contents API로 SKILL.md 레시피를 쓰세요. 요청 필드, slug 규칙, 처리할 오류를 정리했습니다.
AI 영상 워크플로를 다른 팀과 공유: Sume Format 공유 권한
Sume 팀 Format을 다른 팀 워크스페이스와 공유하세요. 공유 권한이 활성화되면 그 팀은 자기 팀 키로 소유자의 주소를 호출하고, 실행 비용도 직접 냅니다.
Sume Format API 한도: 상한, 크기, 타임아웃
문서화된 Sume Format API 한도를 한곳에 모았습니다. 요청과 입력 크기, 첨부 파일, 스키마, 지출 상한, 큐, 실행 기한, 웹훅, 요청 한도입니다.
strict 모드 JSON Schema oneOf 미지원: 위반 항목 고치기
Sume는 OpenAI strict 모드 부분집합을 벗어난 output_schema를 400 output_schema_invalid로 거부합니다. 위반마다 rule을 읽고 oneOf와 nullable을 옮기세요.
Format 목록 API: handle·id로 Sume Format 찾기
GET /v1/formats는 키로 호출할 수 있는 Format을 나열합니다. Format은 {handle}/{slug}나 영구적인 skl_ id로 지정하고, 그 실행은 최신순으로 나열합니다.
AI 에이전트가 지시를 무시했다면? Sume Format 실행 디버깅
Sume Format 실행이 예상과 다르게 동작했을 때 쓰는 체크리스트입니다. 조합된 첫 메시지, 전달된 지시문, 버전, 이벤트, 출력을 차례로 확인합니다.
프로덕션 AI 에이전트 프롬프트 버전 관리: Sume Format
Sume Format은 편집할 때마다 버전이 올라가고, 실행 영수증마다 실제로 실행된 버전이 기록됩니다. 실행을 특정 버전에 고정할 수 없고, 롤백 API도 없습니다.
AI 영상 배치 실패 항목 재시도: Sume 대량 실행 복구
Sume 대량 실행 큐가 완료되면 counts.failed를 읽고, 결과물을 남긴 실패한 자식 실행은 이어 가거나 새 Idempotency-Key로 다시 제출하세요.
AI UGC 광고 생성 API: Sume로 만드는 두 가지 방법
Sume API로 UGC 스타일 광고를 만들려면 sume handle의 카탈로그 UGC Format을 호출하거나, 직접 쓴 스크립트와 제품 이미지로 Avatar 1.0 말하는 영상을 렌더링하세요.
Sume Format 구조화 출력: JSON Schema대로 받는 JSON
JSON Schema를 output_schema로 바인딩하면 Sume Format 실행이 그 형태로 output을 돌려줍니다. 미디어 URL은 모두 실행이 만든 미디어와 대조됩니다.
Sume Format 대량 실행: 요청 한 번에 렌더 100개까지
Sume 대량 실행 요청은 일반 Format 실행 1–100개를 서버에서 큐에 넣고 1–16개를 동시에 진행합니다. 큐 URL 하나를 폴링하고, 각 자식은 일반 실행으로 읽으세요.
Sume Format 실행 수명주기: 상태, 웹훅, 폴링
Sume Format 실행은 queued에서 processing을 거쳐 종료 상태로 갑니다. 결과는 서명된 format.run.terminal 웹훅 한 번이나 폴링, 또는 둘 다로 확인합니다.
Sume Format으로 제품에 AI 영상 생성을 임베드하는 방법
AI 영상 생성을 임베드하려면 서버가 Sume API 키 하나를 들고 고객마다 Format을 실행합니다. 유도한 Idempotency-Key와 지출 상한, 웹훅을 함께 씁니다.
Sume Format이란? 에이전트 스레드를 API 호출 한 번으로
Sume Format은 백엔드가 handle과 slug로 호출하는 저장된 영상 레시피입니다. POST 한 번으로 새 샌드박스에서 실행되고, 미디어와 선택적 typed JSON을 돌려줍니다.
바로 쓰는 제품 영상 Format: Sume Format 카탈로그
Sume는 제품·UGC 스타일 영상과 이미지를 위한 바로 쓸 수 있는 Format을 제공합니다. 모두 예약된 sume handle에서 HTTP 요청 한 번으로 백엔드에서 호출할 수 있습니다.