AI 제품 광고 영상 생성 API: Format 또는 직접 만들기

Sume API로 AI 제품 광고 영상을 만들려면 제품 팩샷을 첨부해 POST /v1/formats/sume/{slug}/runs로 두 카탈로그 Format sume-product-commercial과 sume-cinematic-studio-commercial 중 하나를 실행하세요. 모델, 길이, 해상도, 사운드를 직접 고르려면 팩샷을 첫 프레임으로 지정해 POST /v1/videos에서 클립을 생성하세요.

아래 내용은 2026-09-27에 확인한 Sume 문서 Format 카탈로그 (영문), Format 호출하기 (영문), 영상 생성 (영문) 페이지에서 가져왔습니다. 각 Format은 그 Format 자체의 description, 즉 카탈로그가 저장하는 SKILL.md frontmatter에서 인용했습니다. 카탈로그 전체는 바로 쓰는 제품 영상 Format에서 다룹니다.

제품 광고에는 어떤 카탈로그 Format이 맞나요?

둘 다 영상 Format이며, 두 설명 모두 “Not for: static campaign deliverables.”(정적인 캠페인 결과물용 아님)로 끝납니다. 이 문구는 각 Format이 명시한 목표일 뿐, 개별 영상에 대한 약속이 아닙니다. GET /v1/formats/sume/{slug}는 설명을 반환하고, 레시피 본문은 호출자가 아니라 에이전트에게 전달됩니다.

광고 Format은 어떻게 호출하나요?

formats:write가 있는 API 키라면 어떤 키로든 카탈로그 Format을 호출할 수 있으며, 실행과 그 미디어, 지출은 호출한 키에 귀속됩니다. 팩샷은 공개 HTTPS image_url을 담은 input_image로 첨부하세요. Sume는 실행을 만들 때 이미지를 가져오며, JPEG, PNG, WebP, GIF, AVIF를 장당 최대 30 MB, 실행당 최대 30장까지 받습니다.

브리프는 instruction에 넣으세요. instruction은 Format 본문 뒤에 조합되며, 둘이 어긋나면 instruction이 우선합니다. 영상 모델, 길이, 해상도를 정하는 필드는 없습니다. model은 실행을 오케스트레이션하는 LLM만 고르고, 이미지·영상·오디오 모델은 Format의 도구가 고르며, 알 수 없는 최상위 필드는 400 unknown_parameter가 됩니다.

curl -sS -X POST "https://api.sume.com/v1/formats/sume/sume-cinematic-studio-commercial/runs" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-headphones-cinematic-v1" \
  -d '{
    "instruction": "16:9 launch film for the attached headphones.",
    "attachments": [
      { "type": "input_image", "image_url": "https://example.com/headphones.png" }
    ],
    "generation_spend_cap_usd": 30,
    "communication": { "webhook_url": "https://example.com/hooks/sume" }
  }'

광고 클립을 직접 생성하려면 어떻게 하나요?

모델과 그 설정을 직접 정하고 싶다면 POST /v1/videos를 호출하세요. 팩샷을 frame_type: "first_frame"과 함께 frame_images에 넣으면 클립의 첫 프레임이 됩니다. input_references는 정확한 프레임이 아니라 시각적 가이드이며, 둘을 함께 보내면 frame_images가 우선합니다. 이 차이가 라벨에 왜 중요한지는 Image-to-Video 제품 로고 왜곡에서 다룹니다.

아래 요청은 문서의 이미지로 영상 만들기 예제를 고친 것입니다. 문서의 seedance-2 항목에는 4–15초 길이, 1080p, 16:9, generate_audio: true가 나와 있습니다.

• 호출은 Job id와 polling_url을 담아 202를 반환합니다. status가 completed가 될 때까지 폴링한 뒤, API 키를 사용해 unsigned_urls[0]에서 내려받으세요.

curl -X POST https://api.sume.com/v1/videos \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-headphones-clip-v1" \
  -d '{
    "model": "seedance-2",
    "prompt": "Slow push-in on the headphones on a dark studio table, soft rim light",
    "frame_images": [
      {
        "type": "image_url",
        "image_url": { "url": "https://example.com/headphones.png" },
        "frame_type": "first_frame"
      }
    ],
    "duration": 12,
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "generate_audio": true
  }'

길이, 해상도, 사운드는 무엇을 고를 수 있나요?

한도는 모델마다 다르므로, 제출하기 전에 GET /v1/videos/models에서 supported_durations, supported_resolutions, supported_aspect_ratios, generate_audio를 확인하세요. 클립 아래에 배경 음악을 믹싱하는 방법은 API로 영상에 배경 음악 넣기에서 다룹니다.

경로별 비용은 얼마인가요?

Format 경로에서는 실행 상한에 잡히는 생성이 API 요금의 요율로 계량됩니다. 상한은 generation_spend_cap_usd가 정합니다. 최대 $500이며, null은 $500으로 실행되고, 0은 거부되며, 생략하면 Format 자체의 상한을 물려받습니다. 영수증의 usage.billable_amount_usd_micros는 에이전트 자체의 LLM 턴을 제외하므로 실행의 총비용이 아닙니다.

직접 생성하는 경로에서는 모든 모델에서 영상 Job이 제출 시 워크스페이스 USD 잔액에서 공급사 정가 × 1.25로 예약되고, 기본 5.5% 에이전트 수수료가 더해집니다. 모델별 요율은 GET /v1/videos/models의 pricing_skus에 있습니다.

경로마다 어떤 제한이 있나요?

어느 경로도 결과물이 어떻게 보일지는 보장하지 않습니다.

• Format의 설명은 그 Format이 명시한 목표입니다. 레시피는 비공개로 유지되며, Format 실행 안에서 영상 모델을 고정할 수는 없습니다.
• API 실행은 무인 실행입니다. 채팅용 레시피라면 기다렸을 승인은 이미 부여된 것으로 처리되며, 끝낼 수 없는 실행은 failed로 돌아올 뿐 절반만 끝난 completed로 돌아오지 않습니다.
• POST /v1/videos에서는 모든 v1 모델이 supported_sizes: null을 보고하므로, size를 보내면 400 unsupported_parameter가 반환됩니다. 대신 resolution과 aspect_ratio를 보내세요.