---
title: Product promo
description: Formats by Sume의 Product promo Format을 백엔드에서 호출해, 제품 URL을 고정된 하우스 스타일의 광고 이미지 또는 프로모 비디오로 바꾸세요.
---

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

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

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

## 1. 주소 잡기

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

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

## 2. 스코프

| Scope | Needed for |
|---|---|
| `formats:read` | Format 읽기, run 읽기·목록입니다. |
| `formats:write` | run 시작, run 취소입니다. |

Formats가 출시되기 전에 만든 키에는 이 스코프가 없고, 기존 키에 스코프를 추가할 수
없습니다 — [API Keys](https://www.sume.com/dashboard/api-keys)에서 새 키를 만들고
교체하세요. 서비스 계정 키로는 Format run을 시작할 수 없습니다.

## 3. 호출하기

```bash
export SUME_API_KEY="sume_live_..."

curl -sS -X POST "https://api.sume.com/v1/formats/sume/sume-product-promo/runs" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "instruction": "Make three square ad images for this product, benefit-led copy, no faces.",
    "input": {
      "product_url": "https://example.com/products/trail-runner",
      "brand": "Northbound",
      "aspect_ratio": "1:1",
      "count": 3
    },
    "generation_spend_cap_usd": 20
  }'
```

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

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

```json
{
  "data": {
    "id": "run_...",
    "object": "format.run",
    "format": { "id": "skl_...", "slug": "sume-product-promo", "version": 1 },
    "status": "queued",
    "status_url": "https://api.sume.com/v1/format-runs/run_.../status",
    "result_url": "https://api.sume.com/v1/format-runs/run_.../result",
    "created_at": "2026-08-02T09:00:00.000Z"
  }
}
```

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

### `input`에 대해

`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. 폴링한 뒤 결과 읽기

```bash
curl -sS "https://api.sume.com/v1/format-runs/$RUN_ID" \
  -H "Authorization: Bearer $SUME_API_KEY"
```

상태는 `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 취소:

```bash
curl -sS -X POST "https://api.sume.com/v1/format-runs/$RUN_ID/cancel" \
  -H "Authorization: Bearer $SUME_API_KEY"
```

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`는 없습니다.

## 다음

- [Format 호출하기](/formats/call) — 전체 invoke 계약과 모든 오류 코드
- [실행과 결과](/formats/runs) — receipt, 버전, 취소
- [구조화 출력](/formats/structured-output) — 스키마를 바인딩하고 typed JSON을 받기
- [Avatar UGC video](/formats/avatar-ugc) — 이 Format의 talking-head 대응
- [OpenAPI](https://api.sume.com/reference) — 정확한 요청·응답 스키마