murdle/fluxer
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
fluxer/fluxer_docs/resources/media_proxy.mdx
Hampus Kraft d5abd1a7e4
refactor progress
2026-02-17 12:22:36 +00:00

343 lines
10 KiB
Plaintext
Raw Permalink Blame History

---
title: 'Media proxy'
description: 'Object schemas used by the Fluxer media proxy.'
---
The media proxy serves all user-generated content for Fluxer, including avatars, icons, attachments, emojis, stickers, and external media. All public routes are served from `https://fluxerusercontent.com`.
See the [Media Proxy API reference](/media-proxy-api) for the full list of available endpoints.
## Field notation
Resource tables use a compact notation:
| Notation | Meaning |
|----------|----------|
| `field` | Required field |
| `field?` | Optional field (may be omitted) |
| `?type` | Nullable (value can be `null`) |
## Enums
<a id="imagesizeenum"></a>
### ImageSizeEnum
Allowed image sizes in pixels.
**Related endpoints**
- [`GET /avatars/{id}/{filename}`](/media-proxy-api/images/get-user-or-guild-avatar)
- [`GET /icons/{id}/{filename}`](/media-proxy-api/images/get-guild-icon)
- [`GET /banners/{id}/{filename}`](/media-proxy-api/images/get-user-or-guild-banner)
- [`GET /emojis/{id}`](/media-proxy-api/content/get-custom-emoji)
- [`GET /stickers/{id}`](/media-proxy-api/content/get-sticker)
- [`GET /attachments/{channel_id}/{attachment_id}/{filename}`](/media-proxy-api/content/get-message-attachment)
| Value | Description |
|-------|-------------|
| `16` | 16 pixels |
| `20` | 20 pixels |
| `22` | 22 pixels |
| `24` | 24 pixels |
| `28` | 28 pixels |
| `32` | 32 pixels |
| `40` | 40 pixels |
| `44` | 44 pixels |
| `48` | 48 pixels |
| `56` | 56 pixels |
| `60` | 60 pixels |
| `64` | 64 pixels |
| `80` | 80 pixels |
| `96` | 96 pixels |
| `100` | 100 pixels |
| `128` | 128 pixels |
| `160` | 160 pixels |
| `240` | 240 pixels |
| `256` | 256 pixels |
| `300` | 300 pixels |
| `320` | 320 pixels |
| `480` | 480 pixels |
| `512` | 512 pixels |
| `600` | 600 pixels |
| `640` | 640 pixels |
| `1024` | 1024 pixels |
| `1280` | 1280 pixels |
| `1536` | 1536 pixels |
| `2048` | 2048 pixels |
| `3072` | 3072 pixels |
| `4096` | 4096 pixels |
<a id="imageformatenum"></a>
### ImageFormatEnum
Allowed image output formats.
**Related endpoints**
- [`GET /avatars/{id}/{filename}`](/media-proxy-api/images/get-user-or-guild-avatar)
- [`GET /external/{signature}/{timestamp}/{url}`](/media-proxy-api/external/proxy-external-media)
| Value | Description |
|-------|-------------|
| `png` | PNG format |
| `jpg` | JPEG format |
| `jpeg` | JPEG format (alias) |
| `webp` | WebP format (default, recommended) |
| `gif` | GIF format (for animated images) |
<a id="imagequalityenum"></a>
### ImageQualityEnum
Image quality levels.
**Related endpoints**
- [`GET /avatars/{id}/{filename}`](/media-proxy-api/images/get-user-or-guild-avatar)
- [`GET /external/{signature}/{timestamp}/{url}`](/media-proxy-api/external/proxy-external-media)
| Value | Description |
|-------|-------------|
| `high` | High quality compression, good balance of size and fidelity (default for most images) |
| `low` | Lower quality for smaller file sizes, suitable for thumbnails |
| `lossless` | No quality loss, largest file sizes (default for external media) |
---
## Query parameter schemas
<a id="imagequeryparams"></a>
## ImageQueryParams
Standard query parameters for image routes.
**Related endpoints**
- [`GET /avatars/{id}/{filename}`](/media-proxy-api/images/get-user-or-guild-avatar)
- [`GET /icons/{id}/{filename}`](/media-proxy-api/images/get-guild-icon)
- [`GET /emojis/{id}`](/media-proxy-api/content/get-custom-emoji)
| Field | Type | Description |
|-------|------|-------------|
| size? | [ImageSizeEnum](#imagesizeenum) | Target image size in pixels. Default: `128` |
| format? | [ImageFormatEnum](#imageformatenum) | Output image format. Default: `webp` |
| quality? | [ImageQualityEnum](#imagequalityenum) | Image quality level. Default: `high` |
| animated? | boolean | Whether to return animated images (GIF, APNG) if available. Default: `false` |
<a id="externalmediaqueryparams"></a>
## ExternalMediaQueryParams
Query parameters for the external media proxy.
**Related endpoints**
- [`GET /external/{signature}/{timestamp}/{url}`](/media-proxy-api/external/proxy-external-media)
| Field | Type | Description |
|-------|------|-------------|
| width? | integer | Target width in pixels (1-4096). If only width is specified, height is calculated to maintain aspect ratio. |
| height? | integer | Target height in pixels (1-4096). If only height is specified, width is calculated to maintain aspect ratio. |
| format? | [ImageFormatEnum](#imageformatenum) | Output image format. If not specified, the original format is preserved. |
| quality? | [ImageQualityEnum](#imagequalityenum) | Image quality level. Default: `lossless` |
| animated? | boolean | Whether to preserve animation for GIF images. Default: `false` |
---
## Response schemas
<a id="metadataresponse"></a>
## MetadataResponse
Response from metadata extraction.
**Related endpoints**
- [`POST /_metadata`](/media-proxy-api/internal/extract-media-metadata)
| Field | Type | Description |
|-------|------|-------------|
| format | string | Detected media format (e.g., `png`, `jpeg`, `gif`, `mp4`) |
| content_type | string | MIME content type |
| content_hash | string | SHA-256 hash of the content |
| size | integer | File size in bytes |
| width? | integer | Image or video width in pixels |
| height? | integer | Image or video height in pixels |
| duration? | number | Video or audio duration in seconds |
| placeholder? | string | BlurHash placeholder string for progressive loading |
| base64? | string | Base64-encoded content (if `with_base64` was requested) |
| animated? | boolean | Whether the image is animated (GIF, APNG) |
| nsfw | boolean | Whether the content was flagged as NSFW |
| nsfw_probability? | number | NSFW probability score (0-1) |
| nsfw_predictions? | map&lt;string, number&gt; | Per-category NSFW predictions |
<a id="thumbnailresponse"></a>
## ThumbnailResponse
Response from thumbnail generation.
**Related endpoints**
- [`POST /_thumbnail`](/media-proxy-api/internal/generate-video-thumbnail)
| Field | Type | Description |
|-------|------|-------------|
| thumbnail | string | Base64-encoded thumbnail image (JPEG) |
| mime_type | string | MIME type of the thumbnail (always `image/jpeg`) |
<a id="frameresponse"></a>
## FrameResponse
Response from frame extraction.
**Related endpoints**
- [`POST /_frames`](/media-proxy-api/internal/extract-video-frames)
| Field | Type | Description |
|-------|------|-------------|
| frames | [ExtractedFrame](#extractedframe)[] | Extracted video frames |
<a id="extractedframe"></a>
## ExtractedFrame
Single extracted video frame.
| Field | Type | Description |
|-------|------|-------------|
| timestamp | number | Frame timestamp in seconds |
| mime_type | string | MIME type of the frame image |
| base64 | string | Base64-encoded frame image |
---
## Request schemas
<a id="metadatarequest"></a>
### MetadataRequest
Discriminated union for metadata extraction requests. The `type` field determines which variant is used.
**Related endpoints**
- [`POST /_metadata`](/media-proxy-api/internal/extract-media-metadata)
| Type | Description |
|------|-------------|
| [MetadataRequestExternal](#metadatarequestexternal) | Fetch metadata from an external URL |
| [MetadataRequestUpload](#metadatarequestupload) | Get metadata from an uploaded file |
| [MetadataRequestBase64](#metadatarequestbase64) | Get metadata from base64-encoded data |
| [MetadataRequestS3](#metadatarequests3) | Get metadata from an S3 object |
<a id="metadatarequestexternal"></a>
## MetadataRequestExternal
Metadata request for external URLs.
| Field | Type | Description |
|-------|------|-------------|
| type | string | Must be `"external"` |
| url | string | External URL to fetch |
| with_base64? | boolean | Include base64-encoded content in response |
| isNSFWAllowed | boolean | Whether NSFW content is permitted |
<a id="metadatarequestupload"></a>
## MetadataRequestUpload
Metadata request for uploaded files.
| Field | Type | Description |
|-------|------|-------------|
| type | string | Must be `"upload"` |
| upload_filename | string | Filename in the uploads bucket |
| isNSFWAllowed | boolean | Whether NSFW content is permitted |
<a id="metadatarequestbase64"></a>
## MetadataRequestBase64
Metadata request for base64-encoded data.
| Field | Type | Description |
|-------|------|-------------|
| type | string | Must be `"base64"` |
| base64 | string | Base64-encoded media data |
| isNSFWAllowed | boolean | Whether NSFW content is permitted |
<a id="metadatarequests3"></a>
## MetadataRequestS3
Metadata request for S3 objects.
| Field | Type | Description |
|-------|------|-------------|
| type | string | Must be `"s3"` |
| bucket | string | S3 bucket name |
| key | string | S3 object key |
| with_base64? | boolean | Include base64-encoded content in response |
| isNSFWAllowed | boolean | Whether NSFW content is permitted |
<a id="framerequest"></a>
### FrameRequest
Discriminated union for frame extraction requests. The `type` field determines which variant is used.
**Related endpoints**
- [`POST /_frames`](/media-proxy-api/internal/extract-video-frames)
| Type | Description |
|------|-------------|
| [FrameRequestUpload](#framerequestupload) | Extract frames from an uploaded file |
| [FrameRequestS3](#framerequests3) | Extract frames from an S3 object |
<a id="framerequestupload"></a>
## FrameRequestUpload
Frame extraction request for uploaded files.
| Field | Type | Description |
|-------|------|-------------|
| type | string | Must be `"upload"` |
| upload_filename | string | Filename in the uploads bucket |
<a id="framerequests3"></a>
## FrameRequestS3
Frame extraction request for S3 objects.
| Field | Type | Description |
|-------|------|-------------|
| type | string | Must be `"s3"` |
| bucket | string | S3 bucket name |
| key | string | S3 object key |
<a id="thumbnailrequestbody"></a>
## ThumbnailRequestBody
Request body for thumbnail generation.
**Related endpoints**
- [`POST /_thumbnail`](/media-proxy-api/internal/generate-video-thumbnail)
| Field | Type | Description |
|-------|------|-------------|
| upload_filename | string | Filename of the uploaded video in the uploads bucket |
Reference in New Issue View Git Blame Copy Permalink