Send a video to a Format run: URLs in input, not attachments

The attachments field on a Format run, and on POST /v1/agent/completions, accepts images only: input_image is the only attachment type. To hand a Format a video, put its HTTPS URL inside input. On Format runs, media URLs anywhere in input share one budget with the attachments, and going over it is 400 invalid_attachment on the create.

The budget

The Format docs describe it as one budget shared by attachments[] and media URLs in input. The check is by file type, not field name.

Doing it

Put the URL under a key you choose, and tell the Format which key to read in instruction. Send an Idempotency-Key and, if you do not want the Format's default ceiling, a generation_spend_cap_usd. A Format with no cap inherits $400, and the platform maximum is $500.

curl -sS -X POST "https://api.sume.com/v1/formats/sume/sume-restyle/runs" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: restyle-clip-7-v1" \
  -d '{
    "instruction": "Use input.source_video as the reference video.",
    "input": {"source_video": "https://media.sume.com/artifacts/artf_demo/clip.mp4"},
    "generation_spend_cap_usd": 20
  }'

Choosing the key name

Pick a descriptive key such as source_video and name it in the instruction. Because the check is by file type and not field name, a URL nested several levels deep still counts, and a repeated URL counts once. If you pass a page URL instead of the file, it is not counted as media and the agent may not get the video at all, so link the file itself.

Limits

A URL that does not end in a media extension is not counted as media, so do not rely on the budget check to catch a bad link. Whether a Format actually reads a video is up to its recipe; check the Format's io profile first. For Agent Completions the docs state images-only attachments but no video budget, so send text derived from the video, such as sentence segments from video-inspect, rather than assuming the agent will watch it. More than 10 videos needs several runs, or a bulk run of 1 to 100 items.