{"openapi":"3.1.0","info":{"title":"media.pollinations.ai","description":"Media storage for Pollinations. Upload images, audio, and video and get back a unique id and URL. Uploads require a pollinations.ai API key (`pk_` or `sk_`). Retrieval is public. Tagging an upload publishes it to that tag's public gallery; the gallery features (tags, listing, delete) are **alpha** — their API may still change.","version":"1.0.0"},"servers":[{"url":"https://media.pollinations.ai"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"pollinations.ai API key (pk_ or sk_)"}}},"security":[{"bearerAuth":[]}],"paths":{"/upload":{"post":{"operationId":"postUpload","tags":["media.pollinations.ai"],"summary":"Upload media","description":"Upload an image, audio, or video file via multipart/form-data (field `file`) or application/json (base64 `data`). Returns a unique id and its retrieval URL; each upload gets its own id (re-uploading the same bytes yields a new one). Files are retained for 30 days.\n\n**Tags publish.** An optional `tags` field publishes the upload into each tag's public gallery (GET /media?tag=…), where anyone can see it. Untagged uploads stay unlisted: reachable only by their unguessable id URL, never listed anywhere. **Alpha:** the publish tagging is new and may still change.","requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"The media file to upload."},"tags":{"type":"string","description":"Comma-separated tags. Tagging publishes the upload to those tags' public galleries."}}}},"application/json":{"schema":{"type":"object","properties":{"data":{"type":"string","minLength":1,"description":"Base64-encoded file bytes (with or without a data: prefix)."},"contentType":{"description":"MIME type; defaults to application/octet-stream.","type":"string"},"name":{"description":"Filename; used for the download Content-Disposition.","type":"string"},"tags":{"description":"Tags (publish the upload to those tags' public galleries): a comma-separated string or an array of strings.","anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},"required":["data"],"additionalProperties":false}}}},"responses":{"200":{"description":"Upload successful","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Unique media id (also the retrieval id)"},"url":{"type":"string","description":"Public retrieval URL"},"contentType":{"type":"string"},"size":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"File size in bytes"},"tags":{"description":"Tags the upload was published with; present only when tagged","type":"array","items":{"type":"string"}}},"required":["id","url","contentType","size"]}}}},"400":{"description":"No/empty file, invalid JSON/base64, invalid tags, or tags on a key with no user account","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"413":{"description":"File too large (max 100MB)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/media":{"get":{"operationId":"getMedia","tags":["media.pollinations.ai"],"summary":"List a public tag gallery","description":"List the public gallery for a tag: every published item carrying that tag, any owner, newest first. Tagging an upload is what publishes it, so galleries are fully public — no API key needed. `tag` is required.\n\nItems reference storage with a 30-day lifecycle. A GET refreshes the lifecycle once an object is at least 15 days old. An expired item keeps its catalog entry, but its url 404s. **Alpha:** this endpoint is new and its API may still change.","security":[],"responses":{"200":{"description":"Page of media items","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Catalog item id"},"url":{"type":"string","description":"Public retrieval URL"},"contentType":{"type":"string"},"size":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"File size in bytes"},"tags":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","description":"ISO-8601 timestamp"}},"required":["id","url","contentType","size","tags","createdAt"]}},"nextCursor":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Opaque cursor for the next page, null when exhausted. Treat it as a token: pass it back verbatim as `?cursor=` to fetch the next page — do not parse or construct it."},"hasMore":{"type":"boolean","description":"true when more pages exist (nextCursor is non-null). Loop while hasMore is true."}},"required":["items","nextCursor","hasMore"]}}}},"400":{"description":"Missing/empty tag, or invalid cursor or limit","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}},"parameters":[{"in":"query","name":"tag","schema":{"type":"string"},"required":true,"description":"Required. The public gallery to list: items carrying this tag, any owner."},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100},"description":"Page size, 1–100. Omitted → 20."},{"in":"query","name":"cursor","schema":{"type":"string"},"description":"Opaque pagination cursor from a previous response's nextCursor."}]}},"/media/{id}":{"delete":{"operationId":"deleteMediaById","tags":["media.pollinations.ai"],"summary":"Delete media","description":"Delete a published media item you own: the file, its catalog entry, and all its tags are removed, so it disappears from galleries and its URL 404s. Requires your **secret (`sk_`)** API key. Untagged uploads were never published, have no catalog entry, and can't be deleted — they use the same 30-day lifecycle, refreshed by a GET once they are at least 15 days old. **Alpha:** this endpoint is new and its API may still change.","parameters":[{"name":"id","in":"path","required":true,"description":"Media id (from the upload response or GET /media).","schema":{"type":"string"}}],"responses":{"200":{"description":"Item deleted","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean","const":true},"id":{"type":"string","description":"Id of the deleted media item"}},"required":["deleted","id"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"403":{"description":"Key is not a secret (`sk_`) key, is not attached to a user account, or the item belongs to someone else","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"404":{"description":"No published media item with this id","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/{id}":{"get":{"operationId":"getById","tags":["media.pollinations.ai"],"summary":"Retrieve media","description":"Get a file by its id. Access keeps files from expiring.","security":[],"responses":{"200":{"description":"File content with appropriate Content-Type"},"404":{"description":"File not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}]},"head":{"operationId":"headById","tags":["media.pollinations.ai"],"summary":"Check if media exists","description":"Check existence and metadata without downloading the file.","security":[],"responses":{"200":{"description":"File exists (headers include Content-Type, Content-Length, X-Content-Id)"},"404":{"description":"File not found"}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}]}},"/{id}/metadata":{"get":{"operationId":"getByIdMetadata","tags":["media.pollinations.ai"],"summary":"Get file metadata","description":"Return file metadata (id, content type, size, upload timestamp) as JSON without downloading the file body.","security":[],"responses":{"200":{"description":"File metadata","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Unique media id"},"contentType":{"type":"string"},"size":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"File size in bytes"},"uploadedAt":{"description":"ISO-8601 upload timestamp, when recorded","type":"string"}},"required":["id","contentType","size"]}}}},"404":{"description":"File not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"id","required":true}]}}}}