Media CDN API

SpinShot serves processed images from our CDN. You build URLs as path segments, not query strings. The server reads the stored file, applies the segments you include, and returns a cached image. This article documents the four public path styles for product images: frames, stills, gallery, and images.

To use the in-app URL builder, open a product, go to Embed, and switch the preview to Grid (the grid control next to the default spin view). Select an image in the grid; the panel shows direct URLs and the transform builder that matches the patterns below. You can also open a specific image from the grid to adjust transforms and copy the resulting link.

At a glance

This article is for product-image links where the path encodes how the file is stored: revision, row, filename, or a longer path segment—the same shape SpinShot uses in the dashboard, embeds, and viewer.

Each full URL is cached separately. Two different paths that show the same picture are still two cache entries unless you pick one URL and use it consistently.

Discover current image URLs with the REST API

Prefer GET https://app-staging.spinshot.io/api/v2/products/UUID/images over constructing storage paths yourself. See List a product’s images for the full response. This endpoint returns an array of images with id, ordial, alt_texts, source_revision, storage_version, image_status, source, row, image_group, media_ready, media_url, and thumbnail_url. The former name field has been removed; use numeric ordial for ordering and source for the stored filename. It uses existing HTTP Basic authentication and requires project edit permission; API responses use Cache-Control: no-store. Empty products return [], and image records remain available for alt-text editing during processing.

• media_url is an absolute HTTPS base URL on the account’s media host, followed by its public account UUID and image.image_path. Source path segments are URL-encoded. It has no trailing slash, transforms, or output filename; append these to request an image.
• thumbnail_url is ready to display: media_url plus /resize;w_320/image.webp, requesting a 320 px wide WebP with the source aspect ratio preserved. Neither URL automatically includes viewer settings or watermarks.
• media_ready is a boolean. Both URLs are null unless the product’s image_status is finished and usable path/account metadata exists.

For custom output, append Media CDN transforms and an output filename to media_url, not to thumbnail_url. For example (fictional identifiers and reserved example hostname, not customer values):

Base returned by the API: https://media.example.com/example-account/frames/example-product/0;2;sample%20side.jpg Custom WebP output: https://media.example.com/example-account/frames/example-product/0;2;sample%20side.jpg/resize;w_1200/optimize;q_85/image.webp

The URLs use the current Flyster media stack and the actual stored source, which must not be inferred from ordial. For example, the first image (ordial: 1) may reference the stored file 4.jpg. For storage v1, rotation images use frames/{product_uuid}/{revision};{row};{source}, additional images use stills/{product_uuid}/{revision};{source}, and gallery images use gallery/{product_uuid}/{revision};{source}. The row is the individual image’s stored row. For storage v2, all groups use images/{product_uuid}/{source} without a revision in the path. The returned source_revision is the variant’s current upload revision, including 0, regardless of storage version.

The image list reflects the latest state at the request snapshot. Refetch after a reshoot or reupload: image IDs and source filenames can change, and old URLs do not automatically follow the latest upload. Poll GET https://app-staging.spinshot.io/api/v2/products/UUID/status with backoff using variant.source_revision and variant.image_status, then refetch /images after status is finished and check media_ready. The existing status endpoint is public and uses Cache-Control: no-cache (revalidation required); the image listing requires authentication and edit permission and uses no-store. Revisions increment before processing finishes; never synthesize a new path from a status revision alone. API no-store responses are separate from the CDN caching of rendered images described above.

URL layout

https://media.spinshot.io/{account_id}/{segment}/{…path…}/{transformations}/{output_name}.{ext}

Part	Meaning
hostname	The media host, often media.spinshot.io in production. Use the same host that appears in working links in your account (staging may use another hostname).
account_id	Public account UUID (not an internal database ID); use the value in the returned media_url.
segment	One of frames, stills, gallery, or images (see the next section).
…path…	Depends on the segment; each subsection below shows the exact shape
transformations	Chained transform blocks, e.g. a resize block followed by an optimize block: see the transformation section for full examples.
output_name.ext	Last segment; the file extension sets format (for example jpg, png, or webp).

Four path styles

Pick the segment and path shape that matches your product.

Segment	What it is for
frames	360° rotation: one file per step; path includes revision, row, and filename
stills	Additional photos (not the spin), keyed by revision and filename
gallery	Gallery images for the product, keyed by revision and filename
images	Flat or multi-segment path under the product UUID; typical for current flat storage—use the path SpinShot already emits

frames — 360° rotation

Pattern:

https://media.spinshot.io/{account}/frames/{product_uuid}/{revision};{row};{filename}/resize;{options}/image.jpg

Path pieces:

Piece	Notes
revision	Upload revision, often 0, 1, …
row	Multi-row spins; single-row is usually 1
filename	Stored name, e.g. image-1.jpg

Example:

https://media.spinshot.io/7458632/frames/489162134/0;1;image-1.jpg/resize;w_160;h_160;f_cover/optimize;bg_ffffff/image.jpg

stills — additional photos

Pattern:

https://media.spinshot.io/{account}/stills/{product_uuid}/{revision};{filename}/resize;{options}/image.jpg

Example:

https://media.spinshot.io/7458632/stills/489162134/0;image-3.jpg/resize;w_800;h_800;f_inside/optimize;bg_ffffff/image.jpg

gallery

Pattern:

https://media.spinshot.io/{account}/gallery/{product_uuid}/{revision};{filename}/resize;{options}/image.jpg

Example:

https://media.spinshot.io/7458632/gallery/489162134/0;image-7.jpg/resize;w_1920;h_1080;f_inside/optimize;bg_ffffff/image.jpg

images — flat or multi-segment path

When to use: use this segment when the path under the product is a single filename or several nested folder or name segments. Transformations start after that path. Common for flat storage where each file is images/{product_uuid}/{filename}.

Pattern:

https://media.spinshot.io/{account}/images/{product_uuid}/{extra_path_segments…}/{transformations}/image.jpg

Path note: everything after images/{product_uuid}/ up to the first transformation segment is the file path for that product.

Example (flat, one filename):

https://media.spinshot.io/7458632/images/489162134/abc-def-uuid.jpg/resize;w_800;h_800;f_inside/optimize;bg_ffffff/image.jpg

Transformation segments

Transform blocks in the path are divided by slash characters. Inside each block, the module name and its parameters are divided by semicolons (for example: resize, then w_800, h_600, f_inside in one block). The following modules are the usual ones.

Resize

Example: resize;w_800;h_600;bg_ffffff;f_inside. Use w_ and h_ for width and height in pixels, bg_ plus a six-digit hex without a hash for background, and f_inside, f_cover, f_contain, and so on for fit (f_ plus the Sharp name). That form matches Flyster and the in-app URL builder.

Optimize

Example: optimize;q_85;bg_ffffff. The q_ parameter is quality from 1–100. Optional bg_ uses the same hex style as resize. A single optimize block can list both, separated by semicolons.

Trim

Example: trim;t_10. The t_ value is the trim threshold: an integer from 0 to 100 (in-app default 10). Higher values remove more of a uniform border before the subject; 0 is a light trim.

Preset

Example: preset;id_abc123. Optional; applies a saved transformation preset from SpinShot when you use it.

Watermark

When watermarking is enabled for the account, a watermark block appears (for example watermark;… with a structured payload from SpinShot).

Output filename

After the transform chain, the last path segment sets the file name and type: the bare name image for JPEG, or image.png and image.webp for those formats.

Modifier and trim options can differ from other ways you might request a resized image, so do not copy modifier strings between unrelated URL styles. For working chains, copy from the dashboard, an export, an embed, or the browser network tools.

Related

• Frame extraction API
• RESTful API
• Hotspots