AI product demo video generator API: show one real action

To generate a product demo video with the Sume API, call the catalog Format sume-product-usage-demo at POST /v1/formats/sume/sume-product-usage-demo/runs with the product photo in attachments and the one action to show in instruction. To build it yourself, animate a still of the product in use with POST /v1/videos, one clip per action, and join the clips with a Timeline 1.0 render.

The facts below come from Sume's Format catalog, Create a run, Video generation, and Timeline 1.0 docs and the Sume API reference, read on 2026-09-27. AI UGC ad generator API lists this Format next to the UGC ones; this post is about demos.

What does the product usage demo Format make?

sume-product-usage-demo (catalog title: Sume Product Usage Demo) is a catalog video Format. Its description reads: "Create a finished product-usage video that demonstrates one real action, texture, or result in a casual social setting. Use when the user asks for skincare application, household product demos, unbox-and-use clips, and hands-on product ads. Not for: static campaign deliverables."

That is the Format's stated aim, not a guarantee about any one clip. The recipe stays private; what you send is the brief (instruction), caller data (input), and images (attachments). The run's model field picks only the LLM that orchestrates the run; image, video, and audio models are chosen by the Format's tools.

How do I brief a demo run?

Any key with formats:write can call it. Keep each run to what the description names:

• Name one action, texture, or result in instruction. It accepts 8000 characters, and about the first 4000 reach the run.
• Attach the packshot as an input_image with a public HTTPS image_url. A run takes up to 30 images.
• Put product facts in input. It is written whole to a file the agent is told to treat as data, not instructions.
• Bind an output_schema with a SumeMediaFile# field and name it in primary_output_key, so primary_output_url is the clip.

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: acme-serum-demo-pump-v1" \
  -d '{
    "instruction": "Demo: one pump of the attached serum worked into the back of a hand.",
    "input": { "product_name": "Acme Serum" },
    "attachments": [
      { "type": "input_image", "image_url": "https://example.com/serum.png", "filename": "serum.png" }
    ],
    "output_schema": {
      "name": "acme/demo-clip/v1",
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "required": ["demo_video"],
        "properties": { "demo_video": { "$ref": "SumeMediaFile#" } }
      }
    },
    "primary_output_key": "demo_video",
    "generation_spend_cap_usd": 20,
    "communication": { "webhook_url": "https://example.com/hooks/sume" }
  }'

How do I build a demo clip myself?

Animate a still of the product in use, one action per clip. Animating a photo as the first frame is covered in Product photo to video API; for a demo, what changes is the still you start from and where the clip goes next:

• Make the in-use still by sending the packshot in input_references to POST /v1/images. Its data[].url is Sume-hosted and signed, and the video docs do not document passing that URL straight into frame_images, so put the still you pick at your own public HTTPS URL.
• Pass that still in frame_images with frame_type: "first_frame" on POST /v1/videos. Do not count on the packshot as an extra input_references entry: when both are sent, frame_images takes precedence and the request is treated as image-to-video.
• Length, resolution, and sound are per model: read supported_durations, supported_resolutions, and generate_audio on GET /v1/videos/models.
• Read the clip's media.sume.com URL from GET /v1/jobs/{id}/result; the Timeline step below needs it. Sume mirrors generated outputs to Sume-owned media URLs before exposing them.

How do I join several steps into one demo?

Render each step as its own clip, then place the clips as video[] slots in one Timeline 1.0 render (POST /v1/timeline-1.0/render), which returns one MP4. Every URL in the render must already be your workspace's media.sume.com artifact or asset. Transitions are covered in Video transitions API.

• A render takes 1–200 slots. video[0].start must be 0, and later starts must increase.
• The render's audio is a voice-over spine (audio.url or audio.parts[]) plus an optional soundtrack bed. audio.mode: "silence" renders a silent audio track instead.
• POST /v1/timeline-1.0/plan checks the document without creating a job or reserving credits.

What does a demo cost?

On the Format path, generation is metered at API pricing rates and bounded by generation_spend_cap_usd: up to $500, null runs at $500, and 0 is rejected. The receipt's usage.debited_usd_micros is what the wallet deducted, the agent's own LLM turn included. On the direct path, each video job reserves provider list × 1.25 at submit, and each image and render bills on its own.