Virtual try-on video API: put a garment on a person

To make a virtual try-on video with the Sume API, call one of two catalog Formats, sume-virtual-try-on or sume-virtual-fitting, at POST /v1/formats/sume/{slug}/runs with photos of the person and the garment in attachments. To approve each step yourself, make a try-on still with POST /v1/images and animate it with POST /v1/videos.

Format facts come from the Format catalog, Create a run, and Format API docs pages and each Format's published description; the step-by-step path comes from the Image API and Video generation pages. All were read on 2026-09-27.

Which try-on Format should I call?

GET /v1/formats/sume/{slug} returns either Format's description before you call it. Both descriptions end “Not for: static campaign deliverables”, so both make video. An ad or an outfit switch fits sume-virtual-try-on; a product-page fit preview fits sume-virtual-fitting. “Accurate garment fit” is that Format's stated aim, not a guarantee, so review every video before you publish it.

How do I send the person and the garment?

Any API key with formats:write, other than a service-account key, can call a catalog Format. The run, its media, and its spend belong to the calling key, and there is nothing to fork or install first. Put the brief in instruction: it accepts 8,000 characters, the run carries the first ~4,000, and it is composed after the Format's recipe, so it wins where the two disagree.

Put each photo in attachments as an input_image with a public HTTPS image_url. filename is the label the agent sees, so use it to say which photo is the person and which is the garment. Use photos of people who have agreed to appear in the video.

curl -sS -X POST "https://api.sume.com/v1/formats/sume/sume-virtual-try-on/runs" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: look-042-jacket-tryon-v1" \
  -d '{
    "instruction": "Show the person in person.jpg wearing the jacket in jacket.png.",
    "attachments": [
      { "type": "input_image", "image_url": "https://example.com/person.jpg", "filename": "person.jpg" },
      { "type": "input_image", "image_url": "https://example.com/jacket.png", "filename": "jacket.png" }
    ],
    "generation_spend_cap_usd": 20
  }'

What limits apply to the photos?

Sume fetches and checks every attachment at create time, so a broken or private image fails the create, not the run.

• JPEG, PNG, WebP, GIF, or AVIF; input_image is the only attachment type today.
• Up to 30 images and 500 MB per run, and 30 MB per image. Over a size cap is 413 attachment_too_large.
• An image Sume cannot fetch is 502 attachment_fetch_failed, and details.index names it.
• The same Idempotency-Key and body return the original run, with no second charge.

How do I build the try-on myself, one step at a time?

Split the work into two jobs when you want to approve the look before you pay for motion. Frame support per model is in Image-to-video API, and per-model reference limits for the still are in Image generation API with reference images.

• Make the still. Send POST /v1/images with the person and the garment in input_references, as public HTTPS URLs. A model whose input_references descriptor is {"min": 0, "max": 0} is text-to-image only and rejects references; ChatGPT Image 2.5 (openai/gpt-image-2.5) takes up to 16. On image-to-image calls, prefer aspect_ratio: "auto" to match the reference.
• Host the still you approve at your own public HTTPS URL. The Image API returns data[].url as Sume-hosted and signed, and the Video generation docs do not document passing it straight into a video request.
• Animate it. Send POST /v1/videos with the still as a frame_images entry whose frame_type is first_frame. If the request also carries input_references, frame_images takes precedence and the request runs as image-to-video; references alone are covered in Reference-to-video API.

What comes back, and what does it cost?

A Format run answers 202 with a receipt, then takes minutes. Poll it, or set communication.webhook_url for one signed format.run.terminal POST. A completed run fills primary_output_url, the one thing to show, and artifacts[]. These media.sume.com URLs do not expire and are public to anyone holding them, so proxy or copy them if each customer needs private access.

Generation in the run is metered at the API pricing rates under generation_spend_cap_usd: up to $500, null runs at $500, and 0 is rejected. The run's cost, the agent's own LLM turn included, is usage.debited_usd_micros. On the step-by-step path, a failed image is not billed, and a video job is reserved at the provider's list price × 1.25, plus a 5.5% agent fee by default.

What does an API run not do?

Three boundaries of the Format path:

• No approval stops. Approvals are treated as granted, and a run that cannot finish comes back failed, never a half-finished completed.
• No model choice. The run's model field picks only the orchestrating LLM; image, video, and audio models are chosen by the Format's tools.
• No recipe edits. To change a catalog Format, fork it in the Format library and call your copy at {your_handle}/{slug}.