Read and asset routes
Each route here returns one stored or external file. The paths are unversioned and are under the endpoints.media base URL from instance discovery, except Get static object, which uses endpoints.static_cdn. Every route accepts GET and HEAD and has no rate limit.
Common responses
Section titled “Common responses”Every route can also return these statuses.
| Status | Body | Condition |
|---|---|---|
| 403 | Forbidden | The cross-origin read policy refuses the request Origin on an mp or upload endpoint |
| 404 | Not Found | The path is not a media route, the endpoint runs in relay mode, or the object does not exist |
| 405 | Method Not Allowed | The method is neither GET nor HEAD |
| 413 | Payload Too Large | The route has to hold an object larger than 500 MiB in memory |
| 502 | Bad Gateway | The object store could not be read |
Attachments without a transformation, entrance sounds and static objects stream the stored bytes and have no size limit. Every route accepts Range when it returns the stored bytes unchanged. A transformed response ignores Range and is always complete. See Byte ranges for the 206 and 416 headers.
Get attachment
Section titled “Get attachment”GET/attachments/{path}Returns the attachment at the url or proxy_url of a message attachment object. Use the URL as issued, and add a transformation parameter to its query string to resize or convert the file. Anyone with the URL can read the file, and the signed attachment URL policy decides how long it works.
Query parameters
Section titled “Query parameters”| Field | Type | Description |
|---|---|---|
| width? | integer | The output width in pixels, up to the decoded edge bound |
| height? | integer | The output height in pixels, up to the same bound |
| format? | string | The output format |
| quality? | string | The encoder quality profile |
| animated? | boolean | Whether animated output is requested |
| effort? | integer | The WebP encoder effort (at most 9) |
| download? | boolean | Whether the response has attachment disposition |
| ex? | string | The URL expiry, from the issued URL |
| is? | string | The URL issue time, from the issued URL |
| hm? | string | The URL signature, from the issued URL |
| uc? | string | Set to dp on data package download URLs, from the issued URL |
Not every parameter starts a transformation. A video needs an image format to return a frame, and a video request that sets another transformation parameter without format returns 400. Setting format on a file that is neither an image nor a video also returns 400.
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | Complete media representation | The attachment was returned |
| 206 | Selected media bytes | One range over the stored bytes is satisfiable |
| 400 | Bad Request | The path, a dimension, the format or the transformation is invalid, or the transformation failed |
| 404 | This content is no longer available. | The signed attachment URL policy refuses the signature, or the object does not exist under enforce |
| 416 | empty | A range over the stored bytes is unsatisfiable |
| 503 | Service Unavailable | Fluxer has no transformation capacity free |
| 504 | Gateway Timeout | The transformation timed out |
Get signed external media
Section titled “Get signed external media”GET/external/{signature}/{target}Returns a third-party file through Fluxer, optionally transformed. The HTTP API returns these URLs in proxy_url on embed media, proxy_icon_url on embed authors and footers, and proxy_url and proxy_src on GIF results. Use each URL exactly as the API returns it, and don't build /external/ paths yourself.
The signature covers only the target and works until FLUXER_MEDIA_PROXY_SECRET_KEY changes. Fluxer fetches the target with the user agent Mozilla/5.0 (compatible; Fluxerbot/1.0; +https://fluxer.com) and follows at most five redirects to public http or https addresses.
Query parameters
Section titled “Query parameters”| Field | Type | Description |
|---|---|---|
| width? | integer | The output width in pixels, up to the decoded edge bound |
| height? | integer | The output height in pixels, up to the same bound |
| format? | string | The output format |
| quality? | string | The encoder quality profile |
| animated? | boolean | Whether animated output is requested |
| download? | boolean | Whether the response has attachment disposition |
When no transformation runs, Fluxer forwards Range to the origin, which can answer 200 or 206.
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | Complete external representation | The origin returned the file |
| 206 | Selected external bytes | The origin or Fluxer answered a range |
| 400 | Bad Request | The path, target, redirect or transformation is invalid or not allowed |
| 401 | Unauthorized | The signature is invalid |
| 413 | Payload Too Large | The origin sent more than 500 MiB |
| 416 | empty | A local range is unsatisfiable |
| 502 | Bad Gateway | The origin failed, was unreachable or redirected too many times |
| 503 | Service Unavailable | Fluxer could not allocate a buffer for the origin body or has no transformation capacity free |
| 504 | Gateway Timeout | The transformation timed out |
Most origin 4xx statuses, such as 403, 404 and 429, come back with the same status and the body Upstream fetch failed. Other origin errors become 502.
Get theme CSS
Section titled “Get theme CSS”GET/themes/{path}Returns a theme stylesheet written by the themes resource as text/css; charset=utf-8. The path must end in .css.
Get entrance sound
Section titled “Get entrance sound”GET/entrance-sounds/{user_id}/{filename}Returns the audio of an entrance sound. filename is {hash}.{ext} with the hash from the API and an extension of mp3, ogg, m4a or wav.
Image asset contract
Section titled “Image asset contract”The image routes below all take the same query parameters and return the same statuses. Build the URL from the endpoints.media base URL, the route path, the hash from the resource object and an extension. An a_ hash means the asset is animated.
The extension sets the output format and is one of png, jpg, jpeg, webp, gif, apng, avif, heic, heif, jxl or svg, in upper or lower case. Each route uses one size class.
Query parameters
Section titled “Query parameters”| Field | Type | Description |
|---|---|---|
| size? | integer | The square edge in pixels, snapped to the size ladder (default 128) |
| format? | string | The output format, also accepted as fmt, where auto uses the path extension |
| quality? | string | The encoder quality profile, defaulting to high |
| animated? | boolean | Whether animated output is requested, defaulting to true for an a_ hash |
| download? | boolean | Whether the response has attachment disposition |
An unknown or invalid query value uses the default.
Response
Section titled “Response”| Status | Body | Condition |
|---|---|---|
| 200 | Complete asset representation | The asset was returned |
| 206 | Selected asset bytes | One range over the stored bytes is satisfiable |
| 400 | Bad Request | The path makes an unsafe storage key |
| 404 | Not Found | The path is not a valid asset path or the asset does not exist |
| 416 | empty | A range over the stored bytes is unsatisfiable |
| 500 | Transcode Failed | A required transcode failed and the source can't be shown as it is |
| 503 | Service Unavailable | Fluxer has no transformation capacity free |
| 504 | Gateway Timeout | The transformation timed out |
Get user avatar
Section titled “Get user avatar”GET/avatars/{user_id}/{hash}.{ext}Returns a user avatar in the icon size class.
Get guild icon
Section titled “Get guild icon”GET/icons/{guild_id}/{hash}.{ext}Returns a guild icon in the icon size class.
Get instance branding
Section titled “Get instance branding”GET/branding/{entity_id}/{hash}.{ext}Returns an instance branding image written by Create branding asset, in the branding size class. Without size, it returns the image at its original size.
Get instance sign-in backdrop
Section titled “Get instance sign-in backdrop”GET/branding-backdrops/{entity_id}/{hash}.{ext}Returns the sign-in backdrop written by Create branding asset with the sign_in_backdrop kind, in the branding size class. Without size, it returns the image at its original size.
Get owner banner
Section titled “Get owner banner”GET/banners/{owner_id}/{hash}.{ext}Returns a user or guild banner in the banner size class.
Get guild splash
Section titled “Get guild splash”GET/splashes/{guild_id}/{hash}.{ext}Returns a guild splash in the banner size class.
Get guild embed splash
Section titled “Get guild embed splash”GET/embed-splashes/{guild_id}/{hash}.{ext}Returns a guild embed splash in the banner size class.
Get role icon
Section titled “Get role icon”GET/role-icons/{role_id}/{hash}.{ext}Returns a role icon in the role icon size class. Role icons are never animated.
Get guild member avatar
Section titled “Get guild member avatar”GET/guilds/{guild_id}/users/{user_id}/avatars/{hash}.{ext}Returns a member's guild avatar in the icon size class.
Get guild member banner
Section titled “Get guild member banner”GET/guilds/{guild_id}/users/{user_id}/banners/{hash}.{ext}Returns a member's guild banner in the banner size class.
Get emoji image
Section titled “Get emoji image”GET/emojis/{emoji_id}.{ext}Returns an emoji cropped to a square in the emoji size class, static unless you pass animated=true. The ID never has an a_ prefix.
Get sticker image
Section titled “Get sticker image”GET/stickers/{sticker_id}.{ext}Returns a sticker cropped to a square in the sticker size class. Output is always WebP and ignores format, except that an animated GIF stays GIF when animated=true. The ID never has an a_ prefix.
Get static object
Section titled “Get static object”GET/{key}Returns a file from the static bucket, such as a default avatar or a client bundle. The route exists only on a Media Proxy in static mode. The whole path is the storage key, and query parameters are ignored.
Operator and internal endpoints
Section titled “Operator and internal endpoints”These paths are for the instance itself and aren't published by instance discovery.
| Path | Method | Description |
|---|---|---|
/_health | GET | Returns 200 while the process is running |
/_metrics | GET | Returns Prometheus metrics to loopback requests and 403 to anything else |
/_metadata | POST | Returns media metadata for the HTTP API |
/_sniff | POST | Returns the media type of a staged upload for the HTTP API |
/_thumbnail | POST | Makes a WebP thumbnail of a staged upload for the HTTP API |
/_frames | POST | Extracts one JPEG video frame for the HTTP API |
/_strip | POST | Removes metadata from an uploaded image, video or audio file for the HTTP API |
/_audio_duration | POST | Returns the length of an uploaded audio file for the HTTP API |
The six POST endpoints need Authorization: Bearer {FLUXER_MEDIA_PROXY_SECRET_KEY} and return 401 without it.