---
title: 라이브 커머스 API
description: mobidoo/live-commerce 호출 — Intro/Mid/Fin 대본, 클립 단위 납품, 스레드로 일부 클립만 다시 받기.
---

`mobidoo/live-commerce`는 모비두가 호스트 주도 라이브 커머스 영상을 만들 때
쓰는 Format입니다. 완성본 **과** 그걸 이루는 **개별 클립**이 함께 돌아옵니다.
클립 하나만 마음에 안 들면 같은 **스레드**를 이어서 그 클립만 다시 요청하면
됩니다 — 처음부터 새 제작을 돌릴 필요가 없습니다.

**필요한 건 상품 URL 하나입니다.** 호스트 이미지, 태그가 붙은 한국어 대본,
가격 정보를 함께 보내면 그쪽이 우선합니다. 아무것도 안 보내면 상품 페이지에서
각각을 도출합니다 — 상품 톤에 맞춰 생성한 호스트, 페이지에서 쓴 대본, 한국어
보이스 프리셋.

**모비두 팀 워크스페이스**에서 발급한 API 키를 쓰세요(개인 키 아님). 개인
키로 `mobidoo/live-commerce`를 호출하면 `403 workspace_key_required`로
실패합니다 —
[팀 Format에는 팀 키가 필요합니다](/formats/call#팀-format에는-팀-키가-필요합니다).

모비두 워크스페이스에 아직 초대되지 않았다면, Slack에서 **허채원 (Chase Huh)**
에게 요청하거나 [chase@sume.com](mailto:chase@sume.com) 으로 초대를 요청하세요.
자세한 내용은 [모비두 문서 홈](/enterprise/mobidoo)의 “워크스페이스 접근 권한”을
보세요.

## 실행 만들기

아래 필드를 채우면 cURL, TypeScript, JavaScript, Python 스니펫이 다시
작성됩니다.

<!-- api-call-example:format-mobidoo-live-commerce -->

호출하면 Format run이 돌아옵니다.
[`status_url` / `result_url`](/formats/runs)을 폴링하거나,
[run 웹훅](/agents/run-webhooks)(`format.run.terminal`)을 받거나,
[`subscribeFormatRun`](/sdk/runs)을 쓰세요. 사용자 트래픽 뒤에 두기 전에
[오류와 요청 한도](/workflows/errors-and-credits)를 먼저 읽어보세요.

## 무엇을 보내나요

| 필드 | 메모 |
| --- | --- |
| `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 → 클립 재시도 사례 하나는
[모범 사례](/enterprise/mobidoo/best-practices)를 보세요.

### 레시피가 알아보는 `input` 키

`input`은 고정 요청 스키마가 아니라 프롬프트에 concat되는 자유 형식 JSON입니다.
백엔드에 편한 형태로 넣으면 됩니다. 전체 규칙:
[Format 호출하기 — 요청 본문](/formats/call#요청-본문),
[구조화 출력](/formats/structured-output).

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`와 같음)입니다. 플랫폼 상세:
[실행 이어가기](/formats/runs).

```text
턴 1  POST …/runs          → arun_A, thread_id=thr_…
      output: full_video + opening[] + middle[] + closing[]

턴 2  POST …/runs
      previous_run_id=arun_A
      “sc_7 클립만 다시”
                           → arun_B, 같은 thread_id=thr_…
      output: 전체 장면 목록 다시 (sc_7만 갱신, 나머지 유지)
```

습관:

- **이어갈 때는 `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·카피만
바꾸면 됩니다):

```json
{
  "instruction": "제공된 Intro/Mid/Fin 대본을 축약하지 말고 그대로 사용. 한국어 쇼호스트, 세로 9:16, 무BGM, 무자막. 카드 표기는 Q9000.",
  "input": {
    "product_url": "https://item.gmarket.co.kr/Item?goodscode=4376824000",
    "host_image_url": "https://media.sume.com/assets/asset_707ef7a4149340d494a12278ef4e95fe/source.png",
    "vo_language": "ko",
    "on_card_name": "삼성 AI Q9000 멀티",
    "price": {
      "list": "2,010,280원",
      "sale": "1,759,000원",
      "discount_label": "12%"
    },
    "script": {
      "segments": [
        {
          "tag": "Intro",
          "text": "안녕하세요, AI 쇼호스트 유라입니다. 오늘은 삼성 AI Q9000 멀티를 짧게 소개해 드릴게요."
        },
        {
          "tag": "Mid",
          "text": "거실용과 침실용 두 대 구성이고, AI 쾌적과 무풍 냉방을 지원합니다. 정상가 이백일만 이백팔십원에서 지금 백칠십오만 구천원, 십이 퍼센트 할인입니다."
        },
        {
          "tag": "Fin",
          "text": "전국 기본 설치가 포함되어 있어요. 삼성 AI Q9000, 화면에서 확인해 보세요. 감사합니다."
        }
      ]
    }
  },
  "output_schema": { "...": "mobidoo/live-commerce/v1 — 모범 사례 참고" },
  "primary_output_key": "full_video",
  "generation_spend_cap_usd": 45
}
```

Q9000으로 채운 호출, 그때 돌아오는 receipt, 클립 재시도 턴은
[모범 사례](/enterprise/mobidoo/best-practices)에 있습니다.

## 원하는 클립만 다시 받기

대시보드의 “이 클립 다시 만들기”용: create `run.id`와 receipt의 각
`scene.id`를 저장해 두고, 고정 instruction + 선택한 id로 스레드를 이어가세요.
같은 대본으로 새 run을 처음부터 열면 **새 제작**(새 id, 전체 비용)이 됩니다.

`stand-in` 복구가 아니라 운영자가 테이크를 거절한 경우라면, 그 피드백을
`instruction`에 실어 보내세요 — 어느 씬인지, 무엇이 잘못됐는지, 어떻게 바꿔야
하는지.
[씬별 구체 피드백을 넣으세요](/enterprise/mobidoo/best-practices#씬별-구체-피드백을-넣으세요)를
보세요.

### 예시 — Mid talk 클립 하나

```json
{
  "previous_run_id": "arun_42ed6a48b3d44092",
  "instruction": "Retry the selected scene only. Keep every other scene and the VO spine unchanged. Do not change the script.",
  "input": {
    "scene_id": "sc_7"
  },
  "output_schema": { "...": "턴 1과 동일" },
  "primary_output_key": "full_video",
  "generation_spend_cap_usd": 8
}
```

### 예시 — stand-in / failed 클립 두 개

```json
{
  "previous_run_id": "arun_42ed6a48b3d44092",
  "instruction": "Retry the selected scenes only. Keep every other scene and the VO spine unchanged.",
  "input": {
    "scene_ids": ["sc_7", "sc_9"]
  },
  "output_schema": { "...": "턴 1과 동일" },
  "primary_output_key": "full_video",
  "generation_spend_cap_usd": 12
}
```

두 body 어디에도 `thread_id`는 없습니다. 대화를 잇는 계약은 `previous_run_id`
하나가 전부입니다.

receipt는 다시 **전체** `opening` / `middle` / `closing` 목록입니다 — 변경분도
패치도 아닙니다. 다시 만든 장면만 새 미디어 URL이고, 나머지는 이전 턴 URL을
유지합니다. 두 run의 `thread_id`는 같고, `full_video`도 새 URL로 다시
조립됩니다.

[모범 사례](/enterprise/mobidoo/best-practices)의 프로덕션 실행 쌍에서 측정한
결과 — 씬 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 웹훅](/agents/run-webhooks).

## 웹훅은 두 계층입니다

| 계층 | 단위 | 발송 시점 |
| --- | --- | --- |
| 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`는 같습니다. |

플랫폼 계약: [실행 이어가기](/formats/runs).

## 공유용 링크

Slack / 메일용.

| 주제 | 링크 |
| --- | --- |
| 웹훅 FAQ (A vs B) | https://docs.sume.com/ko-KR/enterprise/mobidoo/live-commerce#파트너-faq-웹훅 |
| 씬 재생성 FAQ | https://docs.sume.com/ko-KR/enterprise/mobidoo/live-commerce#파트너-faq-씬-재생성 |
| 스레드 / 이어가기 | https://docs.sume.com/ko-KR/enterprise/mobidoo/live-commerce#스레드-같은-제작물을-이어서 |
| 클립 재시도 레시피 | https://docs.sume.com/ko-KR/enterprise/mobidoo/live-commerce#원하는-클립만-다시-받기 |
| 모범 사례 + 예시 | https://docs.sume.com/ko-KR/enterprise/mobidoo/best-practices |
| EN: webhook FAQ | https://docs.sume.com/enterprise/mobidoo/live-commerce#partner-faq-webhooks |
| EN: scene regen FAQ | https://docs.sume.com/enterprise/mobidoo/live-commerce#partner-faq-scene-regeneration |

## 다음

- [모범 사례](/enterprise/mobidoo/best-practices) — create curl, receipt,
  clip-retry curl.
- [실행 이어가기](/formats/runs) — 플랫폼 스레드 계약.
- [구조화 출력](/formats/structured-output) — 스키마 규칙.
- [빠른 시작](/quick-start) — 처음부터 끝까지 첫 생성.