> ## Documentation Index
> Fetch the complete documentation index at: https://api.fanvue.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Get media by UUID
> Returns a specific media item by its UUID for the authenticated user.
For media with status other than FINALISED, only uuid and status are returned.
For FINALISED media, all details including variants are included, plus a
`tags` field containing structured AI content tags when the owning
creator has AI content tagging enabled and the media has been processed
(`null` otherwise).
Media URLs are only available through variants.
Specify the `variants` query parameter (e.g., `?variants=main,thumbnail,blurred`)
to include them in the response. Without this parameter, the `variants` field
will be an empty array and no media URLs will be returned.
**Required scope**
* `read:media` — Access media files, images, videos, and other content assets.
## OpenAPI
````yaml /openapi.json get /media/{uuid}
openapi: 3.1.0
info:
title: Fanvue API
version: '0.1'
servers: []
security: []
paths:
/media/{uuid}:
get:
summary: Get media by UUID
description: |-
Returns a specific media item by its UUID for the authenticated user.
For media with status other than FINALISED, only uuid and status are returned.
For FINALISED media, all details including variants are included, plus a
`tags` field containing structured AI content tags when the owning
creator has AI content tagging enabled and the media has been processed
(`null` otherwise).
Media URLs are only available through variants.
Specify the `variants` query parameter (e.g., `?variants=main,thumbnail,blurred`)
to include them in the response. Without this parameter, the `variants` field
will be an empty array and no media URLs will be returned.
operationId: getUserMediaByUuid
parameters:
- $ref: '#/components/parameters/ApiVersionHeader'
- schema:
type: string
format: uuid
required: true
name: uuid
in: path
- schema:
type: string
format: uuid
description: >-
UUID of the user to check media purchase against. When provided,
the media item will include a purchasedByFan boolean indicating if
that user has purchased it.
required: false
description: >-
UUID of the user to check media purchase against. When provided, the
media item will include a purchasedByFan boolean indicating if that
user has purchased it.
name: purchasedBy
in: query
- schema:
type: array
items:
$ref: '#/components/schemas/MediaVariantType'
description: Comma-separated list of media variant types
required: false
name: variants
in: query
style: form
explode: false
responses:
'200':
description: Media item
content:
application/json:
schema:
anyOf:
- type: object
properties:
uuid:
type: string
format: uuid
status:
type: string
enum:
- created
- processing
- ready
- error
required:
- uuid
- status
- type: object
properties:
uuid:
type: string
format: uuid
status:
type: string
enum:
- created
- processing
- ready
- error
createdAt:
type:
- string
- 'null'
format: date
url:
type: string
caption:
type:
- string
- 'null'
description:
type:
- string
- 'null'
name:
type:
- string
- 'null'
mediaType:
type: string
enum:
- image
- video
- audio
- document
recommendedPrice:
type:
- number
- 'null'
variants:
type: array
items:
type: object
properties:
uuid:
type: string
format: uuid
variantType:
type: string
enum:
- blurred
- main
- thumbnail
- thumbnail_gallery
displayPosition:
type: number
url:
type: string
width:
type:
- number
- 'null'
height:
type:
- number
- 'null'
lengthMs:
type:
- number
- 'null'
required:
- uuid
- variantType
- displayPosition
- width
- height
- lengthMs
purchasedByFan:
type: boolean
tags:
type:
- object
- 'null'
properties:
description:
type:
- string
- 'null'
description: AI-generated natural language description
tags:
type: array
items:
type: string
description: General content tags
nsfwCategory:
type: array
items:
type: string
description: NSFW classification labels
sexActs:
type: array
items:
type: string
bodyParts:
type: array
items:
type: string
people:
type: array
items:
type: string
sexObjects:
type: array
items:
type: string
setting:
type: array
items:
type: string
description: Scene / environment tags
position:
type: array
items:
type: string
skinColor:
type: array
items:
type: string
bodyType:
type: array
items:
type: string
hairColor:
type: array
items:
type: string
otherTags:
type: array
items:
type: string
importantTags:
type: array
items:
type: string
description: Tags the model marked as salient
isNsfw:
type: boolean
mediaType:
type: string
enum:
- image
- video
required:
- description
- tags
- nsfwCategory
- sexActs
- bodyParts
- people
- sexObjects
- setting
- position
- skinColor
- bodyType
- hairColor
- otherTags
- importantTags
- isNsfw
- mediaType
description: >-
Structured AI content tags. Only populated when the
owning creator has AI content tagging enabled and the
media has been processed; null otherwise.
required:
- uuid
- status
- createdAt
- caption
- description
- name
- mediaType
- recommendedPrice
example:
uuid: d4e5f6a7-8b9c-0d1e-2f3a-4b5c6d7e8f9a
status: ready
createdAt: '2024-01-15T00:00:00.000Z'
caption: Sunset at the beach
description: null
name: beach-sunset.jpg
mediaType: image
recommendedPrice: null
tags:
description: Behind-the-scenes shot at sunset on a beach.
tags:
- beach
- sunset
- outdoors
nsfwCategory: []
sexActs: []
bodyParts: []
people:
- solo woman
sexObjects: []
setting:
- beach
- sunset
position: []
skinColor: []
bodyType: []
hairColor:
- blonde
otherTags: []
importantTags:
- beach
isNsfw: false
mediaType: image
variants:
- uuid: c9d0e1f2-3a4b-5c6d-7e8f-9a0b1c2d3e4f
variantType: main
displayPosition: 0
url: >-
https://media.fanvue.com/main/d4e5f6a7-8b9c-0d1e-2f3a-4b5c6d7e8f9a.jpg
width: 3840
height: 2160
lengthMs: null
- uuid: d0e1f2a3-4b5c-6d7e-8f9a-0b1c2d3e4f5a
variantType: thumbnail
displayPosition: 1
url: >-
https://media.fanvue.com/thumb/d4e5f6a7-8b9c-0d1e-2f3a-4b5c6d7e8f9a.jpg
width: 320
height: 180
lengthMs: null
- uuid: e1f2a3b4-5c6d-7e8f-9a0b-1c2d3e4f5a6b
variantType: thumbnail_gallery
displayPosition: 2
url: >-
https://media.fanvue.com/gallery/d4e5f6a7-8b9c-0d1e-2f3a-4b5c6d7e8f9a.jpg
width: 400
height: 300
lengthMs: null
- uuid: f2a3b4c5-6d7e-8f9a-0b1c-2d3e4f5a6b7c
variantType: blurred
displayPosition: 3
url: >-
https://media.fanvue.com/blur/d4e5f6a7-8b9c-0d1e-2f3a-4b5c6d7e8f9a.jpg
width: 3840
height: 2160
lengthMs: null
'400':
description: Bad Request - API version not supported OR validation failed
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/UnsupportedVersionError'
- $ref: '#/components/schemas/ValidationError'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/UnauthorizedResponse'
'404':
$ref: '#/components/responses/NotFoundResponse'
'410':
$ref: '#/components/responses/SunsetVersionResponse'
'429':
$ref: '#/components/responses/RateLimitResponse'
security:
- BearerAuth:
- read:media
components:
parameters:
ApiVersionHeader:
name: X-Fanvue-API-Version
in: header
required: true
schema:
type: string
default: '2025-06-26'
example: '2025-06-26'
description: API version to use for the request
schemas:
MediaVariantType:
type: string
enum:
- blurred
- main
- thumbnail
- thumbnail_gallery
description: The type of media variant
UnsupportedVersionError:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
- message
description: API version not supported
ValidationError:
type: object
properties:
errors:
type: array
items:
type: string
required:
- errors
description: Request validation failed
responses:
UnauthorizedResponse:
description: Unauthorized Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
required:
- error
NotFoundResponse:
description: Not Found Response
content:
application/json:
schema:
type: object
properties:
message:
type: string
required:
- message
SunsetVersionResponse:
description: API version no longer supported (sunset)
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
nextVersion:
type: string
required:
- error
- message
RateLimitResponse:
description: Too many requests - rate limit exceeded
headers:
Retry-After:
description: Number of seconds to wait before retrying the request
schema:
type: integer
X-RateLimit-Limit:
description: The maximum number of requests allowed in the current window
schema:
type: integer
X-RateLimit-Remaining:
description: The number of requests remaining in the current window
schema:
type: integer
X-RateLimit-Reset:
description: The Unix timestamp (seconds) when the rate limit window resets
schema:
type: integer
content:
application/json:
schema:
type: object
properties:
error:
type: string
required:
- error
securitySchemes:
BearerAuth:
type: oauth2
description: >-
OAuth 2.0 access token, presented as a JWT bearer token in the
`Authorization` header. Obtain a token via the authorization-code flow;
the scopes granted to the token determine which operations it may call.
flows:
authorizationCode:
authorizationUrl: https://auth.fanvue.com/oauth2/auth
tokenUrl: https://auth.fanvue.com/oauth2/token
refreshUrl: https://auth.fanvue.com/oauth2/token
scopes:
read:self: >-
Access your own user profile information, including basic account
details and settings.
read:chat: >-
Read chat conversations, messages, and chat-related data. This
includes viewing chat lists and message history.
write:chat: >-
Create new chats and send messages. This scope is required for any
chat-related actions that modify data.
read:experience: >-
Exchange a fan's experience token for the resolved experience and
the fan's identity, so an embedded fan-facing experience can
render the right content.
write:experience: >-
Request that the creator publish or unpublish a fan-facing
experience. The app mints a request token; the creator confirms
and Fanvue performs the change.
read:fan: Access fan-related data and information within the platform.
read:post: Read posts, including post details, comments, likes, and tips.
write:post: Create, edit, and manage posts and content on behalf of users.
read:media: Access media files, images, videos, and other content assets.
write:media: >-
Upload, modify, and manage media files and content assets. Also
required for vault folder management.
read:creator: >-
Access creator profiles, content, and creator-specific
information.
write:creator: Modify creator profiles, settings, and creator-specific data.
read:insights: >-
Access analytics, metrics, and insights data for performance
tracking.
read:tracking_links: >-
Read tracking links and the users associated with them, including
per-user tracking metadata.
write:tracking_links: Create and delete tracking links.
read:agency: Read agency information, including the agency's team members.
write:agency: >-
Manage agency team members and invites, including inviting new
team members and creators.
````