Product promo

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

역할: 제품·브랜드 URL과 짧은 브리프를 넘기면 광고 이미지 또는 프로모 비디오를 돌려줍니다. Format이 분기 — talking-head UGC 또는 product-motion image-to-video — 를 정하고, 지어내지 않고 URL에서 실제 제품 이미지를 가져오며, 호출마다 다시 쓰지 않도록 하우스 스타일을 유지합니다.

이럴 때 쓰세요. 작업은 매번 같고 제품만 바뀔 때입니다. 호출마다 작업 자체가 달라지면 Agent Completions를 쓰세요.

1st-party slug: sume-product-promo.

1. 주소 잡기

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

Format을 바꾸고 싶을 때는 fork가 그대로 있습니다 — Format 라이브러리의 Product promo를 열고 Fork를 누르면 사용자가 소유한 편집 가능한 사본을 받습니다. fork는 본문과 spend cap을 유지하고 새 slug를 받으며(fork는 원본 slug를 재사용할 수 없으므로 대시보드는 sume-product-promo-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입니다.

결정에 해당하는 것은 instruction에, 데이터에 해당하는 것은 input에 두세요.

4. Spend cap

프로모 run은 유료 미디어를 만들므로, 중요한 제어는 cap입니다.

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

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

5. 폴링한 뒤 결과 읽기

상태는 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은 unattended입니다. Format 본문은 채팅용으로 쓰이며, 유료 단계 전에 미리보기 스틸 승인을 위해 사람을 기다리며 멈출 수 있습니다. API에는 사람이 없으므로 run에는 그 승인이 이미 허용되었고 spend cap 안에서 계속하라고 알려 줍니다. 정말로 끝낼 수 없는 run은 output_error.code가 unattended_blocked인 failed로 돌아오며 — 절반만 끝난 completed는 없습니다.

다음