Share one packshot across 100 bulk items with an asset_id

Upload the packshot once through the Assets API and pass its asset_id in each item's attachments. Sume does not copy an asset_id, or a URL that is already on media.sume.com, again. A remote URL, by contrast, is fetched and copied into durable storage when each run is created.

The two attachment forms

A run can carry up to 30 images as attachments[]. Each entry is { "type": "input_image", ... } with either an image_url or an asset_id, plus an optional filename that the agent sees. The asset_id must be an image that is ready and in the same workspace.

A bulk item that shares one image

Each item is the same body as a single run. Only the data that changes goes in input.

{
  "concurrency": 4,
  "items": [
    {
      "instruction": "Holiday hero from the attached packshot.",
      "input": { "sku": "8823", "headline": "Gift it early" },
      "attachments": [{ "type": "input_image", "asset_id": "asset_..." }]
    },
    {
      "instruction": "Holiday hero from the attached packshot.",
      "input": { "sku": "8824", "headline": "Wrapped and ready" },
      "attachments": [{ "type": "input_image", "asset_id": "asset_..." }]
    }
  ]
}

Checking the upload first

An asset_id has to be ready before you use it, so poll the asset until it is ready, then build the batch. If the asset is in another workspace, the create fails with attachment_not_found, so use a key from the workspace that owns the upload.

Per-item data still belongs in input: the SKU, the headline and the price. The shared image is only the visual reference. If each product has its own photo, the same pattern applies with one asset per item, and the 30-image cap is per item, not per queue.

One more reason to prefer an asset is failure isolation. A public URL that returns an error at create time stops the whole bulk body. If the shared image itself is wrong, fix it once and use a new idempotency key for the rerun.

Tradeoffs

An asset_id ties the batch to one workspace and to an upload that must finish before you send the create. A public URL is simpler for one-off runs but costs a fetch per item and fails the whole create if it is dead. Media URLs on media.sume.com are public and durable, so do not use them for images that must stay private.