Create or Update Transform

Media API · Transforms

PUT https://app.mk.io/api/v1/projects/{project_name}/media/transforms/{transform_name}

Create or Updates a new Transform.

RBAC Capability Required: ams.transform.create or ams.transform.update

Authentication

• Authorization header — Bearer authentication of the form Bearer <token>.

Path parameters

Request body

Content type: application/json

• properties · object · Required — The properties of the Transform
  • description · string · Optional · <=1024 characters — The description of the Transform.
  • outputs · list of objects · Required — An array of TransformOutputs that the Transform should generate. Currently limited to one.
    • Array items (object):
      • onError · enum · Optional — Defines what the service should do when one output fails. Continue to produce other outputs, or stop processing.
        • Allowed values: ContinueJob, StopProcessingJob
      • preset · object · Required — Preset that describes the operations that will be used to modify, transcode, or extract insights from the source file to generate the output.
        • One of the following variants, selected by @odata.type:
          • #Microsoft.Media.BuiltInStandardEncoderPreset (object)
            • @odata.type · string · Required — The discriminator for derived types.
            • advancedSettingsName · string · Optional — Name of the advanced settings configuration to apply to this transform's config. These configuration blocks are managed by MediaKind and you should not set this field unless MediaKind support has asked you to.
            • presetName · string · Required — The built-in preset to be used for encoding videos. Options include: * H264SingleBitrateSD * H264SingleBitrate720p * H264SingleBitrate1080p * H264MultipleBitrateSD * H264MultipleBitrate720p * H264MultipleBitrate1080p * H264MultipleBitrateSDWithCVQ * H264MultipleBitrate720pWithCVQ * H264MultipleBitrate1080pWithCVQ * H265SingleBitrate720p * H265SingleBitrate1080p * H265SingleBitrate4K * AACGoodQualityAudio
          • #MediaKind.BuiltInAssetConverterPreset (object)
            • @odata.type · string · Required — The discriminator for derived types.
            • presetName · enum · Required — The built-in preset to be used for performing asset conversion.
              • Allowed values: CopyTopBitrateInterleaved, CopyAllBitrateNonInterleaved, CopyAllBitrateInterleaved
          • #Microsoft.Media.BuiltInAssetConverterPreset (object)
            • @odata.type · string · Required — The discriminator for derived types.
            • presetName · enum · Required — The built-in preset to be used for performing asset conversion.
              • Allowed values: CopyTopBitrateInterleaved, CopyAllBitrateNonInterleaved, CopyAllBitrateInterleaved
          • #MediaKind.ThumbnailGeneratorPreset (object)
            • @odata.type · string · Required — The discriminator for derived types.
            • baseFilename · string · Optional · <=64 characters · pattern: ^[A-Za-z0-9-]+$_ — Used to create the output filename as {BaseFilename}_{Label}{Index}{Extension}. The default is the name of the input file. If the name of the input file is too long then it will be truncated to 64 characters.
            • thumbnails · list of objects · Required · 1+ items — The set of thumbnails to be produced.
              • Array items (object):
                • format · enum · Required — The output format for the thumbnails.
                  • Allowed values: Jpeg, Png
                • height · string · Optional — Either an integer size in pixels, or a percentage of the input resolution. If either width/height is defined as percentage, the other dimension must be the same percentage.
                • label · string · Optional · <=64 characters · pattern: ^[A-Za-z0-9-]+$_ — Used to create the output filename as {BaseFilename}_{Label}{Index}{Extension}. When generating sprites, the output vtt file will be named {BaseFilename}_{Label}.vtt
                • quality · integer · Optional · 0 to 100 · Defaults to 70 — The compression quality for JPEG images. Between 0-100, default: 70.
                • range · string · Optional · Defaults to 1 — Either an ISO8601 duration, or a percentage of the asset duration, or the value '1'. The default is '1', a single thumbnail is produced.
                • spriteColumn · integer · Optional · 1 to 10 — The number of columns used if you want a thumbnail sprite image. Default: Single image output files.
                • start · string · Optional · Defaults to PT10S — Either an ISO8601 duration, or a percentage of the asset duration. Default: PT10S.
                • step · string · Optional — The intervals at which thumbnails are generated. Either an ISO8601 duration, or a percentage of the asset duration.
                • width · string · Optional — Either an integer size in pixels, or a percentage of the input resolution. If only one of width/height is present, the aspect ratio from the source is preserved.
          • #MediaKind.TrackInserterPreset (object)
            • @odata.type · string · Required — The discriminator for derived types.
            • baseFilename · string · Optional · _<=64 characters_ · _pattern: ^[A-Za-z0-9_-]+$_ — Used to create the output filename. - For text tracks: {BaseFilename}.cmft, the default being the input .vtt filename minus the extension, e.g. subtitles.vtt -> subtitles.cmft. - For audio tracks: {BaseFilename}.mp4, the default being the input .mp4 filename, ignored if the audio file is already present in the output asset.
            • tracks · list of objects · Required · 1-1 items — The set of tracks to be inserted. Currently limited to one.
              • Array items (object):
                • One of the following variants, selected by @odata.type:
                  • #MediaKind.TextTrack (object)
                    • @odata.type · string · Required — The discriminator for derived types.
                    • displayName · string · Optional — The display name of the track on a video player. In HLS, this maps to the NAME attribute of EXT-X-MEDIA.
                    • hlsSettings · object · Optional — The HLS specific setting for the track.
                      • characteristics · string · Optional — The characteristics for the HLS setting.
                      • default · boolean · Optional · Defaults to false — Default track?
                      • forced · boolean · Optional · Defaults to false — Forced track?
                    • languageCode · string · Optional — The RFC5646 language code for the track.
                    • playerVisibility · enum · Optional · Defaults to Visible — When PlayerVisibility is set to 'Visible', the track will be present in the DASH manifest or HLS playlist when requested by a client. When the PlayerVisibility is set to 'Hidden', the track will not be available to the client. The default value is 'Visible'.
                      • Allowed values: Visible, Hidden
                    • trackName · string · Required — The name of the track in the manifest.
                  • #MediaKind.AudioTrack (object)
                    • @odata.type · string · Required — The discriminator for derived types.
                    • dashSettings · object · Optional — The DASH specific setting for the audio track.
                      • role · string · Optional — The role for the DASH setting.
                    • displayName · string · Optional — The display name of the audio track on a video player. In HLS, this maps to the NAME attribute of EXT-X-MEDIA.
                    • hlsSettings · object · Optional — The HLS specific setting for the audio track.
                      • characteristics · string · Optional — The characteristics for the HLS setting.
                      • default · boolean · Optional · Defaults to false — Default track?
                      • forced · boolean · Optional · Defaults to false — Forced track?
                    • languageCode · string · Optional — The RFC5646 language code for the audio track.
                    • trackName · string · Required — The name of the audio track in the manifest.
          • #MediaKind.AIPipelinePreset (object)
            • @odata.type · string · Required — The discriminator for derived types.
            • pipeline · object · Required — AI pipeline settings
              • arguments · map from strings to list of objects · Optional — Arguments to each operation in the AI pipeline
                • [any key] · list of objects — map of additional properties
                  • Array items (object):
                    • name · string · Required · 1-260 characters · pattern: ^[A-Za-z0-9-]+$_ — The name of the argument
                    • value · any · Required — The value of the argument
              • name · string · Required · 0-255 characters — The name of the AI pipeline the Transform will execute.
          • #MediaKind.EncoderPreset (object)
            • @odata.type · string · Required — The discriminator for derived types.
            • advancedSettingsName · string · Optional — Name of the advanced settings configuration to apply to this transform's config. These configuration blocks are managed by MediaKind and you should not set this field unless MediaKind support has asked you to.
            • config · map from strings to any · Required — The configuration for the custom preset.
              • [any key] · any — map of additional properties
            • presetName · string · Required — Name of this preset.
      • relativePriority · enum · Optional · Defaults to Normal — Sets the relative priority of the TransformOutputs within a Transform
        • Allowed values: High, Low, Normal

Example request

curl -X PUT "https://app.mk.io/api/v1/projects/{project_name}/media/transforms/{transform_name}" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
  "properties": {
    "description": "string",
    "outputs": [
      {
        "onError": "ContinueJob",
        "preset": {
          "@odata.type": "#Microsoft.Media.BuiltInStandardEncoderPreset",
          "advancedSettingsName": "string",
          "presetName": "string"
        },
        "relativePriority": "Normal"
      }
    ]
  }
}'

Responses

200 — Transform was updated

• id · string · Optional — Fully qualified resource ID for the resource. Ex - /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}
• name · string · Optional · 1-260 characters · pattern: ^[^e0'%&:?/*+]+$ — The name of the resource
• properties · object · Required — The properties of the Transform
  • created · string · Optional · format: date-time — The creation date and time of the Transform. Set by the system.
  • description · string · Optional · <=1024 characters — The description of the Transform.
  • lastModified · string · Optional · format: date-time — The last modified date and time of the Transform. Set by the system.
  • outputs · list of objects · Required — An array of TransformOutputs that the Transform should generate. Currently limited to one.
    • Array items (object):
      • onError · enum · Optional — Defines what the service should do when one output fails. Continue to produce other outputs, or stop processing.
        • Allowed values: ContinueJob, StopProcessingJob
      • preset · object · Required — Preset that describes the operations that will be used to modify, transcode, or extract insights from the source file to generate the output.
        • One of the following variants, selected by @odata.type:
          • #Microsoft.Media.BuiltInStandardEncoderPreset (object)
            • @odata.type · string · Required — The discriminator for derived types.
            • advancedSettingsName · string · Optional — Name of the advanced settings configuration to apply to this transform's config. These configuration blocks are managed by MediaKind and you should not set this field unless MediaKind support has asked you to.
            • presetName · string · Required — The built-in preset to be used for encoding videos. Options include: * H264SingleBitrateSD * H264SingleBitrate720p * H264SingleBitrate1080p * H264MultipleBitrateSD * H264MultipleBitrate720p * H264MultipleBitrate1080p * H264MultipleBitrateSDWithCVQ * H264MultipleBitrate720pWithCVQ * H264MultipleBitrate1080pWithCVQ * H265SingleBitrate720p * H265SingleBitrate1080p * H265SingleBitrate4K * AACGoodQualityAudio
          • #MediaKind.BuiltInAssetConverterPreset (object)
            • @odata.type · string · Required — The discriminator for derived types.
            • presetName · enum · Required — The built-in preset to be used for performing asset conversion.
              • Allowed values: CopyTopBitrateInterleaved, CopyAllBitrateNonInterleaved, CopyAllBitrateInterleaved
          • #Microsoft.Media.BuiltInAssetConverterPreset (object)
            • @odata.type · string · Required — The discriminator for derived types.
            • presetName · enum · Required — The built-in preset to be used for performing asset conversion.
              • Allowed values: CopyTopBitrateInterleaved, CopyAllBitrateNonInterleaved, CopyAllBitrateInterleaved
          • #MediaKind.ThumbnailGeneratorPreset (object)
            • @odata.type · string · Required — The discriminator for derived types.
            • baseFilename · string · Optional · <=64 characters · pattern: ^[A-Za-z0-9-]+$_ — Used to create the output filename as {BaseFilename}_{Label}{Index}{Extension}. The default is the name of the input file. If the name of the input file is too long then it will be truncated to 64 characters.
            • thumbnails · list of objects · Required · 1+ items — The set of thumbnails to be produced.
              • Array items (object):
                • format · enum · Required — The output format for the thumbnails.
                  • Allowed values: Jpeg, Png
                • height · string · Optional — Either an integer size in pixels, or a percentage of the input resolution. If either width/height is defined as percentage, the other dimension must be the same percentage.
                • label · string · Optional · <=64 characters · pattern: ^[A-Za-z0-9-]+$_ — Used to create the output filename as {BaseFilename}_{Label}{Index}{Extension}. When generating sprites, the output vtt file will be named {BaseFilename}_{Label}.vtt
                • quality · integer · Optional · 0 to 100 · Defaults to 70 — The compression quality for JPEG images. Between 0-100, default: 70.
                • range · string · Optional · Defaults to 1 — Either an ISO8601 duration, or a percentage of the asset duration, or the value '1'. The default is '1', a single thumbnail is produced.
                • spriteColumn · integer · Optional · 1 to 10 — The number of columns used if you want a thumbnail sprite image. Default: Single image output files.
                • start · string · Optional · Defaults to PT10S — Either an ISO8601 duration, or a percentage of the asset duration. Default: PT10S.
                • step · string · Optional — The intervals at which thumbnails are generated. Either an ISO8601 duration, or a percentage of the asset duration.
                • width · string · Optional — Either an integer size in pixels, or a percentage of the input resolution. If only one of width/height is present, the aspect ratio from the source is preserved.
          • #MediaKind.TrackInserterPreset (object)
            • @odata.type · string · Required — The discriminator for derived types.
            • baseFilename · string · Optional · _<=64 characters_ · _pattern: ^[A-Za-z0-9_-]+$_ — Used to create the output filename. - For text tracks: {BaseFilename}.cmft, the default being the input .vtt filename minus the extension, e.g. subtitles.vtt -> subtitles.cmft. - For audio tracks: {BaseFilename}.mp4, the default being the input .mp4 filename, ignored if the audio file is already present in the output asset.
            • tracks · list of objects · Required · 1-1 items — The set of tracks to be inserted. Currently limited to one.
              • Array items (object):
                • One of the following variants, selected by @odata.type:
                  • #MediaKind.TextTrack (object)
                    • @odata.type · string · Required — The discriminator for derived types.
                    • displayName · string · Optional — The display name of the track on a video player. In HLS, this maps to the NAME attribute of EXT-X-MEDIA.
                    • hlsSettings · object · Optional — The HLS specific setting for the track.
                      • characteristics · string · Optional — The characteristics for the HLS setting.
                      • default · boolean · Optional · Defaults to false — Default track?
                      • forced · boolean · Optional · Defaults to false — Forced track?
                    • languageCode · string · Optional — The RFC5646 language code for the track.
                    • playerVisibility · enum · Optional · Defaults to Visible — When PlayerVisibility is set to 'Visible', the track will be present in the DASH manifest or HLS playlist when requested by a client. When the PlayerVisibility is set to 'Hidden', the track will not be available to the client. The default value is 'Visible'.
                      • Allowed values: Visible, Hidden
                    • trackName · string · Required — The name of the track in the manifest.
                  • #MediaKind.AudioTrack (object)
                    • @odata.type · string · Required — The discriminator for derived types.
                    • dashSettings · object · Optional — The DASH specific setting for the audio track.
                      • role · string · Optional — The role for the DASH setting.
                    • displayName · string · Optional — The display name of the audio track on a video player. In HLS, this maps to the NAME attribute of EXT-X-MEDIA.
                    • hlsSettings · object · Optional — The HLS specific setting for the audio track.
                      • characteristics · string · Optional — The characteristics for the HLS setting.
                      • default · boolean · Optional · Defaults to false — Default track?
                      • forced · boolean · Optional · Defaults to false — Forced track?
                    • languageCode · string · Optional — The RFC5646 language code for the audio track.
                    • trackName · string · Required — The name of the audio track in the manifest.
          • #MediaKind.AIPipelinePreset (object)
            • @odata.type · string · Required — The discriminator for derived types.
            • pipeline · object · Required — AI pipeline settings
              • arguments · map from strings to list of objects · Optional — Arguments to each operation in the AI pipeline
                • [any key] · list of objects — map of additional properties
                  • Array items (object):
                    • name · string · Required · 1-260 characters · pattern: ^[A-Za-z0-9-]+$_ — The name of the argument
                    • value · any · Required — The value of the argument
              • name · string · Required · 0-255 characters — The name of the AI pipeline the Transform will execute.
          • #MediaKind.EncoderPreset (object)
            • @odata.type · string · Required — The discriminator for derived types.
            • advancedSettingsName · string · Optional — Name of the advanced settings configuration to apply to this transform's config. These configuration blocks are managed by MediaKind and you should not set this field unless MediaKind support has asked you to.
            • config · map from strings to any · Required — The configuration for the custom preset.
              • [any key] · any — map of additional properties
            • presetName · string · Required — Name of this preset.
      • relativePriority · enum · Optional · Defaults to Normal — Sets the relative priority of the TransformOutputs within a Transform
        • Allowed values: High, Low, Normal
• systemData · object · Optional — Metadata pertaining to creation and last modification of the resource.
  • createdAt · string · Required · format: date-time — The timestamp of resource creation (UTC).
  • createdBy · string · Required — The identity that created the resource.
  • createdByType · enum · Required — The type of identity that created the resource.
    • Allowed values: User, Application, ManagedIdentity, Key
  • internalId · string · Required · format: uuid — The internal ID of the resource.
  • lastModifiedAt · string · Required · format: date-time — The timestamp of resource last modification (UTC).
  • lastModifiedBy · string · Required — The identity that last modified the resource.
  • lastModifiedByType · enum · Required — The type of identity that last modified the resource.
    • Allowed values: User, Application, ManagedIdentity, Key
• type · string · Optional — The type of the resource. E.g. "Microsoft.Media/mediaservices/assets"