Avatar UGC video

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

역할: 스크립트를 넘기면 완성된 talking-head 비디오를 돌려줍니다 — 브리프에 맞는 카탈로그 아바타 캐스팅, 캡션 번인, 사운드트랙 믹스까지. Format이 preview-then-generate 파이프라인 전체를 소유하므로, 글을 보내고 비디오 URL을 읽으면 됩니다.

이럴 때 쓰세요. 크리에이터 스타일 UGC 광고를 대량으로 만들고 스크립트만 바뀔 때입니다. 발표자 없이 제품 이미지와 모션 광고가 필요하면 Product promo를 쓰세요.

1st-party slug: sume-avatar-video-generation.

1. 주소 잡기

아래 스코프를 가진 키라면 sume/sume-avatar-video-generation로 바로 호출합니다. fork도, 설치도 필요 없습니다: 카탈로그 Format은 소유자 없이 공유되며, run과 그 미디어, 그 지출은 호출한 키에 귀속됩니다.

Format을 바꾸고 싶을 때는 fork가 그대로 있습니다 — Format 라이브러리의 Avatar video generation을 열고 Fork를 누르면 사용자가 소유한 편집 가능한 사본을 받습니다. fork는 본문과 spend cap을 유지하고 새 slug를 받으며(fork는 원본 slug를 재사용할 수 없으므로 대시보드는 sume-avatar-video-generation-custom을 제안합니다), 상세 페이지는 이를 {your_handle}/{slug}로 보여 줍니다. 호출을 위한 선행 조건이 아니라 커스터마이즈 단계입니다.

2. 스코프

ScopeNeeded for
formats:readFormat 읽기, run 읽기·목록입니다.
formats:writerun 시작, run 취소입니다.

Formats가 출시되기 전에 만든 키에는 이 스코프가 없고, 기존 키에 스코프를 추가할 수 없습니다 — API Keys에서 새 키를 만들고 교체하세요. 서비스 계정 키로는 Format run을 시작할 수 없습니다.

3. 호출하기

이미 경로를 저장한 클라이언트를 위해 불투명한 skl_… 경로는 계속 유효합니다. 새 연동은 {handle}/{slug}를 쓰세요.

수락된 run은 202를 반환합니다.

매 호출에 Idempotency-Key를 보내세요. 같은 본문으로 재전송하면 200과 원래 run이 돌아옵니다. 다른 본문으로 재전송하면 409 idempotency_conflict입니다.

에 대해

input은 자유 형식 JSON이며, 프롬프트에 호출자 데이터로만 울타리를 치고 instruction으로 쓰이지 않습니다. 선언된 스키마가 아닙니다 — Format 본문이 어떤 키를 읽을지 정하므로, 위 예시는 계약이 아니라 현실적인 형태입니다. 작게, 문자 그대로 유지하세요. 최대 64개 키, 8 KiB입니다.

이유가 없다면 캐스팅은 Format에 맡기세요. 스크립트와 브리프에 맞춰 아바타 카탈로그를 검색합니다. 직접 avatar_handle을 지정하면 그 결과를 고정하고 검색 단계를 건너뜁니다.

4. Spend cap

Avatar video는 카탈로그에서 가장 비싼 항목입니다 — 끝나기 전에 음악, 스틸, 비디오를 만들 수 있으므로 — cap을 의도적으로 설정하세요.

Format의 cap은 run이 따로 지정하지 않았을 때 물려받는 값입니다. 현재 값은 PublicFormat.generation_spend_cap_usd_micros에서 읽습니다. 한 번도 지정하지 않은 Format은 플랫폼 기본값 $400이며, 설정 가능한 상한은 $500입니다.

run의 generation_spend_cap_usd는 $500까지 그 run만의 천장을 지정합니다 — Format 자체의 cap보다 큰 값도 적용되고, $500을 넘으면 오류입니다.

cap이 너무 낮으면 비디오 run이 비디오 없이 끝나는 흔한 이유입니다. artifacts[]에 스틸만 있고 비디오가 없으면, 프롬프트를 바꾸기 전에 cap을 올리세요.

5. 폴링한 뒤 결과 읽기

Avatar video run은 깁니다. 촘촘한 루프 대신 백오프로 폴링하거나, communication.webhook_url을 넘겨 Sume가 종료 receipt를 전달하게 하세요.

상태는 queued, processing, completed, failed, canceled, skipped입니다. 가벼운 확인은 status_url을 폴링하세요. 상태 필드와 next_action만 돌아옵니다.

completed receipt는 output, run이 만든 모든 내구성 파일인 artifacts[], 완성된 비디오인 primary_output_url을 담습니다. 미디어 URL은 만료되지 않는 내구성 있는 media.sume.com HTTPS URL입니다.

진행 중인 run 취소:

run이 종료되면 취소는 no-op이며, 어느 쪽이든 현재 receipt가 돌아옵니다.

사람들이 놀라는 두 가지

새 fork는 첫 run 전까지 inactive로 읽힙니다. 방금 만든 사본에 대해 GET /v1/formats/{format_id}는 status: "inactive"와 api_trigger_enabled: false를 보고합니다. 둘 다 지연 프로비저닝되는 runner에서 읽히기 때문입니다. 그 필드가 true가 될 때까지 연동을 막지 마세요 — 첫 POST .../runs가 runner를 프로비저닝하고 run은 정상 진행됩니다. sume/{slug} 자체는 항상 active로 읽힙니다. 카탈로그는 정의상 호출 가능하기 때문입니다.

미리보기 게이트는 API run을 멈추지 않습니다. 채팅에서 이 Format은 미리보기 스틸을 보여 주고 비디오를 만들기 전에 승인을 기다립니다. API에는 사람이 없으므로 run에는 그 승인이 이미 허용되었고 spend cap 안에서 유료 단계까지 계속하라고 알려 줍니다. 정말로 끝낼 수 없는 run — 예를 들어 브리프에 맞는 아바타가 없을 때 — 은 output_error.code가 unattended_blocked인 failed로 돌아오며, 절반만 끝난 completed는 없습니다.

다음