Photopurr DocsImage download
Originals, thumbnails, download parameters and retention
Generation results and images inside image packs are fetched through the same endpoint:
GET /api/file/<filename>
Authorization: Bearer sk_your_keyRequires the assets:read scope. filename comes from images[].url in the POST /api/v1/generate response, or from download_url in an image pack snapshot. Both are relative paths of the form /api/file/<filename>; prefix them with the domain you are calling.
The 302 redirect
The endpoint never serves image bytes itself. After authentication it answers 302 with a direct link valid for one hour, and the bytes come straight from object storage. So:
- Follow redirects (
-Lfor curl; most HTTP libraries follow by default) - Don't store the redirected URL for reuse; it dies after an hour. Store the
/api/file/<filename>path instead - The redirected request needs no
Authorizationheader
Parameters
| Parameter | Description |
|---|---|
| none | The original, full size, never resized or cropped. Generated images are stored as JPEG (.jpg); only an image that actually uses transparency is a PNG (.png). The extension always matches the file content, so take it from filename rather than hard-coding one |
?w=<width> | Thumbnail, snapped to the nearest size tier: 42 / 48 / 56 / 68 / 96 / 104 / 120 / 160 / 180 / 200 / 210 / 220 / 240 / 640 / 840 / 1024 / 2048. The first request for a tier renders it; later ones hit the cache |
?dl=1 | Download as an attachment. The response carries Content-Disposition, so browsers save it under the original filename |
Use thumbnails for lists and previews, originals for storage and listings.
Errors
This endpoint is not under /api/v1, so errors come back as plain text, not JSON:
| Status | Meaning |
|---|---|
401 | No key / key invalid, revoked or expired |
403 | Key lacks assets:read, or the account is banned |
404 | File doesn't exist, or doesn't belong to the current account |
429 | Key over its rate limit |
How long images are kept
Each account has a cap on total images (1000 by default, adjustable by operations). Past the cap, images are cleaned up on a rolling basis starting from the oldest, originals and thumbnails together.
Never cleaned up:
- Favorite reference images
- Persona source images
- Images referenced by an image pack draft or by a published version
Generation results are not on the exempt list. Download API results promptly to your own storage; don't treat Photopurr as an image host. A cleaned-up image returns 404 on request, and 400 reference_image_missing when passed back as ref_image_ids.