AI product commercial video generator API: Formats or DIY

To generate an AI product commercial with the Sume API, run one of two catalog Formats, sume-product-commercial or sume-cinematic-studio-commercial, at POST /v1/formats/sume/{slug}/runs with your packshot attached. To pick the model, length, resolution, and sound yourself, generate the clip on POST /v1/videos with the packshot as its first frame.

The facts below come from Sume's Format catalog, Create a run, and Video generation docs, read on 2026-09-27. Each Format is quoted from its own description, the SKILL.md frontmatter the catalog stores. The whole catalog is covered in Ready-made Formats for product video.

Which catalog Format fits a product commercial?

Both are video Formats: each description ends “Not for: static campaign deliverables.” The wording is each Format's stated aim, not a promise about any one video. GET /v1/formats/sume/{slug} returns the description; the recipe body reaches the agent, not the caller.

How do I call a commercial Format?

Any API key with formats:write can call a catalog Format; the run, its media, and its spend belong to the calling key. Attach the packshot as an input_image with a public HTTPS image_url. Sume fetches it when you create the run and accepts JPEG, PNG, WebP, GIF, or AVIF, up to 30 MB each and 30 images per run.

The brief goes in instruction, which is composed after the Format body and wins where they disagree. There is no field for the video model, length, or resolution: model selects only the LLM that orchestrates the run, the Format's tools choose the image, video, and audio models, and an unknown top-level field is 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" }
  }'

How do I generate the commercial clip myself?

Call POST /v1/videos when you want to set the model and its settings. Put the packshot in frame_images with frame_type: "first_frame" to make it the clip's first frame; input_references are visual guidance rather than exact frames, and when both are sent, frame_images takes precedence. Why that matters for a label is covered in Product logo warping in image-to-video.

This request adapts the docs' image-to-video example. The docs' seedance-2 record lists 4–15 second durations, 1080p, 16:9, and generate_audio: true:

• The call returns 202 with a job id and a polling_url. Poll until status is completed, then download from unsigned_urls[0] with your API key.

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
  }'

Which length, resolution, and sound can I choose?

Limits are per model, so read supported_durations, supported_resolutions, supported_aspect_ratios, and generate_audio on GET /v1/videos/models before you submit. Mixing a music bed under a clip is covered in Add background music to a video.

What does each path cost?

On the Format path, generation that counts against the run's cap is metered at the rates on API pricing. generation_spend_cap_usd sets the ceiling: up to $500, null runs at $500, 0 is rejected, and omitting it inherits the Format's own cap. The receipt's usage.billable_amount_usd_micros excludes the agent's own LLM turn, so it is not the run's total cost.

On the direct path, a video job is reserved from the workspace USD balance on submit at the provider's list price × 1.25 on every model, plus a 5.5% agent fee by default. Each model's rates are the pricing_skus on GET /v1/videos/models.

What are the limits of each path?

Neither path guarantees how the result looks:

• A Format's description is its stated aim. Its recipe stays private, and you cannot pin the video model inside a Format run.
• An API run is unattended: approvals a chat recipe would wait for are treated as granted, and a run that cannot finish comes back failed, never a half-finished completed.
• On POST /v1/videos, every v1 model reports supported_sizes: null, so size returns 400 unsupported_parameter. Send resolution and aspect_ratio instead.