Avatar 1.0 media URLs: image_url, product_image, scene.image_url

Avatar 1.0 takes media as public HTTPS URLs, and each URL goes in a specific field: input.image_url for an avatar photo, product_image for a product shot, scene.image_url for a scene photo, video_inputs[].background.url for a per-scene background and video_url for face swap or captions.

The mapping is the table on Media inputs, read 2026-10-02. You do not need to create a Sume asset first.

Which field do I use for what?

Putting a URL in the wrong field is a common first-run mistake, and the fields are not interchangeable.

What gets a URL rejected?

Before generation is submitted, Sume rejects localhost and private-network URLs, non-HTTPS URLs, signed or private URLs, and responses whose content type does not match. Because the check happens before submit, a bad URL fails fast and does not start a paid job.

The practical consequence: a presigned storage link is the wrong thing to paste in, since it counts as signed. Host the file at a stable public HTTPS address, or reuse a media.sume.com URL from an earlier result.

What does a request with several fields look like?

An avatar created from a photo, then a video that uses a product image and a prompt-described scene. Scene direction has two shapes: { "type": "prompt", "prompt": "..." } and { "type": "photo", "image_url": "https://..." }.

{
  "avatar_handle": "reference_presenter",
  "product_image": "https://example.com/product.png",
  "scene": {"type": "photo", "image_url": "https://example.com/kitchen.jpg"},
  "script": "Meet our new pour-over kettle.",
  "quality": "plus"
}

The avatar itself would have been created earlier with input: { "type": "photo", "image_url": "https://example.com/reference.png" }. The video request references it only by handle.

What comes back, and where do I store it?

Completed jobs can include artifact objects with an id, a url, a type and a content_type. Sume mirrors outputs into Sume-owned media.sume.com URLs before exposing them, so store the Sume URL, not a raw provider URL. Signed upload and download URLs and private object keys are not part of the public API contract.

If you need a first-party asset id rather than a URL, asset registration and upload paths are write-gated; the docs recommend public HTTPS URLs in generation payloads when you do not need ids.

A pre-flight checklist for media URLs

Open every URL in a private browser window before you submit; if it needs a login, it will not work. Confirm it starts with https://, points to a public host and returns the right content type: an image field needs an image response, and a page that merely contains an image does not count.

Keep a small test image on your own domain so you can separate a URL problem from a content problem. Then check that the field matches the branch: scene.image_url only applies when scene.type is photo, and background.url only when background.type is image.

This post only covers where URLs go. For what an avatar photo costs, see the reference-image post.

Can I reuse the same image in two fields?

Yes. Nothing in the docs ties a URL to a single field, so the same public image can be the avatar photo in one request and a product image in another. Each field is validated on its own when you submit, and each request is billed on its own estimate.

Reusing URLs also keeps your storage simple: one hosted file, referenced by every request that needs it. Just do not change the file behind a URL while a job that uses it may still be fetching it.