FormatController

Every media item in AdmiralCloud is linked to a format. A format can be of type video, audio, image or document. Except for the original formats (which are linked to uploaded media items) every format contains a command structure that defines how this format transcodes or converts the original media. This can be a format to transcode an original video to MP4 or to HLS or a RGB image into CYMK.

AdmiralCloud provided a huge number of curated, managed formats so most of the time there is no need to create your own format. AdmiralCloud also provided microservices which can do conversion of the fly – please checkout Smartcropping Service

Command structure

Every custom format must be based on one of our managed blueprint formats. These formats define available parameters in the settings object. The actual format command must be set in settings parameters.

Again, custom format can have all command parameters from blueprint AND allowedParameters (which take precedence). Take a look at this example:

// blueprint settings
{
   "parameters":{
      "width":640
   },
   "allowedParameters":[
      {
         "command":"width",
         "regex":"^\\d{2,5}$",
         "mediaTypes":[
            "audio"
         ]
      },
      {
         "command":"height",
         "regex":"^\\d{2,5}$",
         "mediaTypes":[
            "audio"
         ]
      }
   ]
}

// custom format
{
   "parameters":{
      "width":1920,
      "height":1080,
      "notAllowedParameter":true
   }
}

// Result command, notAllowedParameter will be ignored
{ width: 1920, height: 1080 }

IPTC-Data

By default AdmiralCloud removes all metadata from images for data protection reasons. A source field (iptc:source) will be automatically re-added with the name of the customer as defined in the customer account. Also the field xmp:CreatorTool will be set to “AdmiralCloud”.

You can define other fields in your format that should be added during transcoding as well as updated after those metadata change. To do so, you have to set settings.metadata in your format.

[
  { "metaTitle": "meta_exif_camera_model" },
  { "metaTitle": "meta_exif_camera_model", "type": "exif", "key": "model" },
  { "metaTitle": "tags", "key": "Keywords", "languages": ["de", "uni"] } // languages is optional,
  { "metaTitle": "license" },
  { "metaTitle": "instructions" }
]

Field	Type	Required	Description
metaTitle	String	yes	The field as defined in our metadata fields. The will automatically be mapped to the proper IPTC or EXIF field. If you want more control, use type and key. SPECIAL CASES: Using “tags” as value -> Tags are set as keywords, all languages are used. If you set languages array only tags in those languages are added. Using “license” as value -> license_rightsUsageTerms are determined from license metadata and added as xmp:usageterms Using instructions as value -> If you set value as property of this object this value is used. Otherwise start, end and types are determined from license and added as instructions
type	String		Optional type – can be exif or iptc
key	String		Optional key to use as IPTC or EXIF field
language			If set metadata in this language is preferred. Otherwise “uni” will be used.

Please note, that the metadata must exist, otherwise the field will remain empty/will not be written to the file.

Reference

Find formats

Find all formats, a single one by id or all for a given media type.

GET/v5/format

Request Parameters

Field	Type	Required	Description
id	integer	✗	Return format for the given id
mediaType	string	✗	Return format for the given mediaType
refresh	boolean	✗	If true, data in cache is invalidated and result comes fresh from database

Response

Field	Type	Description
blueprintId	integer	This is a custom format that is based on the this blueprint id
command	object	Final command that is used with this format
configuration	object	misc configuration settings for this format
└ transcodingCreateNotAllowed	boolean	wether allowed to use format directly for transcoding
└ mediaTypes	array	media types this format is available for
└ useInPlayer	boolean	Set to true if this format is used in weblinks/player
└ autoGenerate	array	List of mediaTypes you want to autoGenerate this format for, if a new source media is uploaded
└ previewFormat	boolean	If true, this format is marked as preview format for videos/audios.
└ watermark	object	Settings for a watermark. Available for video and image Beta
└ mediaContainerId	integer	mediaContainerId id of the asset to use as watermark. Must be an image with flag 33 and type "watermark".
└ position	string	Position of the watermark. When using watermarks with images, the position is relative to gravity (see below)
└ widthFactor	integer	Factor between 0-100 to determine the scaling of the watermark
└ gravity	string	Position of image
└ audioWatermark	object	Settings for a audioWatermark. Available for video and audio. Beta
└ mediaContainerId	integer	mediaContainerId id of the asset to use as watermark. Must be an audio with flag 33 and type "watermark".
└ position	integer	First occurence (in seconds) for the audioLogo. Will then be repeated as defined in interval
└ interval	integer	Time after the audioLogo is added again.
└ annotation	object	Settings for a annotation. Available for image. Beta
└ text	string	Annotation text
└ fill	string	Optional color for the text. Can be a color name ("green") or a hex color ("#ff99900")
└ font	string	Optional font to use for the text.
└ gravity	string	Optional position for the text
└ pointSize	integer	Optional font size. Default value is calculated based on the target size
└ relative	integer	Optional position relative to gravity. Default value is calculated based on the target size.
└ burnTimecode	object	Settings for a burnTimecode. Available for videos. ATTN: Customer individualConfiguration will overwrite any format settings! Beta
└ fontcolor	string	Color for the timecode
└ fontsize	integer	Optional color for the text. Can be a color name ("green") or a hex color ("#ff99900")
└ box	integer	If 1, a box is drawn around the timecode
└ boxcolor	string	Color of the box
└ boxborderw	integer	Border width for the box
└ gravity	string	Position of the timecode (North = top, South = bottom)
└ offset	integer	Start offset for the timecode. 0 => 10:00:00:00, 1 => 00:00:00:00
converter	string	Which converter is used on our transcoding cluster
createdAt	dateTime	Date and time of the creation
creatorId	integer	Id of the user who created this format.
flag	integer	Flag 1 marks a format as deleted but media items with this formatId still exist
fromCache	boolean	Indicates if response came from cache
id	integer	Id of the format
isBlueprint	boolean	If true, this is a base format which can be used as a blueprint for new formats.
lastEditorId	integer	Id of the user who updated this format.
name	string	Name of the format
settings	object	misc settings for this format
└ mediaTypes	array	media types this format is available for
└ useInPlayer	boolean	Set to true if this format is used in weblinks/player
└ autoGenerate	array	List of mediaTypes you want to autoGenerate this format for, if a new source media is uploaded
└ previewFormat	boolean	If true, this format is marked as preview format for videos/audios.
└ createThumbnailVersions	boolean	If true, thumbnail versions are created
└ filetype	string	File type for the target format
└ parameters	object	Command parameters. Must match allowedParameters (in blueprint)
└ metadata	array	Array of objects with metadata definitions (IPTC and EXIF)
└ watermark	object	Settings for a watermark. Available for video and image Beta
└ mediaContainerId	integer	mediaContainerId id of the asset to use as watermark. Must be an image with flag 33 and type "watermark".
└ position	string	Position of the watermark. When using watermarks with images, the position is relative to gravity (see below)
└ widthFactor	integer	Factor between 0-100 to determine the scaling of the watermark
└ gravity	string	Position of image
└ audioWatermark	object	Settings for a audioWatermark. Available for video and audio. Beta
└ mediaContainerId	integer	mediaContainerId id of the asset to use as watermark. Must be an audio with flag 33 and type "watermark".
└ position	integer	First occurence (in seconds) for the audioLogo. Will then be repeated as defined in interval
└ interval	integer	Time after the audioLogo is added again.
└ annotation	object	Settings for a annotation. Available for image. Beta
└ text	string	Annotation text
└ fill	string	Optional color for the text. Can be a color name ("green") or a hex color ("#ff99900")
└ font	string	Optional font to use for the text.
└ gravity	string	Optional position for the text
└ pointSize	integer	Optional font size. Default value is calculated based on the target size
└ relative	integer	Optional position relative to gravity. Default value is calculated based on the target size.
└ burnTimecode	object	Settings for a burnTimecode. Available for videos. ATTN: Customer individualConfiguration will overwrite any format settings! Beta
└ fontcolor	string	Color for the timecode
└ fontsize	string	Optional color for the text. Can be a color name ("green") or a hex color ("#ff99900")
└ font	integer	Font size for the timecode in px. If not set, we will scale the font based on the video size starting with 16px for a 360p(x)video.
└ box	integer	If 1, a box is drawn around the timecode
└ boxcolor	string	Color of the box
└ boxborderw	integer	Border width for the box
└ position	string	Position of the timecode (North = top, South = bottom)
└ offset	integer	Start offset for the timecode. 0 => 10:00:00:00, 1 => 00:00:00:00
└ testMode	object	Testmode only
type	string	DO NOT USE ANY LONGER! Please use settings.mediaTypes instead.
updatedAt	dateTime	Date and time of the latest update
usage	string	What is this format used for – allowed values are transcoding, preview

Create a new format

Creates a new format based on a blueprintId. Parameters for converters (FFMPEG, IM) are only available with adminLevel > 9!

POST/v5/format

Creates a new caption for a given subtitle. Checks the start and endTime against the original media duration.

Request Parameters

Field	Type	Required	Description
blueprintId	integer	✓	id of the blueprint format to base this format on
command	object	✗	Do not use this any longer. Use settings
configuration	object	✗	misc configuration settings for this format
└ transcodingCreateNotAllowed	boolean	✗	wether allowed to use format directly for transcoding
└ mediaTypes	array	✗	media types this format is available for
└ useInPlayer	boolean	✗	Set to true if this format is used in weblinks/player
└ autoGenerate	array	✗	List of mediaTypes you want to autoGenerate this format for, if a new source media is uploaded
└ previewFormat	boolean	✗	If true, this format is marked as preview format for videos/audios.
└ watermark	object	✗	Settings for a watermark. Available for video and image
└ mediaContainerId	integer	✓	mediaContainerId id of the asset to use as watermark. Must be an image with flag 33 and type "watermark".
└ position	string	✗	Position of the watermark. When using watermarks with images, the position is relative to gravity (see below)
└ widthFactor	integer	✗	Factor between 0-100 to determine the scaling of the watermark
└ gravity	string	✗	Position of image
└ audioWatermark	object	✗	Settings for a audioWatermark. Available for video and audio.
└ mediaContainerId	integer	✓	mediaContainerId id of the asset to use as watermark. Must be an audio with flag 33 and type "watermark".
└ position	integer	✗	First occurence (in seconds) for the audioLogo. Will then be repeated as defined in interval
└ interval	integer	✗	Time after the audioLogo is added again.
└ annotation	object	✗	Settings for a annotation. Available for image.
└ text	string	✓	Annotation text
└ fill	string	✗	Optional color for the text. Can be a color name ("green") or a hex color ("#ff99900")
└ font	string	✗	Optional font to use for the text.
└ gravity	string	✗	Optional position for the text
└ pointSize	integer	✗	Optional font size. Default value is calculated based on the target size
└ relative	integer	✗	Optional position relative to gravity. Default value is calculated based on the target size.
└ burnTimecode	object	✗	Settings for a burnTimecode. Available for videos. ATTN: Customer individualConfiguration will overwrite any format settings!
└ fontcolor	string	✗	Color for the timecode
└ fontsize	integer	✗	Optional color for the text. Can be a color name ("green") or a hex color ("#ff99900")
└ box	integer	✗	If 1, a box is drawn around the timecode
└ boxcolor	string	✗	Color of the box
└ boxborderw	integer	✗	Border width for the box
└ gravity	string	✗	Position of the timecode (North = top, South = bottom)
└ offset	integer	✗	Start offset for the timecode. 0 => 10:00:00:00, 1 => 00:00:00:00
converter	string	✓	name of the converter
name	string	✓	Name of the format to create
settings	object	✗	misc settings for this format
└ mediaTypes	array	✗	media types this format is available for
└ useInPlayer	boolean	✗	Set to true if this format is used in weblinks/player
└ autoGenerate	array	✗	List of mediaTypes you want to autoGenerate this format for, if a new source media is uploaded
└ previewFormat	boolean	✗	If true, this format is marked as preview format for videos/audios.
└ createThumbnailVersions	boolean	✗	If true, thumbnail versions are created
└ filetype	string	✗	File type for the target format
└ parameters	object	✗	Command parameters. Must match allowedParameters (in blueprint)
└ metadata	array	✗	Array of objects with metadata definitions (IPTC and EXIF)
└ watermark	object	✗	Settings for a watermark. Available for video and image
└ mediaContainerId	integer	✗	mediaContainerId id of the asset to use as watermark. Must be an image with flag 33 and type "watermark".
└ position	string	✗	Position of the watermark. When using watermarks with images, the position is relative to gravity (see below)
└ widthFactor	integer	✗	Factor between 0-100 to determine the scaling of the watermark
└ gravity	string	✗	Position of image
└ audioWatermark	object	✗	Settings for a audioWatermark. Available for video and audio.
└ mediaContainerId	integer	✗	mediaContainerId id of the asset to use as watermark. Must be an audio with flag 33 and type "watermark".
└ position	integer	✗	First occurence (in seconds) for the audioLogo. Will then be repeated as defined in interval
└ interval	integer	✗	Time after the audioLogo is added again.
└ annotation	object	✗	Settings for a annotation. Available for image.
└ text	string	✗	Annotation text
└ fill	string	✗	Optional color for the text. Can be a color name ("green") or a hex color ("#ff99900")
└ font	string	✗	Optional font to use for the text.
└ gravity	string	✗	Optional position for the text
└ pointSize	integer	✗	Optional font size. Default value is calculated based on the target size
└ relative	integer	✗	Optional position relative to gravity. Default value is calculated based on the target size.
└ burnTimecode	object	✗	Settings for a burnTimecode. Available for videos. ATTN: Customer individualConfiguration will overwrite any format settings!
└ fontcolor	string	✗	Color for the timecode
└ fontsize	string	✗	Optional color for the text. Can be a color name ("green") or a hex color ("#ff99900")
└ font	integer	✗	Font size for the timecode in px. If not set, we will scale the font based on the video size starting with 16px for a 360p(x)video.
└ box	integer	✗	If 1, a box is drawn around the timecode
└ boxcolor	string	✗	Color of the box
└ boxborderw	integer	✗	Border width for the box
└ position	string	✗	Position of the timecode (North = top, South = bottom)
└ offset	integer	✗	Start offset for the timecode. 0 => 10:00:00:00, 1 => 00:00:00:00
└ testMode	object	✗	Testmode only
usage	string	✗	usage for this format

Response

Field	Type	Description
blueprintId	integer	This is a custom format that is based on the this blueprint id
command	object	Final command that is used with this format
configuration	object	misc configuration settings for this format
└ transcodingCreateNotAllowed	boolean	wether allowed to use format directly for transcoding
└ mediaTypes	array	media types this format is available for
└ useInPlayer	boolean	Set to true if this format is used in weblinks/player
└ autoGenerate	array	List of mediaTypes you want to autoGenerate this format for, if a new source media is uploaded
└ previewFormat	boolean	If true, this format is marked as preview format for videos/audios.
└ watermark	object	Settings for a watermark. Available for video and image Beta
└ mediaContainerId	integer	mediaContainerId id of the asset to use as watermark. Must be an image with flag 33 and type "watermark".
└ position	string	Position of the watermark. When using watermarks with images, the position is relative to gravity (see below)
└ widthFactor	integer	Factor between 0-100 to determine the scaling of the watermark
└ gravity	string	Position of image
└ audioWatermark	object	Settings for a audioWatermark. Available for video and audio. Beta
└ mediaContainerId	integer	mediaContainerId id of the asset to use as watermark. Must be an audio with flag 33 and type "watermark".
└ position	integer	First occurence (in seconds) for the audioLogo. Will then be repeated as defined in interval
└ interval	integer	Time after the audioLogo is added again.
└ annotation	object	Settings for a annotation. Available for image. Beta
└ text	string	Annotation text
└ fill	string	Optional color for the text. Can be a color name ("green") or a hex color ("#ff99900")
└ font	string	Optional font to use for the text.
└ gravity	string	Optional position for the text
└ pointSize	integer	Optional font size. Default value is calculated based on the target size
└ relative	integer	Optional position relative to gravity. Default value is calculated based on the target size.
└ burnTimecode	object	Settings for a burnTimecode. Available for videos. ATTN: Customer individualConfiguration will overwrite any format settings! Beta
└ fontcolor	string	Color for the timecode
└ fontsize	integer	Optional color for the text. Can be a color name ("green") or a hex color ("#ff99900")
└ box	integer	If 1, a box is drawn around the timecode
└ boxcolor	string	Color of the box
└ boxborderw	integer	Border width for the box
└ gravity	string	Position of the timecode (North = top, South = bottom)
└ offset	integer	Start offset for the timecode. 0 => 10:00:00:00, 1 => 00:00:00:00
converter	string	Which converter is used on our transcoding cluster
createdAt	dateTime	Date and time of the creation
creatorId	integer	Id of the user who created this format.
flag	integer	Flag 1 marks a format as deleted but media items with this formatId still exist
fromCache	boolean	Indicates if response came from cache
id	integer	Id of the format
isBlueprint	boolean	If true, this is a base format which can be used as a blueprint for new formats.
lastEditorId	integer	Id of the user who updated this format.
name	string	Name of the format
settings	object	misc settings for this format
└ mediaTypes	array	media types this format is available for
└ useInPlayer	boolean	Set to true if this format is used in weblinks/player
└ autoGenerate	array	List of mediaTypes you want to autoGenerate this format for, if a new source media is uploaded
└ previewFormat	boolean	If true, this format is marked as preview format for videos/audios.
└ createThumbnailVersions	boolean	If true, thumbnail versions are created
└ filetype	string	File type for the target format
└ parameters	object	Command parameters. Must match allowedParameters (in blueprint)
└ metadata	array	Array of objects with metadata definitions (IPTC and EXIF)
└ watermark	object	Settings for a watermark. Available for video and image Beta
└ mediaContainerId	integer	mediaContainerId id of the asset to use as watermark. Must be an image with flag 33 and type "watermark".
└ position	string	Position of the watermark. When using watermarks with images, the position is relative to gravity (see below)
└ widthFactor	integer	Factor between 0-100 to determine the scaling of the watermark
└ gravity	string	Position of image
└ audioWatermark	object	Settings for a audioWatermark. Available for video and audio. Beta
└ mediaContainerId	integer	mediaContainerId id of the asset to use as watermark. Must be an audio with flag 33 and type "watermark".
└ position	integer	First occurence (in seconds) for the audioLogo. Will then be repeated as defined in interval
└ interval	integer	Time after the audioLogo is added again.
└ annotation	object	Settings for a annotation. Available for image. Beta
└ text	string	Annotation text
└ fill	string	Optional color for the text. Can be a color name ("green") or a hex color ("#ff99900")
└ font	string	Optional font to use for the text.
└ gravity	string	Optional position for the text
└ pointSize	integer	Optional font size. Default value is calculated based on the target size
└ relative	integer	Optional position relative to gravity. Default value is calculated based on the target size.
└ burnTimecode	object	Settings for a burnTimecode. Available for videos. ATTN: Customer individualConfiguration will overwrite any format settings! Beta
└ fontcolor	string	Color for the timecode
└ fontsize	string	Optional color for the text. Can be a color name ("green") or a hex color ("#ff99900")
└ font	integer	Font size for the timecode in px. If not set, we will scale the font based on the video size starting with 16px for a 360p(x)video.
└ box	integer	If 1, a box is drawn around the timecode
└ boxcolor	string	Color of the box
└ boxborderw	integer	Border width for the box
└ position	string	Position of the timecode (North = top, South = bottom)
└ offset	integer	Start offset for the timecode. 0 => 10:00:00:00, 1 => 00:00:00:00
└ testMode	object	Testmode only
type	string	DO NOT USE ANY LONGER! Please use settings.mediaTypes instead.
updatedAt	dateTime	Date and time of the latest update
usage	string	What is this format used for – allowed values are transcoding, preview

Update an existing format

Updates a given format. You cannot update blueprints or change the blueprintId this format is based on. Also, not all parameters can be changed or can be changed just to a certain level.

PUT/v5/format/:id

Updates an existing caption.

Request Parameters

Field	Type	Required	Description
command	object	✗	Do not use this any longer. Use settings
configuration	object	✗	misc configuration settings for this format
└ transcodingCreateNotAllowed	boolean	✗	wether allowed to use format directly for transcoding
└ mediaTypes	array	✗	media types this format is available for
└ useInPlayer	boolean	✗	Set to true if this format is used in weblinks/player
└ autoGenerate	array	✗	List of mediaTypes you want to autoGenerate this format for, if a new source media is uploaded
└ previewFormat	boolean	✗	If true, this format is marked as preview format for videos/audios.
└ watermark	object	✗	Settings for a watermark. Available for video and image
└ mediaContainerId	integer	✓	mediaContainerId id of the asset to use as watermark. Must be an image with flag 33 and type "watermark".
└ position	string	✗	Position of the watermark. When using watermarks with images, the position is relative to gravity (see below)
└ widthFactor	integer	✗	Factor between 0-100 to determine the scaling of the watermark
└ gravity	string	✗	Position of image
└ audioWatermark	object	✗	Settings for a audioWatermark. Available for video and audio.
└ mediaContainerId	integer	✓	mediaContainerId id of the asset to use as watermark. Must be an audio with flag 33 and type "watermark".
└ position	integer	✗	First occurence (in seconds) for the audioLogo. Will then be repeated as defined in interval
└ interval	integer	✗	Time after the audioLogo is added again.
└ annotation	object	✗	Settings for a annotation. Available for image.
└ text	string	✓	Annotation text
└ fill	string	✗	Optional color for the text. Can be a color name ("green") or a hex color ("#ff99900")
└ font	string	✗	Optional font to use for the text.
└ gravity	string	✗	Optional position for the text
└ pointSize	integer	✗	Optional font size. Default value is calculated based on the target size
└ relative	integer	✗	Optional position relative to gravity. Default value is calculated based on the target size.
└ burnTimecode	object	✗	Settings for a burnTimecode. Available for videos. ATTN: Customer individualConfiguration will overwrite any format settings!
└ fontcolor	string	✗	Color for the timecode
└ fontsize	integer	✗	Optional color for the text. Can be a color name ("green") or a hex color ("#ff99900")
└ box	integer	✗	If 1, a box is drawn around the timecode
└ boxcolor	string	✗	Color of the box
└ boxborderw	integer	✗	Border width for the box
└ gravity	string	✗	Position of the timecode (North = top, South = bottom)
└ offset	integer	✗	Start offset for the timecode. 0 => 10:00:00:00, 1 => 00:00:00:00
id	integer	✓	Id of the caption you want to update
name	string	✓	Name of the format to update
settings	object	✗	misc settings for this format
└ mediaTypes	array	✗	media types this format is available for
└ useInPlayer	boolean	✗	Set to true if this format is used in weblinks/player
└ autoGenerate	array	✗	List of mediaTypes you want to autoGenerate this format for, if a new source media is uploaded
└ previewFormat	boolean	✗	If true, this format is marked as preview format for videos/audios.
└ createThumbnailVersions	boolean	✗	If true, thumbnail versions are created
└ filetype	string	✗	File type for the target format
└ parameters	object	✗	Command parameters. Must match allowedParameters (in blueprint)
└ metadata	array	✗	Array of objects with metadata definitions (IPTC and EXIF)
└ watermark	object	✗	Settings for a watermark. Available for video and image
└ mediaContainerId	integer	✗	mediaContainerId id of the asset to use as watermark. Must be an image with flag 33 and type "watermark".
└ position	string	✗	Position of the watermark. When using watermarks with images, the position is relative to gravity (see below)
└ widthFactor	integer	✗	Factor between 0-100 to determine the scaling of the watermark
└ gravity	string	✗	Position of image
└ audioWatermark	object	✗	Settings for a audioWatermark. Available for video and audio.
└ mediaContainerId	integer	✗	mediaContainerId id of the asset to use as watermark. Must be an audio with flag 33 and type "watermark".
└ position	integer	✗	First occurence (in seconds) for the audioLogo. Will then be repeated as defined in interval
└ interval	integer	✗	Time after the audioLogo is added again.
└ annotation	object	✗	Settings for a annotation. Available for image.
└ text	string	✗	Annotation text
└ fill	string	✗	Optional color for the text. Can be a color name ("green") or a hex color ("#ff99900")
└ font	string	✗	Optional font to use for the text.
└ gravity	string	✗	Optional position for the text
└ pointSize	integer	✗	Optional font size. Default value is calculated based on the target size
└ relative	integer	✗	Optional position relative to gravity. Default value is calculated based on the target size.
└ burnTimecode	object	✗	Settings for a burnTimecode. Available for videos. ATTN: Customer individualConfiguration will overwrite any format settings!
└ fontcolor	string	✗	Color for the timecode
└ fontsize	string	✗	Optional color for the text. Can be a color name ("green") or a hex color ("#ff99900")
└ font	integer	✗	Font size for the timecode in px. If not set, we will scale the font based on the video size starting with 16px for a 360p(x)video.
└ box	integer	✗	If 1, a box is drawn around the timecode
└ boxcolor	string	✗	Color of the box
└ boxborderw	integer	✗	Border width for the box
└ position	string	✗	Position of the timecode (North = top, South = bottom)
└ offset	integer	✗	Start offset for the timecode. 0 => 10:00:00:00, 1 => 00:00:00:00
└ testMode	object	✗	Testmode only
usage	string	✗	usage for this format

Response

Field	Type	Description
blueprintId	integer	This is a custom format that is based on the this blueprint id
command	object	Final command that is used with this format
configuration	object	misc configuration settings for this format
└ transcodingCreateNotAllowed	boolean	wether allowed to use format directly for transcoding
└ mediaTypes	array	media types this format is available for
└ useInPlayer	boolean	Set to true if this format is used in weblinks/player
└ autoGenerate	array	List of mediaTypes you want to autoGenerate this format for, if a new source media is uploaded
└ previewFormat	boolean	If true, this format is marked as preview format for videos/audios.
└ watermark	object	Settings for a watermark. Available for video and image Beta
└ mediaContainerId	integer	mediaContainerId id of the asset to use as watermark. Must be an image with flag 33 and type "watermark".
└ position	string	Position of the watermark. When using watermarks with images, the position is relative to gravity (see below)
└ widthFactor	integer	Factor between 0-100 to determine the scaling of the watermark
└ gravity	string	Position of image
└ audioWatermark	object	Settings for a audioWatermark. Available for video and audio. Beta
└ mediaContainerId	integer	mediaContainerId id of the asset to use as watermark. Must be an audio with flag 33 and type "watermark".
└ position	integer	First occurence (in seconds) for the audioLogo. Will then be repeated as defined in interval
└ interval	integer	Time after the audioLogo is added again.
└ annotation	object	Settings for a annotation. Available for image. Beta
└ text	string	Annotation text
└ fill	string	Optional color for the text. Can be a color name ("green") or a hex color ("#ff99900")
└ font	string	Optional font to use for the text.
└ gravity	string	Optional position for the text
└ pointSize	integer	Optional font size. Default value is calculated based on the target size
└ relative	integer	Optional position relative to gravity. Default value is calculated based on the target size.
└ burnTimecode	object	Settings for a burnTimecode. Available for videos. ATTN: Customer individualConfiguration will overwrite any format settings! Beta
└ fontcolor	string	Color for the timecode
└ fontsize	integer	Optional color for the text. Can be a color name ("green") or a hex color ("#ff99900")
└ box	integer	If 1, a box is drawn around the timecode
└ boxcolor	string	Color of the box
└ boxborderw	integer	Border width for the box
└ gravity	string	Position of the timecode (North = top, South = bottom)
└ offset	integer	Start offset for the timecode. 0 => 10:00:00:00, 1 => 00:00:00:00
converter	string	Which converter is used on our transcoding cluster
createdAt	dateTime	Date and time of the creation
creatorId	integer	Id of the user who created this format.
flag	integer	Flag 1 marks a format as deleted but media items with this formatId still exist
fromCache	boolean	Indicates if response came from cache
id	integer	Id of the format
isBlueprint	boolean	If true, this is a base format which can be used as a blueprint for new formats.
lastEditorId	integer	Id of the user who updated this format.
name	string	Name of the format
settings	object	misc settings for this format
└ mediaTypes	array	media types this format is available for
└ useInPlayer	boolean	Set to true if this format is used in weblinks/player
└ autoGenerate	array	List of mediaTypes you want to autoGenerate this format for, if a new source media is uploaded
└ previewFormat	boolean	If true, this format is marked as preview format for videos/audios.
└ createThumbnailVersions	boolean	If true, thumbnail versions are created
└ filetype	string	File type for the target format
└ parameters	object	Command parameters. Must match allowedParameters (in blueprint)
└ metadata	array	Array of objects with metadata definitions (IPTC and EXIF)
└ watermark	object	Settings for a watermark. Available for video and image Beta
└ mediaContainerId	integer	mediaContainerId id of the asset to use as watermark. Must be an image with flag 33 and type "watermark".
└ position	string	Position of the watermark. When using watermarks with images, the position is relative to gravity (see below)
└ widthFactor	integer	Factor between 0-100 to determine the scaling of the watermark
└ gravity	string	Position of image
└ audioWatermark	object	Settings for a audioWatermark. Available for video and audio. Beta
└ mediaContainerId	integer	mediaContainerId id of the asset to use as watermark. Must be an audio with flag 33 and type "watermark".
└ position	integer	First occurence (in seconds) for the audioLogo. Will then be repeated as defined in interval
└ interval	integer	Time after the audioLogo is added again.
└ annotation	object	Settings for a annotation. Available for image. Beta
└ text	string	Annotation text
└ fill	string	Optional color for the text. Can be a color name ("green") or a hex color ("#ff99900")
└ font	string	Optional font to use for the text.
└ gravity	string	Optional position for the text
└ pointSize	integer	Optional font size. Default value is calculated based on the target size
└ relative	integer	Optional position relative to gravity. Default value is calculated based on the target size.
└ burnTimecode	object	Settings for a burnTimecode. Available for videos. ATTN: Customer individualConfiguration will overwrite any format settings! Beta
└ fontcolor	string	Color for the timecode
└ fontsize	string	Optional color for the text. Can be a color name ("green") or a hex color ("#ff99900")
└ font	integer	Font size for the timecode in px. If not set, we will scale the font based on the video size starting with 16px for a 360p(x)video.
└ box	integer	If 1, a box is drawn around the timecode
└ boxcolor	string	Color of the box
└ boxborderw	integer	Border width for the box
└ position	string	Position of the timecode (North = top, South = bottom)
└ offset	integer	Start offset for the timecode. 0 => 10:00:00:00, 1 => 00:00:00:00
└ testMode	object	Testmode only
type	string	DO NOT USE ANY LONGER! Please use settings.mediaTypes instead.
updatedAt	dateTime	Date and time of the latest update
usage	string	What is this format used for – allowed values are transcoding, preview

Destroy format

Destroys a format. If there are media items converted with this format, the format will not be deleted but just marked as deleted (flag 1).

If you want to destroy all media items for this formatId you must send forceDelete. Please note that this operation is final and media items cannot be recovered!

This operation requires AdminLevel 9+.

DELETE/v5/format/:id

Request Parameters

Field	Type	Required	Description
forceDelete	boolean	✗	If true, the format and all media with this formatId are destroyed
id	integer	✓	Id of the caption you want to delete

Response

Field	Type	Description
flag	integer	Flag 1 marks a format as deleted but media items with this formatId still exist
id	integer	Id of the format
items	integer	Number of media items (with this format) that have been deleted.
jobId	string	JobId of the destroyFormat job/activitiy

API

Command structure

IPTC-Data

Reference

Find formats

Create a new format

Update an existing format

Destroy format

Related Articles