Sume Format으로 제품에 AI 영상 생성을 임베드하는 방법

제품에 AI 영상 생성을 임베드하려면 UI에 자체 서버를 호출하는 버튼을 두고, 그 서버가 클릭한 고객을 위해 POST /v1/formats/{handle}/{slug}/runs로 Sume Format을 실행하게 하세요. 고객은 Sume와 직접 통신하지 않습니다. 서버가 Sume API 키 하나를 보관하고, 고객을 대신해 Format을 실행하며, 결과를 자체 레코드에 다시 매핑합니다.

이 가이드는 Sume의 제품에 Format 임베드하기 (영문) 쿡북을 따르며, 세부 내용은 Format 호출하기 (영문)와 TypeScript SDK 페이지에서 가져왔습니다. 모두 2026-09-25에 확인했습니다.

Sume API 키는 어디에 두어야 하나요?

서버에만 두세요. Sume에는 최종 사용자별 자격 증명도, 브라우저에 안전한 키도 없으며, 키는 여러분의 크레딧을 씁니다. 키를 가진 사람은 누구나 여러분이 소유한 어떤 Format이든 여러분의 상한까지 실행할 수 있습니다. 쿡북의 키 보관 (영문) 규칙은 다음과 같습니다.

• 키는 서버 환경에 두고, 클라이언트 JavaScript, 모바일 번들, NEXT_PUBLIC_* 변수에는 절대 두지 마세요.
• 키가 아니라 호출을 프록시하세요. 엔드포인트는 고객의 식별자를 받아 Sume 요청을 직접 구성합니다.
• 자체 인가 검사를 추가하세요. Sume가 인증하는 것은 고객이 아니라 여러분입니다.
• API 키에서 formats:read와 formats:write 스코프로 키를 만드세요. 스코프는 나중에 추가할 수 없으며, 서비스 계정 키로는 Format 실행을 만들 수 없습니다.
• 팀 Format에는 그 팀 워크스페이스에서 만든 키가 필요합니다. 개인 키로 호출하면 403 workspace_key_required를 받습니다.

고객 한 명을 위한 실행은 어떻게 시작하나요?

공식 TypeScript SDK인 @sume-com/sdk(0.2.0+)를 쓰거나, 평범한 HTTP POST를 한 번 보내세요. SDK에 필요한 것은 fetch와 WebCrypto뿐이어서 Node 18+, Bun, Deno, Cloudflare Workers에서 동작합니다. subscribeFormatRun은 한 번의 호출로 실행을 만들고 종료 영수증까지 기다립니다. 스트리밍이 아니라 폴링 방식이며, 기본 타임아웃은 20분입니다.

클라이언트는 x-api-key만 보냅니다. Authorization 헤더를 함께 추가하지 마세요. 두 자격 증명을 함께 실은 요청은 401 unauthorized로 실패합니다.

import { createSumeClient, subscribeFormatRun } from "@sume-com/sdk";

const client = createSumeClient({ apiKey: process.env.SUME_API_KEY! });

const run = await subscribeFormatRun({
  client,
  path: { handle: "acme", slug: "product-promo" },
  idempotencyKey: runKey(customer, order),
  body: {
    input: { product_url: order.productUrl },
    generation_spend_cap_usd: spendCapForPlan(customer.plan),
  },
});

if (run.status === "completed") await attachOutputs(order.id, run);

더블클릭으로 유료 실행이 두 번 시작되는 것은 어떻게 막나요?

Idempotency-Key는 요청한 시점이 아니라 만들고 있는 대상에서 유도하세요. 테넌트 ID, 주문 ID, Format slug, 그리고 의도적으로 다시 실행하고 싶을 때 올리는 버전을 해시하면 됩니다. 요청마다 uuidv4()를 쓰면 헤더는 장식에 불과해지고, 주문 ID만으로 만든 키는 ID가 겹치는 두 테넌트가 실행 하나를 공유하게 만듭니다. 브라우저에 응답하기 전에 반환된 실행 ID를 저장하세요. 자세한 내용은 AI 영상 API 멱등성 키에 있습니다.

고객 한 명의 실행이 쓸 수 있는 비용은 어떻게 제한하나요?

요청마다 generation_spend_cap_usd를 설정하세요. 예를 들어 고객의 요금제 등급에 따라 값을 정할 수 있습니다. 값은 플랫폼 최대치인 $500까지 가능합니다. Format 자체 상한보다 큰 값도 그대로 적용되고, $500을 넘으면 400이며, 생략하면 Format의 상한을 물려받습니다. Format 상한의 기본값은 $400입니다.

영수증은 그 상한에 대비한 지출을 usage.billable_amount_usd_micros로 보고합니다. 이 값은 에이전트 자체의 LLM 턴을 제외하므로 실행의 총비용도, 청구서도 아닙니다. 고객 청구는 자체 기록을 기준으로 하고 GET /v1/usage와 대조하세요. 자세한 내용은 무인 AI 에이전트 지출 상한에 있습니다.

서버는 완성된 영상을 어떻게 받나요?

communication.webhook_url을 등록하면 Sume가 서명된 종료 영수증을 그 URL로 POST합니다. 엔드포인트가 다운되는 날에 대비해 status_url 폴링이나 subscribeFormatRun을 백업으로 계속 연결해 두세요.

• 파싱하기 전에 원본 본문으로 sume-v1 서명(<timestamp>.<raw_body>에 대한 HMAC-SHA256)을 검증하세요. SDK의 verifyWebhook이 이 일을 합니다.
• 2xx를 빠르게 반환한 뒤 작업하세요. 전달 시도 예산은 10초입니다.
• request_id로 중복을 제거하세요. 재시도에도 같은 값이 반복됩니다.
• 1 MiB를 넘는 영수증은 payload: null로 도착하니, 대신 error.result_url에서 가져오세요.
• 최종 HTTPS URL을 등록하세요. 리다이렉트는 따라가지 않으므로 3xx는 전달이 아닙니다.

무엇을 저장하고 보여 줘야 하나요?

완료된 영수증에는 primary_output_url(보여 줄 하나), artifacts[](id, type, url, content_type, size_bytes, width, height, duration_ms, checksum_sha256를 담은 모든 생성 파일), 그리고 구조화된 결과인 output이 있습니다. 모든 URL은 만료되지 않는 내구성 있는 media.sume.com HTTPS URL이므로 레코드에 저장해 둘 수 있습니다.

쿡북의 artifact 섹션 (영문)이 경고하듯, 내구성 있는 URL은 공개 URL이기도 합니다. 고객 A가 고객 B의 결과물을 절대 보면 안 된다면, 자체 인증 라우트로 바이트를 프록시하거나 웹훅이 도착할 때 자체 스토리지로 복사하세요.

UI에서는 어떤 실패를 구분해야 하나요?

• 제출 시: 4xx는 아무것도 실행되지 않았고 아무것도 청구되지 않았다는 뜻입니다. 키나 호출을 고치세요. 403 insufficient_scope를 끝없이 재시도하는 것은 흔하면서도 비싼 실수입니다.
• 실행 시: status가 failed입니다. unattended_blocked는 사람 없이는 넘을 수 없는 게이트에 실행이 걸렸다는 뜻이고, format_run_failed는 일반 실패입니다. 새 멱등성 키로 재시도하세요.
• 종료됐지만 실패는 아님: canceled와 skipped 실행은 웹훅을 절대 전달하지 않습니다.
• 전달 시: 실행은 문제없고 엔드포인트에 문제가 있었던 경우입니다. result_url에서 영수증을 가져오세요.