Media Controller

The Media Controller manages all media-related operations in AdmiralCloud, including file retrieval, creation, updates, deletion, uploads, and downloads. It serves as the primary interface for working with media files across different formats and types (images, videos, audio, documents).

Key capabilities:

Retrieve media items from containers with flexible filtering options
Create media entries for new uploads or transcoding operations
Update media properties and usage types
Delete media items with dependency checking
Import files from external URLs
Generate secure download links with customizable expiration
Access preview images with automatic resizing

Important notes:

Media operations respect user permissions for access control
For local file uploads, use the S3 Controller
Original media files are protected and can only be deleted through container deletion

Reference

Find Media

Retrieve all media items within a specific container

Returns an array of media items associated with a mediaContainer. By default, only media with valid file sizes (> 0 bytes) is returned, filtering out items that are still processing or have failed. The response includes comprehensive metadata about each media item including technical specifications, processing status, and storage details.

GET/v5/media/:mediaContainerId/:mediaId

Request Parameters

Field	Type	Required	Description
forceFind	boolean	✗	If true, also returns media with fileSize = 0 (processing/failed items)
formatIds	array	✗	Filter by specific format IDs
mediaContainerId	integer	✓	ID of the mediaContainer to fetch media from
mediaId	integer	✗	Optional: fetch only this specific media item Deprecated

Response

Field	Type	Description
additionalSettings	object	Extended configuration for media processing
└ contactId	integer	Associated contact ID
└ isAdditionalDocument	boolean	Mark as supplementary document
└ mediaContainerId	integer	Parent mediaContainer for subtitle files
└ subtitleLanguage	iso-639-2	Language code for subtitle files (ISO 639-2)
└ thumbnailsOnly	boolean	Skip video transcoding, only generate thumbnails Experimental
└ thumbnailVersion	integer	Thumbnail generation algorithm: 1 = legacy, 2 = current (default) ⟨⟩ range: 1 to 2
└ published	boolean	Publication status for subtitle files Experimental
└ ignoreMetadata	object	Disable automatic metadata extraction
└ container_name	boolean	Skip title extraction from IPTC/EXIF
└ container_description	boolean	Skip description extraction from IPTC/EXIF
└ keywordsAsTags	boolean	Do not convert IPTC keywords to tags
└ all	boolean	Skip all automatic metadata extraction
└ originalFileExtension	fileExtension	Original file extension (e.g., "docx", "xlsx"). Helps with Office document detection
└ disableAutoGenerate	boolean	Prevent automatic preview/thumbnail generation
└ replacement	object	Configuration for file replacement/versioning
└ id	integer	ID of the media being replaced
└ skipVersion	boolean	If true, replace without creating version history
additionalTechData	object	Technical analysis results (color profiles, histogram data, etc.). Please note that all properties are EXPERIMENTAL and may change or removed in future versions. Experimental
└ uploadSpeed	float	Upload speed in bytes per second
└ repairMimeType	string	Repaired MIME type if the original was incorrect
└ layers	integer	Number of layers in the image (if applicable)
└ quality	float	Estimated quality of the media (0-100 scale)
└ megaPixels	integer	Total megapixels in the image
└ alphatransparency	integer	Alpha transparency level (0-255)
└ laplacianBlurFactor	float	Laplacian blur factor for image sharpness detection
└ colorDetection	array	Detected dominant colors in the image
└ pixels	integer	Number of pixels matching this color
└ srgb	array	sRGB color values [R, G, B]
└ weight	float	Weight of this color in the image (0-1 scale)
└ width	integer	Document width in pixels
└ height	integer	Document height in pixels
└ pages	integer	Number of pages in the document (if applicable)
└ pageRot	integer	Rotation of the first page in degrees (0, 90, 180, 270)
└ pageSize	string	Page size in points (e.g., "595 x 842 pts (A4)")
└ encrypted	string	Indicates if the PDF is encrypted ≡ allowed values: yesno
└ pdfVersion	string	PDF version (e.g., "1.4")
└ audioStreamMapping	integer	TBC
analyzerResults	object	AI analysis results (object detection, face recognition, OCR).
audioBitrate	integer	Audio bitrate in bits per second
audioCodec	string	Audio codec (e.g., aac, mp3). For video and audio files
bits_per_sample	integer	Bit depth: color depth for images/video, sample size for audio
bucket	string	S3 bucket name (immutable) Will be removed in future versions without prior notice
channel_layout	string	Audio channel configuration (e.g., "stereo", "5.1")
channels	integer	Number of audio channels (1 = mono, 2 = stereo, etc.)
checksum	string	File checksum (auto-calculated)
colorProfile	string	Current ICC color profile, (e.g. Apple RGB, sRGB IEC61966-2.1, etc.)
colorProfileOriginal	string	Original ICC color profile before processing
colorSpace	string	Color space (e.g., rgb, srgb, cmyk, etc)
createdAt	string	Creation timestamp (ISO 8601)
creatorId	integer	User ID who created this media
customerId	integer	Customer account ID Will be removed in future versions without prior notice
display_aspect_ratio	string	Display aspect ratio (videos only). E.g., "16:9", "4:3"
dryRun	boolean	Indicates this was a validation-only request
duration	integer	Duration in milliseconds (video/audio only)
fileExtension	string	File extension (auto-detected)
fileName	string	Stored original filename
fileSize	integer	Actual file size in bytes
flag	integer	0 = active, 1 = no on S3, 2 = transcoding pending, 3 = upload pending, 6 = transcoding ended with error, probing failed – do not use for transcodings ≡ allowed values: 01234569
formatId	integer	Format ID of this media version
fps	number	Frames per second (videos only)
hasThumbnailVersions	boolean	True, if multiple thumbnail sizes are available
height	integer	Height in pixels (auto-detected)
id	integer	Unique media ID
isInterlaced	integer	Interlacing detection: 1 = interlaced, 2 = progressive
malwareScan	string	Malware scan status: "clean", "infected", "error"
malwareScanResult	string	Detailed malware scan results/threats found
malwareScanVersion	string	Antivirus engine version used
mediaContainerId	integer	ID of the mediaContainer this media belongs to
offsiteBackup	integer	Timestamp of the last offsite backup for this media item
orientation	integer	EXIF orientation (images): 3 = 180°, 6 = 90° CCW, 8 = 90° CW
phash	string	Perceptual hash for image similarity detection Is only active for legacy media. Will be removed in future versions without prior notice
provider	string	Storage provider (immutable) Will be removed in future versions without prior notice
region	string	AWS region (immutable) Will be removed in future versions without prior notice
resolutionUnit	integer	Resolution unit: 1 = none, 2 = inches, 3 = centimeters
s3Key	string	Unique S3 object key (immutable). Format: customer_ID/UUID Will be removed in future versions without prior notice
s3fileSize	integer	Total S3 storage used including all versions (bytes)
s3fileSizeLogDate	integer	Unix timestamp when s3fileSize was last calculated
sampleRate	integer	Audio sample rate in Hz (typically 48000 or 44100)
sample_aspect_ratio	string	Pixel aspect ratio (videos only). Usually "1:1"
source	string	Origin of this media item ≡ allowed values: usertranscoder
subtitleId	integer	ID of burned-in subtitle (if any)
totalTranscodingTime	integer	Cumulative transcoding duration in milliseconds. For original media, this is the upload time
type	string	Detected media type of this item ≡ allowed values: imagevideoaudiodocument
updatedAt	string	Last modification timestamp (ISO 8601)
uploadId	string	Batch upload identifier (same for all files uploaded together)
uploadLog	array	Logs of the upload
└ ip	ip	Anonymized IP address of the uploader
└ type	string	Type of the upload log entry ≡ allowed values: cloudtrails3
└ eventName	string	Event name from the upload log (e.g., CreateMultipartUpload) ≡ allowed values: CreateMultipartUploadCompleteMultipartUploadObjectCreated:CompleteMultipartUploadPutObjectUploadPart
└ eventTime	string	Timestamp of the upload event (ISO 8601 format)
usage	string	Current usage type of this media item ≡ allowed values: previewtranscodinghlsthumbnailuploadedThumbnailrawfileinterimspritedownloadsocialmediareplacementoutdatedlogoavatarwelcomeBackgroundcontactPicturesubtitletagImporteditscenesfacePreviewwaveform
videoBitrate	integer	Video bitrate in bits per second
videoCodec	string	Video codec (e.g., h264, h265). Also set for images
width	integer	Width in pixels (auto-detected)
xResolution	integer	Horizontal resolution (DPI/PPI)
yResolution	integer	Vertical resolution (DPI/PPI)

FindBatch Media

Retrieve media items from multiple containers in a single request

Efficiently fetch media items across multiple mediaContainers in one API call. This endpoint is optimized for bulk operations where you need to retrieve media from various containers simultaneously. Results can be filtered by format, type, or usage to get exactly the media versions you need.

POST/v5/media/findBatch

Request Parameters

Field	Type	Required	Description
formatIds	array	✗	Filter results to specific format IDs
ids	array	✗	Array of mediaContainer IDs to fetch media from
type	string	✗	Filter results by media type ≡ allowed values: imagevideoaudiodocument
usage	string	✗	Filter by usage type (e.g., "preview", "thumbnail") ≡ allowed values: previewtranscodinghlsthumbnailuploadedThumbnailrawfileinterimspritedownloadsocialmediareplacementoutdatedlogoavatarwelcomeBackgroundcontactPicturesubtitletagImporteditscenesfacePreviewwaveform

Response

Field	Type	Description
additionalSettings	object	Extended configuration for media processing
└ contactId	integer	Associated contact ID
└ isAdditionalDocument	boolean	Mark as supplementary document
└ mediaContainerId	integer	Parent mediaContainer for subtitle files
└ subtitleLanguage	iso-639-2	Language code for subtitle files (ISO 639-2)
└ thumbnailsOnly	boolean	Skip video transcoding, only generate thumbnails Experimental
└ thumbnailVersion	integer	Thumbnail generation algorithm: 1 = legacy, 2 = current (default) ⟨⟩ range: 1 to 2
└ published	boolean	Publication status for subtitle files Experimental
└ ignoreMetadata	object	Disable automatic metadata extraction
└ container_name	boolean	Skip title extraction from IPTC/EXIF
└ container_description	boolean	Skip description extraction from IPTC/EXIF
└ keywordsAsTags	boolean	Do not convert IPTC keywords to tags
└ all	boolean	Skip all automatic metadata extraction
└ originalFileExtension	fileExtension	Original file extension (e.g., "docx", "xlsx"). Helps with Office document detection
└ disableAutoGenerate	boolean	Prevent automatic preview/thumbnail generation
└ replacement	object	Configuration for file replacement/versioning
└ id	integer	ID of the media being replaced
└ skipVersion	boolean	If true, replace without creating version history
additionalTechData	object	Technical analysis results (color profiles, histogram data, etc.). Please note that all properties are EXPERIMENTAL and may change or removed in future versions. Experimental
└ uploadSpeed	float	Upload speed in bytes per second
└ repairMimeType	string	Repaired MIME type if the original was incorrect
└ layers	integer	Number of layers in the image (if applicable)
└ quality	float	Estimated quality of the media (0-100 scale)
└ megaPixels	integer	Total megapixels in the image
└ alphatransparency	integer	Alpha transparency level (0-255)
└ laplacianBlurFactor	float	Laplacian blur factor for image sharpness detection
└ colorDetection	array	Detected dominant colors in the image
└ pixels	integer	Number of pixels matching this color
└ srgb	array	sRGB color values [R, G, B]
└ weight	float	Weight of this color in the image (0-1 scale)
└ width	integer	Document width in pixels
└ height	integer	Document height in pixels
└ pages	integer	Number of pages in the document (if applicable)
└ pageRot	integer	Rotation of the first page in degrees (0, 90, 180, 270)
└ pageSize	string	Page size in points (e.g., "595 x 842 pts (A4)")
└ encrypted	string	Indicates if the PDF is encrypted ≡ allowed values: yesno
└ pdfVersion	string	PDF version (e.g., "1.4")
└ audioStreamMapping	integer	TBC
analyzerResults	object	AI analysis results (object detection, face recognition, OCR).
audioBitrate	integer	Audio bitrate in bits per second
audioCodec	string	Audio codec (e.g., aac, mp3). For video and audio files
bits_per_sample	integer	Bit depth: color depth for images/video, sample size for audio
bucket	string	S3 bucket name (immutable) Will be removed in future versions without prior notice
channel_layout	string	Audio channel configuration (e.g., "stereo", "5.1")
channels	integer	Number of audio channels (1 = mono, 2 = stereo, etc.)
checksum	string	File checksum (auto-calculated)
colorProfile	string	Current ICC color profile, (e.g. Apple RGB, sRGB IEC61966-2.1, etc.)
colorProfileOriginal	string	Original ICC color profile before processing
colorSpace	string	Color space (e.g., rgb, srgb, cmyk, etc)
createdAt	string	Creation timestamp (ISO 8601)
creatorId	integer	User ID who created this media
customerId	integer	Customer account ID Will be removed in future versions without prior notice
display_aspect_ratio	string	Display aspect ratio (videos only). E.g., "16:9", "4:3"
dryRun	boolean	Indicates this was a validation-only request
duration	integer	Duration in milliseconds (video/audio only)
fileExtension	string	File extension (auto-detected)
fileName	string	Stored original filename
fileSize	integer	Actual file size in bytes
flag	integer	0 = active, 1 = no on S3, 2 = transcoding pending, 3 = upload pending, 6 = transcoding ended with error, probing failed – do not use for transcodings ≡ allowed values: 01234569
formatId	integer	Format ID of this media version
fps	number	Frames per second (videos only)
hasThumbnailVersions	boolean	True, if multiple thumbnail sizes are available
height	integer	Height in pixels (auto-detected)
id	integer	Unique media ID
isInterlaced	integer	Interlacing detection: 1 = interlaced, 2 = progressive
malwareScan	string	Malware scan status: "clean", "infected", "error"
malwareScanResult	string	Detailed malware scan results/threats found
malwareScanVersion	string	Antivirus engine version used
mediaContainerId	integer	ID of the mediaContainer this media belongs to
offsiteBackup	integer	Timestamp of the last offsite backup for this media item
orientation	integer	EXIF orientation (images): 3 = 180°, 6 = 90° CCW, 8 = 90° CW
phash	string	Perceptual hash for image similarity detection Is only active for legacy media. Will be removed in future versions without prior notice
provider	string	Storage provider (immutable) Will be removed in future versions without prior notice
region	string	AWS region (immutable) Will be removed in future versions without prior notice
resolutionUnit	integer	Resolution unit: 1 = none, 2 = inches, 3 = centimeters
s3Key	string	Unique S3 object key (immutable). Format: customer_ID/UUID Will be removed in future versions without prior notice
s3fileSize	integer	Total S3 storage used including all versions (bytes)
s3fileSizeLogDate	integer	Unix timestamp when s3fileSize was last calculated
sampleRate	integer	Audio sample rate in Hz (typically 48000 or 44100)
sample_aspect_ratio	string	Pixel aspect ratio (videos only). Usually "1:1"
source	string	Origin of this media item ≡ allowed values: usertranscoder
subtitleId	integer	ID of burned-in subtitle (if any)
totalTranscodingTime	integer	Cumulative transcoding duration in milliseconds. For original media, this is the upload time
type	string	Detected media type of this item ≡ allowed values: imagevideoaudiodocument
updatedAt	string	Last modification timestamp (ISO 8601)
uploadId	string	Batch upload identifier (same for all files uploaded together)
uploadLog	array	Logs of the upload
└ ip	ip	Anonymized IP address of the uploader
└ type	string	Type of the upload log entry ≡ allowed values: cloudtrails3
└ eventName	string	Event name from the upload log (e.g., CreateMultipartUpload) ≡ allowed values: CreateMultipartUploadCompleteMultipartUploadObjectCreated:CompleteMultipartUploadPutObjectUploadPart
└ eventTime	string	Timestamp of the upload event (ISO 8601 format)
usage	string	Current usage type of this media item ≡ allowed values: previewtranscodinghlsthumbnailuploadedThumbnailrawfileinterimspritedownloadsocialmediareplacementoutdatedlogoavatarwelcomeBackgroundcontactPicturesubtitletagImporteditscenesfacePreviewwaveform
videoBitrate	integer	Video bitrate in bits per second
videoCodec	string	Video codec (e.g., h264, h265). Also set for images
width	integer	Width in pixels (auto-detected)
xResolution	integer	Horizontal resolution (DPI/PPI)
yResolution	integer	Vertical resolution (DPI/PPI)

Create Media

Initialize a new media entry for upload or transcoding

Creates a media record in the system as preparation for file upload or transcoding operations. The media entry serves as a placeholder that gets populated with actual file data through subsequent upload or transcoding processes. Includes automatic duplicate detection based on container, format, and subtitle combinations.

If you want to REPLACE an original file, please create a media with usage “replacement”. Then you can initiate a classic upload – make sure to call s3.success to start the actual replacement. Or use media.upload to upload the replacement file from a URL. The user needs permission “media_replaceOriginal” in order to use this function.

If you want to upload media, we recommend using the modern S3 createUpload approach.

POST/v5/media

Request Parameters

Field	Type	Required	Description
additionalSettings	object	✗	Extended configuration for media processing
└ contactId	integer	✗	Associated contact ID
└ isAdditionalDocument	boolean	✗	Mark as supplementary document
└ mediaContainerId	integer	✗	Parent mediaContainer for subtitle files
└ subtitleLanguage	iso-639-2	✗	Language code for subtitle files (ISO 639-2)
└ thumbnailsOnly	boolean	✗	Skip video transcoding, only generate thumbnails Experimental
└ thumbnailVersion	integer	✗	Thumbnail generation algorithm: 1 = legacy, 2 = current (default) ⟨⟩ range: 1 to 2
└ published	boolean	✗	Publication status for subtitle files Experimental
└ ignoreMetadata	object	✗	Disable automatic metadata extraction
└ container_name	boolean	✗	Skip title extraction from IPTC/EXIF
└ container_description	boolean	✗	Skip description extraction from IPTC/EXIF
└ keywordsAsTags	boolean	✗	Do not convert IPTC keywords to tags
└ all	boolean	✗	Skip all automatic metadata extraction
└ originalFileExtension	fileExtension	✗	Original file extension (e.g., "docx", "xlsx"). Helps with Office document detection
└ disableAutoGenerate	boolean	✗	Prevent automatic preview/thumbnail generation
└ replacement	object	✗	Configuration for file replacement/versioning
└ id	integer	✗	ID of the media being replaced
└ skipVersion	boolean	✗	If true, replace without creating version history
fileName	string	✗	Original filename to store with the media. Max 250 chars
formatId	integer	✗	Target format ID. Auto-set for source="user" uploads
mediaContainerId	integer	✓	ID of the mediaContainer to create a media entry for
mergeMetadata	object	✗	Metadata merge rules for replacements
└ mergeTags	boolean	✗	Combine new tags with existing ones
└ overwriteUserEditedFields	boolean	✗	Allow overwriting manually edited metadata
source	string	✓	Origin of media: "user" for uploads, "transcoder" for generated versions ≡ allowed values: usertranscoder
subtitleId	integer	✗	ID of subtitle to burn into video during transcoding
type	string	✓	Media type of the file to be created ≡ allowed values: imagevideoaudiodocument
uploadId	string	✗	Batch upload identifier (same for all files uploaded together)
usage	string	✗	Media usage: "preview" (main thumb), "thumbnail", "replacement" (for versioning), "subtitle", "interim", "outdated" ≡ allowed values: previewtranscodinghlsthumbnailuploadedThumbnailrawfileinterimspritedownloadsocialmediareplacementoutdatedlogoavatarwelcomeBackgroundcontactPicturesubtitletagImporteditscenesfacePreviewwaveform

Response

Field	Type	Description
additionalSettings	object	Extended configuration for media processing
└ contactId	integer	Associated contact ID
└ isAdditionalDocument	boolean	Mark as supplementary document
└ mediaContainerId	integer	Parent mediaContainer for subtitle files
└ subtitleLanguage	iso-639-2	Language code for subtitle files (ISO 639-2)
└ thumbnailsOnly	boolean	Skip video transcoding, only generate thumbnails Experimental
└ thumbnailVersion	integer	Thumbnail generation algorithm: 1 = legacy, 2 = current (default) ⟨⟩ range: 1 to 2
└ published	boolean	Publication status for subtitle files Experimental
└ ignoreMetadata	object	Disable automatic metadata extraction
└ container_name	boolean	Skip title extraction from IPTC/EXIF
└ container_description	boolean	Skip description extraction from IPTC/EXIF
└ keywordsAsTags	boolean	Do not convert IPTC keywords to tags
└ all	boolean	Skip all automatic metadata extraction
└ originalFileExtension	fileExtension	Original file extension (e.g., "docx", "xlsx"). Helps with Office document detection
└ disableAutoGenerate	boolean	Prevent automatic preview/thumbnail generation
└ replacement	object	Configuration for file replacement/versioning
└ id	integer	ID of the media being replaced
└ skipVersion	boolean	If true, replace without creating version history
additionalTechData	object	Technical analysis results (color profiles, histogram data, etc.). Please note that all properties are EXPERIMENTAL and may change or removed in future versions. Experimental
└ uploadSpeed	float	Upload speed in bytes per second
└ repairMimeType	string	Repaired MIME type if the original was incorrect
└ layers	integer	Number of layers in the image (if applicable)
└ quality	float	Estimated quality of the media (0-100 scale)
└ megaPixels	integer	Total megapixels in the image
└ alphatransparency	integer	Alpha transparency level (0-255)
└ laplacianBlurFactor	float	Laplacian blur factor for image sharpness detection
└ colorDetection	array	Detected dominant colors in the image
└ pixels	integer	Number of pixels matching this color
└ srgb	array	sRGB color values [R, G, B]
└ weight	float	Weight of this color in the image (0-1 scale)
└ width	integer	Document width in pixels
└ height	integer	Document height in pixels
└ pages	integer	Number of pages in the document (if applicable)
└ pageRot	integer	Rotation of the first page in degrees (0, 90, 180, 270)
└ pageSize	string	Page size in points (e.g., "595 x 842 pts (A4)")
└ encrypted	string	Indicates if the PDF is encrypted ≡ allowed values: yesno
└ pdfVersion	string	PDF version (e.g., "1.4")
└ audioStreamMapping	integer	TBC
analyzerResults	object	AI analysis results (object detection, face recognition, OCR).
audioBitrate	integer	Audio bitrate in bits per second
audioCodec	string	Audio codec (e.g., aac, mp3). For video and audio files
bits_per_sample	integer	Bit depth: color depth for images/video, sample size for audio
bucket	string	S3 bucket name (immutable) Will be removed in future versions without prior notice
channel_layout	string	Audio channel configuration (e.g., "stereo", "5.1")
channels	integer	Number of audio channels (1 = mono, 2 = stereo, etc.)
checksum	string	File checksum (auto-calculated)
colorProfile	string	Current ICC color profile, (e.g. Apple RGB, sRGB IEC61966-2.1, etc.)
colorProfileOriginal	string	Original ICC color profile before processing
colorSpace	string	Color space (e.g., rgb, srgb, cmyk, etc)
createdAt	string	Creation timestamp (ISO 8601)
creatorId	integer	User ID who created this media
customerId	integer	Customer account ID Will be removed in future versions without prior notice
display_aspect_ratio	string	Display aspect ratio (videos only). E.g., "16:9", "4:3"
dryRun	boolean	Indicates this was a validation-only request
duration	integer	Duration in milliseconds (video/audio only)
fileExtension	string	File extension (auto-detected)
fileName	string	Stored original filename
fileSize	integer	Actual file size in bytes
flag	integer	0 = active, 1 = no on S3, 2 = transcoding pending, 3 = upload pending, 6 = transcoding ended with error, probing failed – do not use for transcodings ≡ allowed values: 01234569
formatId	integer	Format ID of this media version
fps	number	Frames per second (videos only)
hasThumbnailVersions	boolean	True, if multiple thumbnail sizes are available
height	integer	Height in pixels (auto-detected)
id	integer	Unique media ID
isInterlaced	integer	Interlacing detection: 1 = interlaced, 2 = progressive
malwareScan	string	Malware scan status: "clean", "infected", "error"
malwareScanResult	string	Detailed malware scan results/threats found
malwareScanVersion	string	Antivirus engine version used
mediaContainerId	integer	ID of the mediaContainer this media belongs to
offsiteBackup	integer	Timestamp of the last offsite backup for this media item
orientation	integer	EXIF orientation (images): 3 = 180°, 6 = 90° CCW, 8 = 90° CW
phash	string	Perceptual hash for image similarity detection Is only active for legacy media. Will be removed in future versions without prior notice
provider	string	Storage provider (immutable) Will be removed in future versions without prior notice
region	string	AWS region (immutable) Will be removed in future versions without prior notice
resolutionUnit	integer	Resolution unit: 1 = none, 2 = inches, 3 = centimeters
s3Key	string	Unique S3 object key (immutable). Format: customer_ID/UUID Will be removed in future versions without prior notice
s3fileSize	integer	Total S3 storage used including all versions (bytes)
s3fileSizeLogDate	integer	Unix timestamp when s3fileSize was last calculated
sampleRate	integer	Audio sample rate in Hz (typically 48000 or 44100)
sample_aspect_ratio	string	Pixel aspect ratio (videos only). Usually "1:1"
source	string	Origin of this media item ≡ allowed values: usertranscoder
subtitleId	integer	ID of burned-in subtitle (if any)
totalTranscodingTime	integer	Cumulative transcoding duration in milliseconds. For original media, this is the upload time
type	string	Detected media type of this item ≡ allowed values: imagevideoaudiodocument
updatedAt	string	Last modification timestamp (ISO 8601)
uploadId	string	Batch upload identifier (same for all files uploaded together)
uploadLog	array	Logs of the upload
└ ip	ip	Anonymized IP address of the uploader
└ type	string	Type of the upload log entry ≡ allowed values: cloudtrails3
└ eventName	string	Event name from the upload log (e.g., CreateMultipartUpload) ≡ allowed values: CreateMultipartUploadCompleteMultipartUploadObjectCreated:CompleteMultipartUploadPutObjectUploadPart
└ eventTime	string	Timestamp of the upload event (ISO 8601 format)
usage	string	Current usage type of this media item ≡ allowed values: previewtranscodinghlsthumbnailuploadedThumbnailrawfileinterimspritedownloadsocialmediareplacementoutdatedlogoavatarwelcomeBackgroundcontactPicturesubtitletagImporteditscenesfacePreviewwaveform
videoBitrate	integer	Video bitrate in bits per second
videoCodec	string	Video codec (e.g., h264, h265). Also set for images
width	integer	Width in pixels (auto-detected)
xResolution	integer	Horizontal resolution (DPI/PPI)
yResolution	integer	Vertical resolution (DPI/PPI)

Update Media

Modify properties of existing media items

Updates media metadata such as filename or usage type. This endpoint is commonly used to change how a media item is categorized or displayed in the system. The usage property is particularly important for designating media as preview images, thumbnails, or other specific purposes.

PUT/v5/media/:mediaContainerId/:mediaId

Request Parameters

Field	Type	Required	Description
fileName	string	✗	Update the filename used when downloading. Max 250 chars
mediaContainerId	integer	✓	ID of the mediaContainer containing the media to update
mediaId	integer	✓	ID of the specific media item to update Deprecated
usage	string	✗	Change the usage type of this media item ≡ allowed values: previewtranscodinghlsthumbnailuploadedThumbnailrawfileinterimspritedownloadsocialmediareplacementoutdatedlogoavatarwelcomeBackgroundcontactPicturesubtitletagImporteditscenesfacePreviewwaveform

Response

Field	Type	Description
additionalSettings	object	Extended configuration for media processing
└ contactId	integer	Associated contact ID
└ isAdditionalDocument	boolean	Mark as supplementary document
└ mediaContainerId	integer	Parent mediaContainer for subtitle files
└ subtitleLanguage	iso-639-2	Language code for subtitle files (ISO 639-2)
└ thumbnailsOnly	boolean	Skip video transcoding, only generate thumbnails Experimental
└ thumbnailVersion	integer	Thumbnail generation algorithm: 1 = legacy, 2 = current (default) ⟨⟩ range: 1 to 2
└ published	boolean	Publication status for subtitle files Experimental
└ ignoreMetadata	object	Disable automatic metadata extraction
└ container_name	boolean	Skip title extraction from IPTC/EXIF
└ container_description	boolean	Skip description extraction from IPTC/EXIF
└ keywordsAsTags	boolean	Do not convert IPTC keywords to tags
└ all	boolean	Skip all automatic metadata extraction
└ originalFileExtension	fileExtension	Original file extension (e.g., "docx", "xlsx"). Helps with Office document detection
└ disableAutoGenerate	boolean	Prevent automatic preview/thumbnail generation
└ replacement	object	Configuration for file replacement/versioning
└ id	integer	ID of the media being replaced
└ skipVersion	boolean	If true, replace without creating version history
additionalTechData	object	Technical analysis results (color profiles, histogram data, etc.). Please note that all properties are EXPERIMENTAL and may change or removed in future versions. Experimental
└ uploadSpeed	float	Upload speed in bytes per second
└ repairMimeType	string	Repaired MIME type if the original was incorrect
└ layers	integer	Number of layers in the image (if applicable)
└ quality	float	Estimated quality of the media (0-100 scale)
└ megaPixels	integer	Total megapixels in the image
└ alphatransparency	integer	Alpha transparency level (0-255)
└ laplacianBlurFactor	float	Laplacian blur factor for image sharpness detection
└ colorDetection	array	Detected dominant colors in the image
└ pixels	integer	Number of pixels matching this color
└ srgb	array	sRGB color values [R, G, B]
└ weight	float	Weight of this color in the image (0-1 scale)
└ width	integer	Document width in pixels
└ height	integer	Document height in pixels
└ pages	integer	Number of pages in the document (if applicable)
└ pageRot	integer	Rotation of the first page in degrees (0, 90, 180, 270)
└ pageSize	string	Page size in points (e.g., "595 x 842 pts (A4)")
└ encrypted	string	Indicates if the PDF is encrypted ≡ allowed values: yesno
└ pdfVersion	string	PDF version (e.g., "1.4")
└ audioStreamMapping	integer	TBC
analyzerResults	object	AI analysis results (object detection, face recognition, OCR).
audioBitrate	integer	Audio bitrate in bits per second
audioCodec	string	Audio codec (e.g., aac, mp3). For video and audio files
bits_per_sample	integer	Bit depth: color depth for images/video, sample size for audio
bucket	string	S3 bucket name (immutable) Will be removed in future versions without prior notice
channel_layout	string	Audio channel configuration (e.g., "stereo", "5.1")
channels	integer	Number of audio channels (1 = mono, 2 = stereo, etc.)
checksum	string	File checksum (auto-calculated)
colorProfile	string	Current ICC color profile, (e.g. Apple RGB, sRGB IEC61966-2.1, etc.)
colorProfileOriginal	string	Original ICC color profile before processing
colorSpace	string	Color space (e.g., rgb, srgb, cmyk, etc)
createdAt	string	Creation timestamp (ISO 8601)
creatorId	integer	User ID who created this media
customerId	integer	Customer account ID Will be removed in future versions without prior notice
display_aspect_ratio	string	Display aspect ratio (videos only). E.g., "16:9", "4:3"
dryRun	boolean	Indicates this was a validation-only request
duration	integer	Duration in milliseconds (video/audio only)
fileExtension	string	File extension (auto-detected)
fileName	string	Stored original filename
fileSize	integer	Actual file size in bytes
flag	integer	0 = active, 1 = no on S3, 2 = transcoding pending, 3 = upload pending, 6 = transcoding ended with error, probing failed – do not use for transcodings ≡ allowed values: 01234569
formatId	integer	Format ID of this media version
fps	number	Frames per second (videos only)
hasThumbnailVersions	boolean	True, if multiple thumbnail sizes are available
height	integer	Height in pixels (auto-detected)
id	integer	Unique media ID
isInterlaced	integer	Interlacing detection: 1 = interlaced, 2 = progressive
malwareScan	string	Malware scan status: "clean", "infected", "error"
malwareScanResult	string	Detailed malware scan results/threats found
malwareScanVersion	string	Antivirus engine version used
mediaContainerId	integer	ID of the mediaContainer this media belongs to
offsiteBackup	integer	Timestamp of the last offsite backup for this media item
orientation	integer	EXIF orientation (images): 3 = 180°, 6 = 90° CCW, 8 = 90° CW
phash	string	Perceptual hash for image similarity detection Is only active for legacy media. Will be removed in future versions without prior notice
provider	string	Storage provider (immutable) Will be removed in future versions without prior notice
region	string	AWS region (immutable) Will be removed in future versions without prior notice
resolutionUnit	integer	Resolution unit: 1 = none, 2 = inches, 3 = centimeters
s3Key	string	Unique S3 object key (immutable). Format: customer_ID/UUID Will be removed in future versions without prior notice
s3fileSize	integer	Total S3 storage used including all versions (bytes)
s3fileSizeLogDate	integer	Unix timestamp when s3fileSize was last calculated
sampleRate	integer	Audio sample rate in Hz (typically 48000 or 44100)
sample_aspect_ratio	string	Pixel aspect ratio (videos only). Usually "1:1"
source	string	Origin of this media item ≡ allowed values: usertranscoder
subtitleId	integer	ID of burned-in subtitle (if any)
totalTranscodingTime	integer	Cumulative transcoding duration in milliseconds. For original media, this is the upload time
type	string	Detected media type of this item ≡ allowed values: imagevideoaudiodocument
updatedAt	string	Last modification timestamp (ISO 8601)
uploadId	string	Batch upload identifier (same for all files uploaded together)
uploadLog	array	Logs of the upload
└ ip	ip	Anonymized IP address of the uploader
└ type	string	Type of the upload log entry ≡ allowed values: cloudtrails3
└ eventName	string	Event name from the upload log (e.g., CreateMultipartUpload) ≡ allowed values: CreateMultipartUploadCompleteMultipartUploadObjectCreated:CompleteMultipartUploadPutObjectUploadPart
└ eventTime	string	Timestamp of the upload event (ISO 8601 format)
usage	string	Current usage type of this media item ≡ allowed values: previewtranscodinghlsthumbnailuploadedThumbnailrawfileinterimspritedownloadsocialmediareplacementoutdatedlogoavatarwelcomeBackgroundcontactPicturesubtitletagImporteditscenesfacePreviewwaveform
videoBitrate	integer	Video bitrate in bits per second
videoCodec	string	Video codec (e.g., h264, h265). Also set for images
width	integer	Width in pixels (auto-detected)
xResolution	integer	Horizontal resolution (DPI/PPI)
yResolution	integer	Vertical resolution (DPI/PPI)

Destroy Media

Permanently remove media items from the system

Deletes both the database record and the actual file from storage. The endpoint includes safety checks for linked content (public areas, downloads, chapters) and requires explicit confirmation via forceDelete parameter when dependencies exist. Note that original media cannot be deleted directly – only through container deletion with retention policies.

DELETE/v5/media/:mediaContainerId/:mediaId

Request Parameters

Field	Type	Required	Description
forceDelete	boolean	✗	Force deletion even if linked to public areas, downloads, or chapters
mediaContainerId	integer	✓	ID of the mediaContainer containing the media to delete
mediaId	integer	✓	ID of the specific media item to delete Deprecated

Response

Field	Type	Description
id	integer	Unique media ID

Upload Media from URL

Import media files from external sources

Downloads and imports media files directly from provided URLs into AdmiralCloud. This asynchronous operation validates the source URL, downloads the file in the background, and processes it according to your media settings. Perfect for importing content from external systems or migrating existing media libraries.

POST/v6/media/:mediaContainerId/upload

Request Parameters

Field	Type	Required	Description
dryRun	boolean	✗	If true, validates the URL without actually importing the file
mediaContainerId	integer	✓	ID of the media container to upload the file to. Required unless dryRun is true
mediaId	integer	✗	Optional: specific media ID for replacement uploads Deprecated
priority	integer	✗	Processing priority for the upload job (1-10). Default: 5 Will be removed in future versions without prior notice
source	url	✓	Source URL to import the file from. Cannot be a private IP address
type	string	✗	Media type for the upload. Default: "document". Type URL is deprecated. Please do not use it any longer ≡ allowed values: imagevideoaudiodocumenturl

Response

Field	Type	Description
additionalSettings	object	Extended configuration for media processing
└ contactId	integer	Associated contact ID
└ isAdditionalDocument	boolean	Mark as supplementary document
└ mediaContainerId	integer	Parent mediaContainer for subtitle files
└ subtitleLanguage	iso-639-2	Language code for subtitle files (ISO 639-2)
└ thumbnailsOnly	boolean	Skip video transcoding, only generate thumbnails Experimental
└ thumbnailVersion	integer	Thumbnail generation algorithm: 1 = legacy, 2 = current (default) ⟨⟩ range: 1 to 2
└ published	boolean	Publication status for subtitle files Experimental
└ ignoreMetadata	object	Disable automatic metadata extraction
└ container_name	boolean	Skip title extraction from IPTC/EXIF
└ container_description	boolean	Skip description extraction from IPTC/EXIF
└ keywordsAsTags	boolean	Do not convert IPTC keywords to tags
└ all	boolean	Skip all automatic metadata extraction
└ originalFileExtension	fileExtension	Original file extension (e.g., "docx", "xlsx"). Helps with Office document detection
└ disableAutoGenerate	boolean	Prevent automatic preview/thumbnail generation
└ replacement	object	Configuration for file replacement/versioning
└ id	integer	ID of the media being replaced
└ skipVersion	boolean	If true, replace without creating version history
additionalTechData	object	Technical analysis results (color profiles, histogram data, etc.). Please note that all properties are EXPERIMENTAL and may change or removed in future versions. Experimental
└ uploadSpeed	float	Upload speed in bytes per second
└ repairMimeType	string	Repaired MIME type if the original was incorrect
└ layers	integer	Number of layers in the image (if applicable)
└ quality	float	Estimated quality of the media (0-100 scale)
└ megaPixels	integer	Total megapixels in the image
└ alphatransparency	integer	Alpha transparency level (0-255)
└ laplacianBlurFactor	float	Laplacian blur factor for image sharpness detection
└ colorDetection	array	Detected dominant colors in the image
└ pixels	integer	Number of pixels matching this color
└ srgb	array	sRGB color values [R, G, B]
└ weight	float	Weight of this color in the image (0-1 scale)
└ width	integer	Document width in pixels
└ height	integer	Document height in pixels
└ pages	integer	Number of pages in the document (if applicable)
└ pageRot	integer	Rotation of the first page in degrees (0, 90, 180, 270)
└ pageSize	string	Page size in points (e.g., "595 x 842 pts (A4)")
└ encrypted	string	Indicates if the PDF is encrypted ≡ allowed values: yesno
└ pdfVersion	string	PDF version (e.g., "1.4")
└ audioStreamMapping	integer	TBC
analyzerResults	object	AI analysis results (object detection, face recognition, OCR).
audioBitrate	integer	Audio bitrate in bits per second
audioCodec	string	Audio codec (e.g., aac, mp3). For video and audio files
bits_per_sample	integer	Bit depth: color depth for images/video, sample size for audio
bucket	string	S3 bucket name (immutable) Will be removed in future versions without prior notice
channel_layout	string	Audio channel configuration (e.g., "stereo", "5.1")
channels	integer	Number of audio channels (1 = mono, 2 = stereo, etc.)
checksum	string	File checksum (auto-calculated)
colorProfile	string	Current ICC color profile, (e.g. Apple RGB, sRGB IEC61966-2.1, etc.)
colorProfileOriginal	string	Original ICC color profile before processing
colorSpace	string	Color space (e.g., rgb, srgb, cmyk, etc)
createdAt	string	Creation timestamp (ISO 8601)
creatorId	integer	User ID who created this media
customerId	integer	Customer account ID Will be removed in future versions without prior notice
display_aspect_ratio	string	Display aspect ratio (videos only). E.g., "16:9", "4:3"
dryRun	boolean	Indicates this was a validation-only request
duration	integer	Duration in milliseconds (video/audio only)
fileExtension	string	File extension (auto-detected)
fileName	string	Stored original filename
fileSize	integer	Actual file size in bytes
flag	integer	0 = active, 1 = no on S3, 2 = transcoding pending, 3 = upload pending, 6 = transcoding ended with error, probing failed – do not use for transcodings ≡ allowed values: 01234569
formatId	integer	Format ID of this media version
fps	number	Frames per second (videos only)
hasThumbnailVersions	boolean	True, if multiple thumbnail sizes are available
height	integer	Height in pixels (auto-detected)
id	integer	Unique media ID
isInterlaced	integer	Interlacing detection: 1 = interlaced, 2 = progressive
malwareScan	string	Malware scan status: "clean", "infected", "error"
malwareScanResult	string	Detailed malware scan results/threats found
malwareScanVersion	string	Antivirus engine version used
mediaContainerId	integer	ID of the mediaContainer this media belongs to
offsiteBackup	integer	Timestamp of the last offsite backup for this media item
orientation	integer	EXIF orientation (images): 3 = 180°, 6 = 90° CCW, 8 = 90° CW
phash	string	Perceptual hash for image similarity detection Is only active for legacy media. Will be removed in future versions without prior notice
provider	string	Storage provider (immutable) Will be removed in future versions without prior notice
region	string	AWS region (immutable) Will be removed in future versions without prior notice
resolutionUnit	integer	Resolution unit: 1 = none, 2 = inches, 3 = centimeters
s3Key	string	Unique S3 object key (immutable). Format: customer_ID/UUID Will be removed in future versions without prior notice
s3fileSize	integer	Total S3 storage used including all versions (bytes)
s3fileSizeLogDate	integer	Unix timestamp when s3fileSize was last calculated
sampleRate	integer	Audio sample rate in Hz (typically 48000 or 44100)
sample_aspect_ratio	string	Pixel aspect ratio (videos only). Usually "1:1"
source	string	Origin of this media item ≡ allowed values: usertranscoder
subtitleId	integer	ID of burned-in subtitle (if any)
totalTranscodingTime	integer	Cumulative transcoding duration in milliseconds. For original media, this is the upload time
type	string	Detected media type of this item ≡ allowed values: imagevideoaudiodocument
updatedAt	string	Last modification timestamp (ISO 8601)
uploadId	string	Batch upload identifier (same for all files uploaded together)
uploadLog	array	Logs of the upload
└ ip	ip	Anonymized IP address of the uploader
└ type	string	Type of the upload log entry ≡ allowed values: cloudtrails3
└ eventName	string	Event name from the upload log (e.g., CreateMultipartUpload) ≡ allowed values: CreateMultipartUploadCompleteMultipartUploadObjectCreated:CompleteMultipartUploadPutObjectUploadPart
└ eventTime	string	Timestamp of the upload event (ISO 8601 format)
usage	string	Current usage type of this media item ≡ allowed values: previewtranscodinghlsthumbnailuploadedThumbnailrawfileinterimspritedownloadsocialmediareplacementoutdatedlogoavatarwelcomeBackgroundcontactPicturesubtitletagImporteditscenesfacePreviewwaveform
videoBitrate	integer	Video bitrate in bits per second
videoCodec	string	Video codec (e.g., h264, h265). Also set for images
width	integer	Width in pixels (auto-detected)
xResolution	integer	Horizontal resolution (DPI/PPI)
yResolution	integer	Vertical resolution (DPI/PPI)

Download Media

Generate secure, time-limited download URLs

Creates signed URLs for accessing media files with configurable expiration times and delivery options. Supports batch operations for up to 200 items per request. Files under 20GB are delivered via CloudFront for optimal performance, while larger files are served directly from S3. Includes options for inline viewing or forced download behavior.

If one of the media is not available for the user, then it is silently removed from the list. If you send formatIds, then ids are interpreted as mediaContainerIds and the media ids are determined this way.

If a media has an error, then just the id, no signedUrl is returned for that item.

If you send more than 200 ids with one call, the API will truncate the response to 200 items and send a warning with an X-AdmiralCloud-Warning Header.

Please read the information of expiration date of links: Links in AdmiralCloud

POST/v5/media/download

Request Parameters

Field	Type	Required	Description
audioLanguage	array	✗	ISO 639-1 language codes for audio track selection. Use "silent" for no audio ≡ allowed values: aaabafaksqamaranhyasavaeayazbabmeubebnbhbibobsbrbgmycacschcezhcucvkwcocrcycsdadedvnldzeleneoeteueefofafjfifrfrfyffkadegdgaglgvelgnguhthahehzhihohrhuhyigisioiiiuieiaidikisitjvjaklknkskakrkkkmkirwkykvkgkokjkulolalvlilnltlblulgmkmhmlmimrmsmkmgmtmnmimsmynanvnrndngnenlnnnbnonyocojoromospafapiplptpsqurmrorornrusgsasiskskslsesmsnsdsostessqscsrsssuswsvtytatttetgtlthbotitotntstktrtwugukuruzvevivocywawoxhyiyozazhzusilent
download	boolean	✗	If true, adds Content-Disposition: attachment header for download. If false, Content-Disposition: inline for viewing
expires	integer	✗	Signed URL expiration time in seconds. Default: 3600. Maximum determined by customer.individualConfiguration.media.expiresInternal
formatIds	array	✗	When set, interpret "ids" as mediaContainer IDs and fetch these formats
ids	array	✓	Array of media IDs (or mediaContainer IDs if formatIds is set) to generate signed URLs. Max 200 per request
ignoreSizeZero	boolean	✗	Silently skip media items with fileSize = 0
jobId	string	✗	Internal service validation token. Only processed for acserver requests
jobType	string	✓	Job type for jobId validation. Required when jobId is provided
language	string	✗	ISO 639-2 language code for filename localization. Default: original or "ac_download" ≡ allowed values: aarabkaceachadaadyafaafhafrainakaakksqialealgaltamhanganpapaaraarcarghyearnarpartarwasmastathausavaaveawaaymazebadbaibakbalbambaneusbasbatbejbelbembenberbhobihbikbinbisblabntbodbosbrabrebtkbuabugbulmyabyncadcaicarcatcaucebcelceschachbchechgzhochkchmchnchochpchrchuchvchycmccopcorcoscpecpfcppcrecrhcrpcsbcuscymcesdakdandardaydeldendeudgrdindivdoidradsbduadumnlddyudzoefiegyekaellelxengenmepoesteuseweewofanfaofasfatfijfilfinfiufonfrafrafrmfrofrrfrsfryfulfurgaagaygbagemkatdeugezgilglagleglgglvgmhgohgongorgotgrbgrcellgrngswgujgwihaihathauhawhebherhilhimhinhithmnhmohrvhsbhunhuphyeibaiboislidoiiiijoikuileiloinaincindineinhipkirairoislitajavjbojpnjprjrbkaakabkackalkamkankarkaskatkaukawkazkbdkhakhikhmkhokikkinkirkmbkokkomkonkorkoskpekrckrlkrokrukuakumkurkutladlahlamlaolatlavlezlimlinlitlollozltzlualublugluilunluolusmkdmadmagmahmaimakmalmanmrimapmarmasmsamdfmdrmenmgamicminmismkdmkhmlgmltmncmnimnomohmonmosmrimsamulmunmusmwlmwrmyamynmyvnahnainapnaunavnblndendondsnepnewnianicniunldnnonobnognonnornqonsonubnwcnyanymnynnyonziociojioriormosaossotaotopaapagpalpampanpappaupeofasphiphnplipolponporprapropusquerajraprarroarohromronronrunruprussadsagsahsaisalsamsansassatscnscoselsemsgasgnshnsidsinsiositslaslkslkslvsmasmesmismjsmnsmosmssnasndsnksogsomsonsotspasqisrdsrnsrpsrrssasswsuksunsussuxswaswesycsyrtahtaitamtatteltemtertettgktglthabodtigtirtivtkltlhtlitmhtogtontpitsitsntsotuktumtupturtuttvltwityvudmugauigukrumbundurduzbvaivenvievolvotwakwalwarwascymwenwlnwolxalxhoyaoyapyidyorypkzapzblzenzghzhazhozndzulzunzxxzzauni
width	integer	✗	Image width for resizing. Options: 720, 360, or 144. Omit for original size

Response

Field	Type	Description
error	array	List of errors encountered during processing
└ id	integer	Media ID that encountered the error
└ mediaContainerId	integer	ID of the mediaContainer this media belongs to
└ reason	string	Error reason or message
ignored	array	List of media items that were ignored
└ id	integer	Media ID that was ignored
└ mediaContainerId	integer	ID of the mediaContainer this media belongs to
└ reason	string	Reason why this media item was ignored
└ formatId	integer	ID of the media format that was ignored, if applicable
processed	array	List of processed media items with signed URLs
└ id	integer	Media ID
└ type	string	Media type ≡ allowed values: imagevideoaudiodocument
└ signedUrl	string	Generated signed URL for the media item
└ mediaContainerId	integer	ID of the mediaContainer this media belongs to
└ formatId	integer	ID of the media format used for this signed URL
└ fileName	string	Original filename used for this media item
└ fileExtension	string	File extension of the media item
└ expireTime	integer	Unix timestamp when the signed URL expires
└ serverTime	integer	Server timestamp when the signed URL was generated
└ fileSize	integer	File size in bytes
└ download	boolean	True if this URL is for downloading, false for inline viewing
└ usage	string	Usage type of this media item (e.g., "preview", "thumbnail") ≡ allowed values: previewtranscodinghlsthumbnailuploadedThumbnailrawfileinterimspritedownloadsocialmediareplacementoutdatedlogoavatarwelcomeBackgroundcontactPicturesubtitletagImporteditscenesfacePreviewwaveform
└ width	integer	Width of the media item in pixels, if applicable
└ height	integer	Height of the media item in pixels, if applicable
└ colorSpace	string	Color space of the media item (e.g., "srgb", "cmyk"), if applicable
└ xResolution	integer	Horizontal resolution in DPI/PPI, if applicable
└ yResolution	integer	Vertical resolution in DPI/PPI, if applicable
└ resolutionUnit	integer	Resolution unit: 1 = none, 2 = inches, 3 = centimeters

Preview Image

Access mediacontainer preview images with automatic sizing

Returns or redirects to the designated preview image for a mediaContainer. Supports multiple image sizes with automatic selection of the closest available resolution. Implements intelligent caching with 60-second cache headers for optimal performance. Falls back to placeholder images if no preview is available.

GET/v5/media/previewImage/:mediaContainerId/:width/:mediaId

Request Parameters

Field	Type	Required	Description
allowError	boolean	✗	Return 404 status instead of placeholder image on error
debug	boolean	✗	Return JSON response instead of redirect (for debugging) May be removed without notice. Testing only
language	string	✗	ISO 639-2 language code for localized preview. Default: "uni" (universal) ≡ allowed values: aarabkaceachadaadyafaafhafrainakaakksqialealgaltamhanganpapaaraarcarghyearnarpartarwasmastathausavaaveawaaymazebadbaibakbalbambaneusbasbatbejbelbembenberbhobihbikbinbisblabntbodbosbrabrebtkbuabugbulmyabyncadcaicarcatcaucebcelceschachbchechgzhochkchmchnchochpchrchuchvchycmccopcorcoscpecpfcppcrecrhcrpcsbcuscymcesdakdandardaydeldendeudgrdindivdoidradsbduadumnlddyudzoefiegyekaellelxengenmepoesteuseweewofanfaofasfatfijfilfinfiufonfrafrafrmfrofrrfrsfryfulfurgaagaygbagemkatdeugezgilglagleglgglvgmhgohgongorgotgrbgrcellgrngswgujgwihaihathauhawhebherhilhimhinhithmnhmohrvhsbhunhuphyeibaiboislidoiiiijoikuileiloinaincindineinhipkirairoislitajavjbojpnjprjrbkaakabkackalkamkankarkaskatkaukawkazkbdkhakhikhmkhokikkinkirkmbkokkomkonkorkoskpekrckrlkrokrukuakumkurkutladlahlamlaolatlavlezlimlinlitlollozltzlualublugluilunluolusmkdmadmagmahmaimakmalmanmrimapmarmasmsamdfmdrmenmgamicminmismkdmkhmlgmltmncmnimnomohmonmosmrimsamulmunmusmwlmwrmyamynmyvnahnainapnaunavnblndendondsnepnewnianicniunldnnonobnognonnornqonsonubnwcnyanymnynnyonziociojioriormosaossotaotopaapagpalpampanpappaupeofasphiphnplipolponporprapropusquerajraprarroarohromronronrunruprussadsagsahsaisalsamsansassatscnscoselsemsgasgnshnsidsinsiositslaslkslkslvsmasmesmismjsmnsmosmssnasndsnksogsomsonsotspasqisrdsrnsrpsrrssasswsuksunsussuxswaswesycsyrtahtaitamtatteltemtertettgktglthabodtigtirtivtkltlhtlitmhtogtontpitsitsntsotuktumtupturtuttvltwityvudmugauigukrumbundurduzbvaivenvievolvotwakwalwarwascymwenwlnwolxalxhoyaoyapyidyorypkzapzblzenzghzhazhozndzulzunzxxzzauni
mediaContainerId	integer	✓	MediaContainer ID to fetch the preview image from
mediaId	integer	✗	Optional: use this specific media instead of the default preview image Deprecated
responseCode	integer	✗	Alternative response image: 9000 = "No media selected" placeholder Will be removed without notice. Do not use in new implementations ≡ allowed values: 9000
width	integer	✗	Requested image width. Default: 640. Returns closest available size

Response

Field	Type	Description
–		This endpoint returns a redirect (HTTP 307) to the preview image URL. No additional fields are returned.

API

Reference

Find Media

FindBatch Media

Create Media

Update Media

Destroy Media

Upload Media from URL

Download Media

Preview Image

Related Articles