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.
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 id (from the dashboard or API) |
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.