asset_upload
Upload local image files to the site's media library without attaching them, and receive asset IDs and derivative sizes for building responsive srcsets.
Instructions
Upload local image files into the site's media library (POST /assets -> PUT bytes -> PUT confirm) WITHOUT attaching them to anything. Use for images referenced from site.data / page.data maps, article galleries or template markup; use product_set_images when the images are a product's gallery.
Returns each asset's id, dimensions, public path (/photos/) and the derivative sizes Voog actually produced — build srcsets from those widths, never from guessed ones (a width Voog did not make answers 403 and the browser renders nothing). Voog caps the LONG side of each derivative at 150/600/1280/2048 and scales the other side to match the source aspect ratio, so a wide image's derivatives are capped on WIDTH, not height.
By default an existing asset with the same filename is REUSED rather than uploaded again: Voog auto-suffixes duplicate filenames (photo-1.jpg), so re-uploading silently orphans the original. Pass allow_duplicate=true to force a new asset (e.g. a corrected re-shoot under a fresh sequence letter).
Waits for Voog to finish its async resizes before returning — up to 120s per file, polling the API every 5s, so a large batch is slow by design. Each result carries sizes_complete: false means the wait timed out and sizes is PARTIAL, so build the srcset from a later read rather than from those widths. Pass wait_for_sizes=false to skip the wait entirely (then sizes is empty).
Do NOT request a derivative URL over HTTP to check whether it exists — a too-early request gets a 403 that the CDN caches for ~1h, breaking a URL that was about to work.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| site | Yes | Site name from voog_list_sites | |
| files | Yes | Absolute paths to local image files (.gif, .jpeg, .jpg, .png, .webp) | |
| wait_for_sizes | No | Wait for Voog's async resizes before returning (default true). false returns as soon as the upload is confirmed — `sizes` may then be empty. | |
| allow_duplicate | No | Upload even when an asset with this filename already exists (default false = reuse it) |