Start an upload
- Reuse your approved account connection, refresh its token if needed, and verify the account with
GET /v1/session. For intentional guest uploads, reuse a retained guest session or create one withPOST /v1/sessions. Do not switch to guest hosting when expected account access fails. - Hash the exact file bytes with SHA-256 and create an upload with
POST /v1/uploads. - Send raw bytes once to the returned upload URL using all returned headers.
- Complete the upload with
POST /v1/uploads/{id}/completeand wait until the asset is ready.
Keep the returned expiry. For uncertain writes, use the private status URL rather than replaying bytes. See the full API guide for authentication and recovery details.
Hosting limits
Contract 3-edad2f47 · policy 2026-09-28-v2
| Client | Maximum file | Retention | Daily attempts | Batch items |
|---|---|---|---|---|
| Visitor | 5 MiB | 1 day | 25 | 25 |
| Free account | 20 MiB | No routine expiry for eligible verified Free accounts | 250 | 250 |
| PRO account | 20 MiB | No routine expiry while PRO is active | 2,500 | 1,000 |
Eligible verified Free accounts receive no routine expiry within their storage allowance. Visitor and unclaimed uploads expire after 24 hours. A full storage allowance blocks new admissions without deleting existing files. Read each upload's returned expiry and signed-in account limits.
The table shows each tier's general per-file allowance. New still-image uploads are limited to the smaller of the tier allowance and 20,000,000 bytes; visitors retain their 5 MiB cap. MP4 and GIF use the tier allowance. Check the returned policy.maxUploadBytes before sending bytes for each new upload. An exact idempotent replay keeps its captured policy.
Supported upload formats
image/gif · image/heic · image/heif · image/jpeg · image/png · image/webp · video/mp4
The website uploader can preview and edit supported HEVC HEIC/HEIF still images, using native decoding first and a compatible preview fallback when available. When native HEVC preview fails, the local fallback accepts up to 20 MiB, 8192px per side and 32MP decoded area, and makes a preview at most 1024px on its longest side. Preview depends on the browser, device and available resources; the original can still be uploaded and downloaded if preview fails. Saved edits are new WebP or PNG files. API clients should submit the selected original bytes and omit legacy processing. Account optimization and quality control any further hosting encoding.
New public IDs use 16 Base62 characters; older links remain accepted.
Account image uploads
Signed-in owners set automatic optimization and quality in Dashboard Settings. GET /v1/session returns the effective imagePolicy to an authorized upload client; GET and PUT /v1/account/image-settings are human browser routes, with owner permission required to save. Optimization is on by default and outputs WebP. With it off, an allowed still image retains the exact submitted bytes, including embedded metadata and any location data; review the file before sharing. Free accounts allow up to 2000px displayed width. For a wider source, request imageProcessing: {"resizeToAccountLimit":true} when creating a new upload; a width rejection requires a new session and idempotency key. PRO has no product width cap, subject to supported file and processing limits. Ready status reports the actual MIME type, dimensions, bytes and checksum.
Image variants
Request a WebP delivery size from an eligible PRO public still image. For example, /a/PUBLIC_ID?width=320 preserves the source aspect ratio.
| Parameter | Accepted values | Default |
|---|---|---|
width | Positive integer, no greater than the source width or 4,096 pixels | Derived from height to preserve aspect ratio; otherwise the source width |
height | Positive integer, no greater than the source height or 4,096 pixels | Derived from width to preserve aspect ratio; otherwise the source height |
fit | contain or cover; cover requires both dimensions and centre-crops | contain (no crop or padding) |
format | webp only | webp |
quality | 70, 82, or 90 | 82 |
The result cannot exceed 16 megapixels or enlarge the source. Query order does not change variant identity. Unknown or repeated parameters are rejected. See the full variant contract.
The images below are static local browser-optimizer illustrations, not results from the hosted variant route. The 320-pixel file uses quality 80, which the hosted route does not accept. Hosted requests allow quality 70, 82, or 90.
These examples show how dimensions and encoding affect one image; results vary by source. Variants require active PRO eligibility and resizing availability. The first request creates a resized image that can be saved for reuse. CDN caching can speed up later delivery, although a cache hit is not guaranteed for every request.
Video posters
Eligible ready public MP4 videos on active PRO CDN accounts can return a still WebP poster. For example, /a/PUBLIC_ID/poster?frame=2.5&width=320. The original video URL still plays the MP4.
| Parameter | Accepted values | Default |
|---|---|---|
frame | Seconds from the start, nonnegative, up to three decimal places, strictly before the video ends and below 60 seconds | 0 |
width, height, fit, format, quality | Same bounds and options as image variants above; no upscaling | Same as image variants above |
Each frame time and output combination is a variant. The MP4 source uses the hosted 20 MiB input limit; outputs and variant counts use the limits above. A first request may create the poster; a later matching request may reuse it. HEAD only reports a saved poster. Invalid options fail with 400, ineligible videos with 403 or 404, limits with 429, and pending or temporarily unavailable generation with 503. Range requests return 416. Public gallery thumbnail URLs check current gallery access and membership. If a poster cannot load, show the video or a video placeholder. See the full poster contract.
Organize and find account media
The signed-in owner can group Library media by Agents, Sites, Clients, Projects, and account-owned Categories. Each account starts with nine Categories; owners can edit definitions, exclusions and aliases or archive and restore them. A Project may belong to one Client; the Client view includes its Projects. Term names may change without changing their IDs, and archived or disconnected terms can still describe existing media.
Use GET /v1/media-taxonomies and the term picker to discover IDs. Read GET /v1/assets/{id}/organization before changing manual memberships, and send its exact ETag with If-Match on a patch. Query combinations with POST /v1/media-query; pages include direct and inherited memberships. If a cursor becomes stale, start at the first page. Requested counts may be unavailable even while pages can be read.
Owner browsers can use these routes. Connected native agents with media:search-own can search eligible account media and read only Category, Client, and Project organization, terms, and facets; media:metadata-edit-own allows editorial edits and Category, Client, and Project assignments under their own connection. New rights require explicit human approval. Read the full organization guide for limits, write requirements, and retry behavior. Owners can also correct agent supports and accepted Category suggestions, and edit manual Site associations. Optional account Category suggestions send the owner-visible selected filename, title, description, caption, alt text and tags, plus active Category names, definitions, exclusions and aliases, to OpenRouter and model providers after owner confirmation. Media pixels and originals are not sent for this Category request. Suggestions require the owner's explicit review before entering Library filters. Check availability and the account budget, quote the whole selected batch count and maximum reservation, and confirm before requesting a job. Availability labels a provisional model as not evaluated; each admitted job reports its reservation plus requested and actual model identifiers. See the full organization guide for cancellation, retries and stale evidence. Verified Agent origins and Site imports or publications remain read-only. A manual Site association does not mean the media was published there.
FooGallery Site Connect
A FooGallery WordPress site requests apiVersion: 2026-10-04 with requestedGrant: foogallery-site. For Try it first, the site may include its live guest session proof only as x-foopixel-session on the server-to-server connection request. Guest uploads use the ordinary 25-attempt and 50 MiB daily allowance, two outstanding uploads, and 10 network starts per minute. A rate refusal returns 429 rate_limited with Retry-After before bytes are accepted. After the owner selects an account, the review shows how many trial images and other uploads fit and lists every overflow upload. A changed review requires a new request and consent. Kept uploads can be read by the new Site bearer; a public image keeps its public URL, while overflow keeps its guest expiry. The signed-in FooPixel Account owner reviews its hostname and installation path before approving. The site verifies the callback and exchanges its one-time code for a bearer. Token exchange and GET /v1/site-connections/self report grant.profile: foogallery-site, consent version 2, and informational effectiveScopes. The scope list may grow; ignore unknown names and handle a denied route. Owners see FooGallery · hostname/path in Connections and Library; if a connection or Site term name is shown outside owner views, it uses the neutral FooGallery site label; those responses do not all display a Site name today. Eligible media copied through a current verified Site connection can carry the owner-visible imported_from relation. Site bearers cannot start paid Category evaluation today; those requests return 403 human_action_required without a job or spend. See the full Site Connect guide and OpenAPI contract.
Feature availability
- Motion uploads: Available
- Credits: Available
- CDN: Available
The CDN setting in live API capabilities reports service configuration, not a specific account's delivery status. A signed-in owner can read cdn.enabled, freeCacheAvailable, and manualPurgeAllowed from billing status. Eligible verified Free public media can use CDN delivery. Saved resizing and manual cache clearing require active PRO. Verify resizing availability before relying on variants. Cache hits and speed are not guaranteed.