라이브 커머스 API
이 문서는 영문 원고를 AI로 번역한 내용이라 표현이 어색할 수 있습니다.
mobidoo/live-commerce는 모비두가 호스트 주도 라이브 커머스 영상을 만들 때
쓰는 Format입니다. 완성본 과 그걸 이루는 개별 클립이 함께 돌아옵니다.
클립 하나만 마음에 안 들면 같은 스레드를 이어서 그 클립만 다시 요청하면
됩니다 — 처음부터 새 제작을 돌릴 필요가 없습니다.
필요한 건 상품 URL 하나입니다. 호스트 이미지, 태그가 붙은 한국어 대본, 가격 정보를 함께 보내면 그쪽이 우선합니다. 아무것도 안 보내면 상품 페이지에서 각각을 도출합니다 — 상품 톤에 맞춰 생성한 호스트, 페이지에서 쓴 대본, 한국어 보이스 프리셋.
모비두 팀 워크스페이스에서 발급한 API 키를 쓰세요(개인 키 아님). 개인
키로 mobidoo/live-commerce를 호출하면 403 workspace_key_required로
실패합니다 —
팀 Format에는 팀 키가 필요합니다.
모비두 워크스페이스에 아직 초대되지 않았다면, Slack에서 허채원 (Chase Huh) 에게 요청하거나 chase@sume.com 으로 초대를 요청하세요. 자세한 내용은 모비두 문서 홈의 “워크스페이스 접근 권한”을 보세요.
실행 만들기
아래 필드를 채우면 cURL, TypeScript, JavaScript, Python 스니펫이 다시 작성됩니다.
Run the live-commerce Format
POST /v1/formats/{handle}/{slug}/runs
Required
호출하면 Format run이 돌아옵니다.
status_url / result_url을 폴링하거나,
run 웹훅(format.run.terminal)을 받거나,
subscribeFormatRun을 쓰세요. 사용자 트래픽 뒤에 두기 전에
오류와 요청 한도를 먼저 읽어보세요.
무엇을 보내나요
| 필드 | 메모 |
|---|---|
instruction | 짧은 산문: 톤, “Intro/Mid/Fin 대본 그대로”, 무BGM·무자막, 세로 9:16. |
input | 구조화된 호출 데이터 — 상품, 호스트, 가격, 태그 대본. |
output_schema | mobidoo/live-commerce/v1을 묶어 receipt를 수집용으로 타입화. |
primary_output_key | "full_video" — 조립된 완성본이 주 미디어 필드. |
generation_spend_cap_usd | 실행당 생성 지출 상한(Format 자체 상한으로 clamp). |
별도의 “JSON 모드”는 없습니다. instruction은 방향, input은 데이터입니다.
LLM 턴과 같은 모양입니다. create → receipt → 클립 재시도 사례 하나는
모범 사례를 보세요.
input
input은 고정 요청 스키마가 아니라 프롬프트에 concat되는 자유 형식 JSON입니다.
백엔드에 편한 형태로 넣으면 됩니다. 전체 규칙:
Format 호출하기 — 요청 본문,
구조화 출력.
HTTP가 아래 키를 강제하지는 않습니다. 여분 키는 데이터로 같이 타고, 빠진 키는 오류가 아닙니다.
| 키 | 효과 |
|---|---|
product_url | 사양·카피·상품 사진을 크롤링할 페이지. 사실상 유일한 필수 필드. |
host_image_url | 쇼호스트로 쓸 인물(모든 talk 컷의 아이덴티티). 별칭: avatar_image_url. 없으면 상품 톤에 맞춰 호스트를 생성합니다. |
script.segments | 적은 수의 긴 태그 블록 — 보통 Intro / Mid / Fin. 컷마다 수십 개로 미리 쪼개지 마세요. 없으면 페이지에서 대본을 씁니다. |
vo_language | 음성 언어. 기본값은 한국어. |
on_card_name | 화면 카드에 허용되는 상품명 표기. |
price | 카드에 정가·판매가·할인 표기가 필요할 때. |
banner_reference_image_urls | 화면 카드 레이아웃 레퍼런스(media.sume.com URL). |
variants_per_n | 카드당 후보 이미지 수. 기본값 1. |
완성 영상 길이는 음성 트랙과 같습니다. 길이를 바꾸려면 대본을 바꾸세요. 재생 시간 파라미터는 없습니다.
대본 태그 → 클립 배열
| 보내는 태그 | receipt 배열 |
|---|---|
Intro | opening[] |
Mid (또는 Mid · …) | middle[] |
Fin | closing[] |
구간은 3–5개 정도의 긴 블록으로 보내세요. Format이 컷을 정합니다. ~45개로
미리 쪼개면 input 크기 예산만 잡아먹고 편집도 나빠집니다. 아래
크기 한계를 보세요.
스레드: 같은 제작물을 이어서
Format run은 에이전트 턴 1회입니다. 첫 성공 run이 대화를 시작합니다. receipt에는 다음이 실립니다:
| 필드 | 의미 |
|---|---|
id | 이 턴의 run id (arun_…). 폴링·웹훅 대상. |
thread_id | 제작물 전체의 대화 id. 응답 전용 — 요청 body에 넣으면 unknown_parameter로 거절됩니다. |
previous_run_id | 이전 run을 이은 턴이면 그 id, 아니면 null. |
수정할 때는 같은 Format에 새 run을 만들고, 끝난 턴의 id를
previous_run_id로 넘깁니다. 파트너 입장에서는 “같은 스레드에 메시지 하나
더”(LLM의 previous_response_id와 같음)입니다. 플랫폼 상세:
실행 이어가기.
습관:
- 이어갈 때는
previous_run_id만.thread_id를 보내지 마세요. body에 실으면unknown_parameter로 거절됩니다 — 두 턴 모두에서 응답 필드일 뿐, 입력이 아닙니다. - 이어 호출은 새 run — 새 id, 자체 지출, terminal 웹훅 1회. 이전 run은
영원히
completed. - 매 턴 같은
output_schema. 바인딩은 run 단위이며 상속되지 않습니다. - 자체 DB에서는 공유
thread_id로 턴을 묶으세요.
원하는 클립 형태로 받기
파트너 스키마(mobidoo/live-commerce/v1)를 묶으면 다음이 옵니다:
full_video— 조립된 세로 완성본opening[]/middle[]/closing[]— 장면마다 자기 파일 (scene.video), 안정적인scene.id
완성본을 그대로 쓰거나, 개별 클립만 골라 자체 편집·QA에 넣을 수 있습니다. 장면 id는 그 제작물이 살아있는 동안 고정입니다. 배열 위치가 아니라 id를 저장하세요.
scene.id는 불투명한 문자열로 다루세요. 지금 제작물은 sc_0, sc_1, …
을 돌려주지만 이전 제작물은 다른 모양을 돌려줬습니다. 패턴으로 검증하거나
직접 만들어 쓰면 깨집니다. receipt가 주는 scene.id를 그대로 저장하고 재시도
때 그대로 돌려보내세요.
현실적인 첫 턴 본문 예시(삼성 Q9000 짧은 샘플 — 카탈로그에 맞게 URL·카피만 바꾸면 됩니다):
Q9000으로 채운 호출, 그때 돌아오는 receipt, 클립 재시도 턴은 모범 사례에 있습니다.
원하는 클립만 다시 받기
대시보드의 “이 클립 다시 만들기”용: create run.id와 receipt의 각
scene.id를 저장해 두고, 고정 instruction + 선택한 id로 스레드를 이어가세요.
같은 대본으로 새 run을 처음부터 열면 새 제작(새 id, 전체 비용)이 됩니다.
stand-in 복구가 아니라 운영자가 테이크를 거절한 경우라면, 그 피드백을
instruction에 실어 보내세요 — 어느 씬인지, 무엇이 잘못됐는지, 어떻게 바꿔야
하는지.
씬별 구체 피드백을 넣으세요를
보세요.
예시 — Mid talk 클립 하나
예시 — stand-in / failed 클립 두 개
두 body 어디에도 thread_id는 없습니다. 대화를 잇는 계약은 previous_run_id
하나가 전부입니다.
receipt는 다시 전체 opening / middle / closing 목록입니다 — 변경분도
패치도 아닙니다. 다시 만든 장면만 새 미디어 URL이고, 나머지는 이전 턴 URL을
유지합니다. 두 run의 thread_id는 같고, full_video도 새 URL로 다시
조립됩니다.
모범 사례의 프로덕션 실행 쌍에서 측정한
결과 — 씬 11개 컷에서 sc_7 하나만 재시도: 11개 행 전부 반환, 11개 중
10개의 나머지 URL이 바이트 단위로 동일, sc_7만 이동, full_video는 같은
73.360초로 재조립. 재시도 뒤에도 그 장면의 이전 URL은 200으로 열리므로 이미
저장해 둔 create receipt는 계속 유효하고, 두 테이크를 모두 보관할 수 있습니다.
클립 재시도로 바꿀 수 있는 것과 없는 것
| 요청 | 결과 |
|---|---|
| 지정한 장면의 다른 테이크·프레이밍·조명·B-roll | ✅ 해당 클립 재렌더 + 재조립 |
stand-in / failed 장면을 최종본으로 | ✅ 동일 |
| 대사·가격 멘트·길이 변경 | ❌ 새 전체 제작 (VO 스파인이 움직임) |
| 호스트·대본·상품 변경 | ❌ 새 전체 제작 |
기준은 음성 트랙입니다. 보이는 방식 → 클립 재시도. 말하는 내용 → 새 제작과 새 장면 id.
재시도는 재인코딩이 아니라 새 생성입니다. 프레임 안의 생성물은 전부 다시 굴러갑니다. 측정한 사례에서 구조화된 오버레이 사실(가격, 할인 표기, 스펙 배지, 구성)은 정확히 유지됐지만, 생성된 제품 아트 안에 렌더링된 장식용 문구는 테이크 사이에 표현이 바뀌었습니다. 운영자에게는 “한 군데만 고쳐진 같은 프레임”이 아니라 다른 테이크를 받는다고 안내하세요.
재시도 비용 잡기
스크립트·VO·호스트 스틸·다른 클립을 재사용할 때, 클립 하나 재시도는 create
실행의 대략 20분의 1로 잡으세요. 프로덕션 측정값: create $14.959638에
대해 재시도 $0.742530 — 씬 11개 컷의 under_banner 장면 하나, 소요 2분 53초.
보장이 아니라 예산 가이드입니다. 짧은 제작물은 고정 비용을 더 적은 클립에
나누므로, 이전의 씬 8개 컷은 5분의 1에 가까웠습니다. 대시보드 예산은 자체 초기
실행에서 산정하고, 재시도마다 generation_spend_cap_usd를 계속 거세요.
크기: 한계가 두 개고, 알려주는 쪽은 하나뿐입니다
방송 대본을 통째로 보내기 전에 알아야 할 규칙입니다.
input은 8,192 UTF-8 바이트를 넘으면 거절됩니다(최상위 속성 64개 초과도 마찬가지) → 즉시400.- 그다음 각 필드는 실행에 실릴 때 약 4,000자에서 앞부분만 남기고 잘립니다 → 오류 없음. 뒷부분이 그냥 없습니다.
즉 6분 이하 대본은 통째로 도착합니다. 13분을 넘기면 깔끔한 400. 그 사이는
호출은 성공하는데 대본 끝이 실행에 안 닿을 수 있습니다.
5–15분 방송이면 1–3분 상품 블록마다 한 번씩 호출하고 쪽에서 병합한 뒤, 약한 블록의 스레드만 재시도하세요.
input은 JSON 객체여야 하고(문자열 JSON은 400), attachments는 이미지만
(최대 30장) 받으므로 대본을 파일로 보낼 수는 없습니다.
파트너 FAQ: 웹훅
연동 시 자주 묻는 질문:
| 질문 | Formats API 답 |
|---|---|
| (A) 씬 영상이 완성될 때마다 씬 단위 webhook이 오는가? | Format run webhook 기준으로는 아니오. Formats response가 씬마다 쪼개져 오지 않습니다. |
| (B) 모든 씬 생성이 끝난 뒤 한 번에 webhook이 오는가? | 예. 에이전트 턴이 완료될 때 최종 구조화 receipt와 format.run.terminal 웹훅이 1회 옵니다. |
Formats는 AI Agent를 호출합니다. 아래층 tool(TTS·클립 렌더·조립)은 서로 다른 시각에 끝날 수 있지만, 파트너 계약은 턴 단위 최종입니다. 씬 재생성 이어 호출은 새 run이며, 그 run에 대해 terminal 웹훅이 다시 1회 갑니다.
job 계층의 per-job 이벤트는 내부 진행용이며, 공개된 파트너 씬 webhook은 아직 아닙니다 — 필요하면 문의하세요.
더 보기: Run 웹훅.
웹훅은 두 계층입니다
| 계층 | 단위 | 발송 시점 |
|---|---|---|
| Format run | 에이전트 턴 1회 | 턴이 끝날 때 format.run.terminal 1회 |
| 생성 job | 미디어 job 1개 | 각 job이 끝날 때마다 |
연동의 기준은 Format 계층입니다. 클립 재시도도 새 run id로 terminal 웹훅을 정확히 1회만 보냅니다.
파트너 FAQ: 씬 재생성
| 질문 | 답 |
|---|---|
| 완성된 제작물에서 특정 씬만 재생성할 수 있는가? | 예 — 같은 스레드를 previous_run_id로 이어 장면 id를 지목합니다. 원하는 클립만 다시 받기를 보세요. |
| 전체 영상을 다시 돌려야 하는가? | 대사·호스트·상품·VO 스파인이 바뀔 때만. 보이는 방식만 고치면 클립 재시도. |
| 대화를 어떻게 이어가는가? | previous_run_id를 보냅니다(thread_id는 보내지 않음). 두 run의 receipt thread_id는 같습니다. |
플랫폼 계약: 실행 이어가기.
공유용 링크
Slack / 메일용.