Video API media inputs and outputs: public URLs in, Sume URLs out

Sume's generation API takes media inputs as public HTTPS URLs in named request fields, so a normal integration needs no upload step and no asset created first. Finished media comes back as artifact objects hosted on media.sume.com, and those Sume URLs, not raw provider URLs, are the ones to store.

The details below come from Sume's Media inputs and Core concepts pages and the attachments section of the Format API docs.

Which request fields take a media URL?

Each workflow reads media from the exact fields in the live OpenAPI schema, which api.sume.com serves at /reference/json. You do not need to create a separate Sume asset before you submit a normal Avatar 1.0, Avatar Video, face-swap, or caption request. Face swap is in Beta.

Full requests are in talking avatar video from a script and burning captions onto a video.

How do I attach images to a Format run?

A Format run can carry up to 30 images the agent can look at, as attachments[] on the create body. Each item has type: "input_image", the only type today, and one of image_url or asset_id:

• image_url is a public HTTPS URL. Sume fetches it when you create the run, so it must be reachable without auth.
• asset_id is an image you uploaded through the Assets API, ready, in the same workspace.
• filename is optional: the label the agent sees. It defaults to the URL's basename.
• Sume fetches every attachment at create time, checks its real type and size, and copies it into durable storage. A broken or private image fails the create instead of killing the run minutes later.
• An asset_id, or a URL already on media.sume.com, is not re-copied. A true Idempotency-Key replay does not re-fetch your images.

curl -sS -X POST "https://api.sume.com/v1/formats/acme/product-hero/runs" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sku-8823-hero-v1" \
  -d '{
    "instruction": "Make a product hero from the attached photo.",
    "input": { "brand": "Acme" },
    "attachments": [
      { "type": "input_image", "image_url": "https://cdn.example.com/shot.jpg" },
      { "type": "input_image", "asset_id": "asset_…", "filename": "packshot.png" }
    ]
  }'

How many media files can one run take?

Media URLs inside input, such as host_image_url or product_image_urls[], count against one budget shared with attachments[]. The check is by file type, not field name: any HTTPS URL anywhere in input whose filename ends in a media extension counts, however deeply nested. A product page URL does not count, the same URL repeated counts once, and media the agent finds for itself during the run does not count.

Why would Sume reject a media URL?

Input image and video URLs must be fetchable, public HTTPS URLs. Localhost, private-network URLs, non-HTTPS URLs, signed or private URLs, and mismatched content types are rejected before generation submission. On a Format run, attachment problems fail the create with one of these codes:

• 400 invalid_attachment: wrong type, a missing or non-HTTPS URL, both image_url and asset_id, too many items, a source that is not an allowed image type, or a media budget that is exceeded.
• 400 attachment_not_found: the asset_id is unknown in this workspace.
• 413 attachment_too_large: an image over 30 MB, or a set over 500 MB.
• 502 attachment_fetch_failed: Sume could not fetch the image because of an unreachable host, hotlink protection, or a non-2xx answer. details.index names the attachment.

What comes back when a job finishes?

Completed jobs can include artifact objects like the one below. Sume mirrors generated outputs into Sume-owned media URLs on media.sume.com before it exposes them in public results, and a job's result is available from /v1/jobs/:id/result.

Sume-owned artifact URLs are the public contract; raw provider URLs are not. A Format run's receipt also names primary_output_url, the one thing to show, and lists every file the run made in artifacts[]. Those media URLs are durable and public, so store them. What is a Sume Format? walks through a whole run.

{
  "id": "artf_...",
  "url": "https://media.sume.com/artifacts/...",
  "type": "image",
  "content_type": "image/png"
}

What does the media API not do?

The docs name these boundaries:

• Signed upload and download URLs and private object keys are not part of the launch public API contract.
• input_image is the only attachment type. Send documents by URL in input, and video or audio references the same way.
• Trending videos returns public watch URLs for research. It does not mirror downloadable source files in the MVP.