Product photo to video API: e-commerce clips from SKU photos

To turn a product photo into a video with the Sume API, call the catalog Format that fits the product, such as sume-product-commercial for an e-commerce hero clip, at POST /v1/formats/sume/{slug}/runs with the photo in attachments. To write the motion yourself, send the photo as the first_frame of a POST /v1/videos request.

Facts come from the Format catalog, Format API, Create a run, Video generation, and Video Router docs pages and each Format's published description, read on 2026-09-27. The catalog itself is introduced in Ready-made Formats for product video.

Which Format fits which product?

These five catalog video Formats name a product or e-commerce job in their descriptions, and each description ends “Not for: static campaign deliverables”. GET /v1/formats/sume/{slug} returns a Format's full description before you call it. sume-virtual-fitting shows the garment “on a supplied person”, so attach a photo of the person as well; that workflow is in Virtual try-on video API.

How do I send the photo and the product details?

Call the Format with a key that has formats:write. Put the brief in instruction and each product photo in attachments as an input_image with a public HTTPS image_url, up to 30 per run. Sume fetches each image (JPEG, PNG, WebP, GIF, or AVIF, up to 30 MB) when you create the run, so a private or broken one fails the create, not the run.

Product details go in input, a free-form JSON object of up to 64 top-level keys and 2 MiB. Sume publishes no field list for it; the Format reads the keys it recognizes. Media URLs anywhere in input share one budget with attachments, 30 files per run with at most 10 videos and 10 audio files, but a product page URL does not count.

curl -sS -X POST "https://api.sume.com/v1/formats/sume/sume-product-usage-demo/runs" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sku-1042-usage-demo-v1" \
  -d '{
    "instruction": "Show the attached hand cream being applied.",
    "input": { "product_url": "https://shop.example.com/p/1042" },
    "attachments": [
      { "type": "input_image", "image_url": "https://example.com/sku-1042-front.jpg" },
      { "type": "input_image", "image_url": "https://example.com/sku-1042-back.jpg" }
    ],
    "generation_spend_cap_usd": 20
  }'

How do I run a whole catalog of SKUs?

Give each SKU its own run and its own Idempotency-Key, derived from the SKU and a version you bump when you want a deliberate re-run. The docs warn that a uuidgen per request “makes the header decorative”, and keys are scoped to one Format, so the same key sent to two Formats starts two runs.

To queue many at once, POST /v1/formats/{handle}/{slug}/bulk-runs takes 1–100 items, each an ordinary run body, and keeps concurrency (1–16) of them in flight. The queue request takes its own Idempotency-Key: mint a fresh one per batch. The queue mechanics are in Sume Format bulk runs.

How do I animate a product photo directly?

Send POST /v1/videos with the photo, at a public HTTPS URL, as a frame_images entry whose frame_type is first_frame, and describe the motion in prompt. With model: "sume/auto", Sume picks the model family, and create controls default to 720p and 8 seconds, with 3–10 second clips at 16:9 or 9:16. Which models take which frame is in Image-to-video API.

• The call returns 202 with a job id and a polling_url. Poll until status is completed; the same job is also at GET /v1/jobs/{id}/status and GET /v1/jobs/{id}/result.
• Send Idempotency-Key: a replay returns the original job.

curl -X POST https://api.sume.com/v1/videos \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sku-1042-i2v-v1" \
  -d '{
    "model": "sume/auto",
    "prompt": "Slow camera push-in on the product, soft studio light",
    "aspect_ratio": "9:16",
    "duration": 6,
    "frame_images": [
      {
        "type": "image_url",
        "image_url": { "url": "https://example.com/sku-1042-front.jpg" },
        "frame_type": "first_frame"
      }
    ]
  }'

Which path should I pick, and what does each cost?

Pick a Format to let its saved recipe and tools make the production choices, and the direct path to write the motion prompt yourself. A Format run's full cost, the agent's own LLM turn included, is usage.debited_usd_micros on its receipt.

What should I check before I ship it?

A few rules from the same pages:

• Format media URLs are durable media.sume.com URLs that do not expire and are public to anyone holding them; proxy or copy them if each merchant needs its own access control.
• An API run is unattended: approvals are treated as granted, and a run that cannot finish comes back failed, never a half-finished completed.