--- title: "Create Transcode" method: POST path: "/delivery/v2.1/global/workspaces/{workspaceUUID}/transcodes" tags: ["CDN and DNS (v2.1)"] --- # Create Transcode `POST /delivery/v2.1/global/workspaces/{workspaceUUID}/transcodes` Creates a new Transcode object in the specified workspace with the provided configuration. ## Path parameters - `workspaceUUID` string, required ## Request body - V2Transcode - `apiVersion` 'delivery/v2' | 'delivery/v2.1', required — Version identifier of the API schema - `kind` 'Transcode', required — The string value 'Transcode' that identifies the schema - `metadata` V2ObjectMeta, required — Standard resource metadata fields - `creationTimestamp` string, date-time, required - `labels` object, required — Labels are key-value pairs attached to resources for organization and categorization - `name` string, required — User-provided name that uniquely identifies the resource within its workspace - `namespace` string, required — Namespace is the namespace in which the resource exists - `uid` string, required — System-generated unique identifier for the resource - `spec` V1TranscodeSpec, required — Desired configuration for the Transcode - `audios` V1Audio[] — Optional additional audio tracks to include in the transcoded output (max 4), each with language and title metadata. - `enabled` boolean, required — Whether this audio track should be processed and included in the transcoded output. - `input` V1Input, nullable, required — Source location of the watermark image file (supports PNG with transparency for best results). - `default` boolean — When true, marks this input as the default track (used for audio/subtitle tracks to indicate the primary or preferred track) - `http` V1HTTPInput, nullable — HTTP input configuration when protocol is 'http', contains the URL to retrieve the file from. - `url` string, required — HTTP or HTTPS URL of the input file to download, supports direct video/audio/subtitle file downloads from web servers. - `protocol` string, required — Specifies the source protocol to use for retrieving the input file (s3 or http) - `s3` V1S3Input, nullable — S3 input configuration when protocol is 's3', contains bucket, object key, and optional endpoint credentials. - `bucket` string, required — S3 bucket name where the input file is stored (3-64 characters). - `endpoint` V1S3Endpoint, nullable, required — Optional S3-compatible storage endpoint configuration, defaults to system-configured endpoint if omitted. - `accessKey` string — S3 access key ID for authentication, required for non-Kise endpoints that need explicit credentials. - `address` string, required — S3-compatible endpoint URL (e.g., 's3.amazonaws.com' or custom MinIO endpoint), defines where to connect for S3 operations. - `kise` boolean, required — When true, uses Kise internal S3 service for storage operations, bypassing S3 credentials. - `secretKey` string — S3 secret access key for authentication, paired with AccessKey for secure S3 API access. - `object` string, required — S3 object key (file name) of the input file to be retrieved, combined with prefix to form the full object path. - `prefix` string — Optional directory path prefix within the bucket, used to organize objects in folder-like structures. - `language` string, required — ISO 639-2 language code for the audio track (e.g., 'eng' for English, 'spa' for Spanish), used by FFmpeg for metadata. - `title` string, required — Optional title/description for the audio track, displayed in media players that support multi-audio selection. - `input` V1VideoInput, nullable, required — The input video to be transcoded. - `audioLanguage` string — ISO 639-2 language code for the input audio track (e.g., 'eng', 'fra'), used by FFmpeg for audio stream identification. - `audioTitle` string — Optional title metadata for the audio track in the input video, displayed in media players supporting audio track selection - `http` V1HTTPInput, nullable — HTTP input configuration when protocol is 'http', contains the URL to retrieve the file from. - `url` string, required — HTTP or HTTPS URL of the input file to download, supports direct video/audio/subtitle file downloads from web servers. - `protocol` string, required — Specifies the source protocol to use for getting the video (s3 or http) - `s3` V1S3Input, nullable — S3 input configuration when protocol is 's3', contains bucket, object key, and optional endpoint credentials. - `bucket` string, required — S3 bucket name where the input file is stored (3-64 characters). - `endpoint` V1S3Endpoint, nullable, required — Optional S3-compatible storage endpoint configuration, defaults to system-configured endpoint if omitted. - `accessKey` string — S3 access key ID for authentication, required for non-Kise endpoints that need explicit credentials. - `address` string, required — S3-compatible endpoint URL (e.g., 's3.amazonaws.com' or custom MinIO endpoint), defines where to connect for S3 operations. - `kise` boolean, required — When true, uses Kise internal S3 service for storage operations, bypassing S3 credentials. - `secretKey` string — S3 secret access key for authentication, paired with AccessKey for secure S3 API access. - `object` string, required — S3 object key (file name) of the input file to be retrieved, combined with prefix to form the full object path. - `prefix` string — Optional directory path prefix within the bucket, used to organize objects in folder-like structures. - `skipAudio` boolean — When true, skips processing audio streams from the input video, useful for video-only transcoding or when replacing audio entirely - `skipSubtitle` boolean — When true, skips processing subtitle streams from the input video, used when subtitles should not be carried over to the output - `output` V1Output, nullable, required — The output configuration to store the transcoded video. - `bucket` string, required — Target S3 bucket name where transcoded video files will be stored (3-64 characters). - `endpoint` V1S3Endpoint, nullable, required — Optional S3-compatible storage endpoint configuration, defaults to system-configured endpoint if omitted. - `accessKey` string — S3 access key ID for authentication, required for non-Kise endpoints that need explicit credentials. - `address` string, required — S3-compatible endpoint URL (e.g., 's3.amazonaws.com' or custom MinIO endpoint), defines where to connect for S3 operations. - `kise` boolean, required — When true, uses Kise internal S3 service for storage operations, bypassing S3 credentials. - `secretKey` string — S3 secret access key for authentication, paired with AccessKey for secure S3 API access. - `prefix` string — Optional object key prefix (folder path) within the bucket for organizing transcoded outputs. - `pipelineName` string — Reference to an existing Pipeline resource by name for reusable transcode configurations. - `pipelineSpec` V1PipelineSpec — Desired configuration for the Pipeline - `autoPresets` boolean — When true, automatically generates outputs for all video presets in the namespace, eliminating the need to manually specify Outputs array. - `outputs` V1PipelineOutput[] — List of output configurations with their associated presets (1-5 outputs), required when AutoPresets is false, each defining a quality/format variant. - `excludeFromPlaylist` boolean — When true, excludes this output from being included in adaptive bitrate playlists (e.g., HLS master playlist). - `excludeFromThumbs` boolean — When true, skips thumbnail generation for this specific output, useful for audio-only or low-quality variants. - `key` string, required — Unique identifier for this output variant (1-64 characters), used as part of the output filename and for referencing in playlists. - `presetName` string — Reference to an existing Preset resource by name, the PresetSpec will be automatically populated from this preset at runtime. - `presetSpec` V1PresetSpec — Desired configuration for the Preset - `audio` V1PresetAudio, nullable — Audio encoding configuration including codec, bitrate, and sample rate, required unless SkipAudio is true - `bitrate` string — Target audio bitrate (e.g., '64k', '128k', '192k', '320k', '1m'), higher bitrates provide better quality but larger file sizes, typical range 96k-320k. - `codec` string, required — Audio codec for encoding (aac, mp3, vorbis, opus, copy), 'copy' streams without re-encoding for faster processing, aac recommended for broad compatibility. - `sampleRate` integer — Audio sample rate of input audio to produce output audio in Hz (22050, 32000, 44100, 48000, 96000), 44100/48000 are standard for most content, higher rates for professional audio. - `container` string, required — Output container format (mp4, m4v, mov, avi, flv), determines the file wrapper format that FFmpeg will mux the encoded streams into. - `description` string — Human-readable description of this preset's purpose (max 128 characters), useful for identifying preset characteristics like '720p High Quality'. - `noFragment` boolean — When true, disables MP4 fragmentation (faststart/moov atom relocation), may impact progressive playback but reduces processing overhead. - `pixelFormat` string — FFmpeg pixel format for video output, yuv420p is the most compatible format for H.264/H.265 ensuring broad device support. - `skipAudio` boolean — When true, removes all audio streams from the output, creating a video-only file useful for silent videos or separate audio processing - `skipSubtitle` boolean — When true, removes all subtitle streams from the output, useful when subtitles should be handled separately or not included. - `skipVideo` boolean — When true, removes all video streams from the output, creating an audio-only file for music or podcast extraction. - `speed` string — FFmpeg encoding speed preset (medium, veryfast, ultrafast), trades encoding time for compression efficiency - faster speeds produce larger files but good quality. - `video` V1PresetVideo, nullable — Video encoding configuration including codec, resolution, bitrate, and quality settings, required unless SkipVideo is true - `bitrate` string — Target video bitrate (e.g., '1000k', '5M'), used for constant/average bitrate encoding, mutually exclusive with CRF for rate control. - `bufferSize` string — Video buffer verifier (VBV) buffer size (e.g., '2M'), controls bitrate variability, typically 1-2x MaxBitrate for streaming. - `codec` string, required — Video codec for encoding (h264, h265/HEVC, vp9), h264 offers best compatibility, h265 better compression, vp9 for WebM/VP9 workflows. - `crf` integer — Constant Rate Factor for quality-based encoding (0-51), lower values = higher quality, 18-28 typical range, 23 is default for h264. - `fixedGOP` boolean — When true, enforces fixed Group of Pictures size disabling scene change detection, ensures consistent segment sizes for HLS/DASH. - `frameRate` integer — Target frame rate in fps (1-120), FFmpeg drops or duplicates frames to match, common values: 24, 25, 30, 50, 60, omit to preserve source fps. - `height` integer — Target height in pixels (0-2400), used with autoHeight or unconstrained ResizeType, common values: 360, 480, 720, 1080, 1440, 2160. - `keyframeInterval` integer — Maximum frames between keyframes/I-frames (1-1000), recommended default 250, lower values improve seeking but increase file size, critical for HLS segment alignment. - `maxBitrate` string — Maximum allowed bitrate for variable bitrate encoding (e.g., '2M'), prevents bitrate spikes, requires BufferSize to be set. - `minBitrate` string — Minimum allowed bitrate for variable bitrate encoding (e.g., '500k'), ensures minimum quality in low-complexity scenes. - `percentage` integer — Scaling percentage (1-1000), used when ResizeType is 'percentage', 50 = half size, 100 = same size, 200 = double size. - `resizeType` string, required — Video scaling strategy: empty (no resize), autoHeight (set width), autoWidth (set height), unconstrained (set both), percentage (scale by %). - `sceneChangeThreshold` integer — FFmpeg scene change detection sensitivity (0-1000), 0 disables scene detection, higher values require more significant changes to insert keyframe. - `width` integer — Target width in pixels (0-2400), used with autoWidth or unconstrained ResizeType, FFmpeg scales video maintaining or ignoring aspect ratio. - `playlist` V1PipelinePlaylist, nullable — Optional adaptive bitrate playlist configuration (e.g., HLS master playlist), combines multiple quality outputs for adaptive streaming. - `enabled` boolean, required — Whether to generate an adaptive bitrate playlist that combines multiple output qualities for seamless quality switching. - `format` string, required — Playlist format type, currently supports 'hls' (HTTP Live Streaming) for Apple-compatible adaptive streaming. - `hls` V1PipelinePlaylistHLS, nullable — HLS-specific configuration parameters when format is 'hls', defines segmentation and playlist generation settings - `segmentDuration` integer, required — Duration of each HLS segment in seconds, FFmpeg splits the video into chunks of this length for adaptive streaming (typical values: 2-10 seconds). - `name` string, required — Name of the playlist file to be generated (e.g., 'master.m3u8' for HLS), used as the entry point for video playback. - `playlistOnly` boolean — When true, only generates the playlist file without individual output files, useful for post-processing or external transcoding workflows. - `thumbs` V1PipelineThumbs, nullable — Optional thumbnail generation configuration, extracts still images from the video at specified intervals using FFmpeg. - `format` string, required — Image format for generated thumbnails (jpg or png), jpg provides smaller file sizes while png supports transparency. - `interval` integer, required — Time interval in seconds between thumbnail extractions, FFmpeg captures a frame every N seconds throughout the video duration. - `tile` boolean — When true, combines multiple thumbnails into a single tiled sprite sheet image, reducing HTTP requests and improving preview performance. - `watermarks` V1PipelineWatermark[] — Optional watermark overlays to apply to the video outputs, supports multiple watermarks with different positions and sizes. - `enabled` boolean, required — Whether to apply this watermark overlay to the transcoded video output. - `height` integer, required — Height of the watermark overlay in pixels (0-4096), maintains aspect ratio when combined with width. - `input` V1Input, nullable, required — Source location of the watermark image file (supports PNG with transparency for best results). - `default` boolean — When true, marks this input as the default track (used for audio/subtitle tracks to indicate the primary or preferred track) - `http` V1HTTPInput, nullable — HTTP input configuration when protocol is 'http', contains the URL to retrieve the file from. - `url` string, required — HTTP or HTTPS URL of the input file to download, supports direct video/audio/subtitle file downloads from web servers. - `protocol` string, required — Specifies the source protocol to use for retrieving the input file (s3 or http) - `s3` V1S3Input, nullable — S3 input configuration when protocol is 's3', contains bucket, object key, and optional endpoint credentials. - `bucket` string, required — S3 bucket name where the input file is stored (3-64 characters). - `endpoint` V1S3Endpoint, nullable, required — Optional S3-compatible storage endpoint configuration, defaults to system-configured endpoint if omitted. - … - `object` string, required — S3 object key (file name) of the input file to be retrieved, combined with prefix to form the full object path. - `prefix` string — Optional directory path prefix within the bucket, used to organize objects in folder-like structures. - `padding` V1WatermarkPadding, nullable, required — Positioning and padding configuration for placing the watermark on the video frame. - `h` integer, required — Vertical padding in pixels from the edge of the video frame, determines the distance between the watermark and top/bottom edge. - `position` string, required — Corner position where the watermark will be placed (top_left, top_right, bottom_left, or bottom_right). - `w` integer, required — Horizontal padding in pixels from the edge of the video frame, determines the distance between the watermark and left/right edge. - `width` integer, required — Width of the watermark overlay in pixels (0-7680), used by FFmpeg's overlay filter to scale the watermark. - `subtitles` V1Subtitle[] — Optional subtitle tracks to embed or burn into the transcoded video (max 4), supports SRT, VTT, ASS, and other FFmpeg-compatible subtitle formats. - `enabled` boolean, required — Whether this subtitle track should be processed and included in the transcoded output. - `input` V1Input, nullable, required — Source location of the watermark image file (supports PNG with transparency for best results). - `default` boolean — When true, marks this input as the default track (used for audio/subtitle tracks to indicate the primary or preferred track) - `http` V1HTTPInput, nullable — HTTP input configuration when protocol is 'http', contains the URL to retrieve the file from. - `url` string, required — HTTP or HTTPS URL of the input file to download, supports direct video/audio/subtitle file downloads from web servers. - `protocol` string, required — Specifies the source protocol to use for retrieving the input file (s3 or http) - `s3` V1S3Input, nullable — S3 input configuration when protocol is 's3', contains bucket, object key, and optional endpoint credentials. - `bucket` string, required — S3 bucket name where the input file is stored (3-64 characters). - `endpoint` V1S3Endpoint, nullable, required — Optional S3-compatible storage endpoint configuration, defaults to system-configured endpoint if omitted. - `accessKey` string — S3 access key ID for authentication, required for non-Kise endpoints that need explicit credentials. - `address` string, required — S3-compatible endpoint URL (e.g., 's3.amazonaws.com' or custom MinIO endpoint), defines where to connect for S3 operations. - `kise` boolean, required — When true, uses Kise internal S3 service for storage operations, bypassing S3 credentials. - `secretKey` string — S3 secret access key for authentication, paired with AccessKey for secure S3 API access. - `object` string, required — S3 object key (file name) of the input file to be retrieved, combined with prefix to form the full object path. - `prefix` string — Optional directory path prefix within the bucket, used to organize objects in folder-like structures. - `language` string, required — ISO 639-2 language code for the subtitle track (e.g., 'eng' for English, 'fra' for French) - `name` string — Optional display name for the subtitle track, useful for identifying the track in multi-subtitle videos - `status` V1TranscodeStatus, required — Current observed state of the Transcode - `changedOn` string, date-time - `lastError` string — Most recent error message encountered during transcoding, preserved across retries for troubleshooting. - `message` string — Human-readable status message providing additional context about the current state. - `outputBucket` string — S3 bucket where the transcoded output was stored, recorded for audit and tracking purposes. - `outputPrefix` string — S3 object key prefix (folder path) where the transcoded files were stored. - `outputSizes` V1OutputSize[] — List of output files with their sizes and compression ratios for each quality variant or format produced. - `compressionRatio` string, required — Compression ratio achieved compared to the original input (e.g., '0.45' means 45% of original size), indicating encoding efficiency. - `key` string, required — S3 object key (file path) of the transcoded output file, uniquely identifying each quality variant or format. - `size` string, required — File size of the transcoded output in human-readable format (e.g., '125.5 MB'), useful for storage and bandwidth planning. - `outputUrl` string — Public URL or path to access the transcoded video output after successful completion. - `progress` string — FFmpeg transcoding progress indicator (e.g., percentage or time processed), updated during the Transcoding state. - `retries` integer — Number of retry attempts for this transcode job in case of transient failures - `speed` string — FFmpeg transcoding speed multiplier (e.g., '2.5x' means processing 2.5 seconds of video per second of real time) - `state` string — Current state of the transcode job (Scheduled, Preparing, Downloading, Transcoding, Completed, Failed, etc.). - `worker` string — Identifier of the worker pod/node processing this transcode job, useful for debugging and load distribution. ## Response `201` The transcode was successfully created. The response contains the complete transcode details including the assigned unique identifier. - V2Transcode - `apiVersion` 'delivery/v2' | 'delivery/v2.1', required — Version identifier of the API schema - `kind` 'Transcode', required — The string value 'Transcode' that identifies the schema - `metadata` V2ObjectMeta, required — Standard resource metadata fields - `creationTimestamp` string, date-time, required - `labels` object, required — Labels are key-value pairs attached to resources for organization and categorization - `name` string, required — User-provided name that uniquely identifies the resource within its workspace - `namespace` string, required — Namespace is the namespace in which the resource exists - `uid` string, required — System-generated unique identifier for the resource - `spec` V1TranscodeSpec, required — Desired configuration for the Transcode - `audios` V1Audio[] — Optional additional audio tracks to include in the transcoded output (max 4), each with language and title metadata. - `enabled` boolean, required — Whether this audio track should be processed and included in the transcoded output. - `input` V1Input, nullable, required — Source location of the watermark image file (supports PNG with transparency for best results). - `default` boolean — When true, marks this input as the default track (used for audio/subtitle tracks to indicate the primary or preferred track) - `http` V1HTTPInput, nullable — HTTP input configuration when protocol is 'http', contains the URL to retrieve the file from. - `url` string, required — HTTP or HTTPS URL of the input file to download, supports direct video/audio/subtitle file downloads from web servers. - `protocol` string, required — Specifies the source protocol to use for retrieving the input file (s3 or http) - `s3` V1S3Input, nullable — S3 input configuration when protocol is 's3', contains bucket, object key, and optional endpoint credentials. - `bucket` string, required — S3 bucket name where the input file is stored (3-64 characters). - `endpoint` V1S3Endpoint, nullable, required — Optional S3-compatible storage endpoint configuration, defaults to system-configured endpoint if omitted. - `accessKey` string — S3 access key ID for authentication, required for non-Kise endpoints that need explicit credentials. - `address` string, required — S3-compatible endpoint URL (e.g., 's3.amazonaws.com' or custom MinIO endpoint), defines where to connect for S3 operations. - `kise` boolean, required — When true, uses Kise internal S3 service for storage operations, bypassing S3 credentials. - `secretKey` string — S3 secret access key for authentication, paired with AccessKey for secure S3 API access. - `object` string, required — S3 object key (file name) of the input file to be retrieved, combined with prefix to form the full object path. - `prefix` string — Optional directory path prefix within the bucket, used to organize objects in folder-like structures. - `language` string, required — ISO 639-2 language code for the audio track (e.g., 'eng' for English, 'spa' for Spanish), used by FFmpeg for metadata. - `title` string, required — Optional title/description for the audio track, displayed in media players that support multi-audio selection. - `input` V1VideoInput, nullable, required — The input video to be transcoded. - `audioLanguage` string — ISO 639-2 language code for the input audio track (e.g., 'eng', 'fra'), used by FFmpeg for audio stream identification. - `audioTitle` string — Optional title metadata for the audio track in the input video, displayed in media players supporting audio track selection - `http` V1HTTPInput, nullable — HTTP input configuration when protocol is 'http', contains the URL to retrieve the file from. - `url` string, required — HTTP or HTTPS URL of the input file to download, supports direct video/audio/subtitle file downloads from web servers. - `protocol` string, required — Specifies the source protocol to use for getting the video (s3 or http) - `s3` V1S3Input, nullable — S3 input configuration when protocol is 's3', contains bucket, object key, and optional endpoint credentials. - `bucket` string, required — S3 bucket name where the input file is stored (3-64 characters). - `endpoint` V1S3Endpoint, nullable, required — Optional S3-compatible storage endpoint configuration, defaults to system-configured endpoint if omitted. - `accessKey` string — S3 access key ID for authentication, required for non-Kise endpoints that need explicit credentials. - `address` string, required — S3-compatible endpoint URL (e.g., 's3.amazonaws.com' or custom MinIO endpoint), defines where to connect for S3 operations. - `kise` boolean, required — When true, uses Kise internal S3 service for storage operations, bypassing S3 credentials. - `secretKey` string — S3 secret access key for authentication, paired with AccessKey for secure S3 API access. - `object` string, required — S3 object key (file name) of the input file to be retrieved, combined with prefix to form the full object path. - `prefix` string — Optional directory path prefix within the bucket, used to organize objects in folder-like structures. - `skipAudio` boolean — When true, skips processing audio streams from the input video, useful for video-only transcoding or when replacing audio entirely - `skipSubtitle` boolean — When true, skips processing subtitle streams from the input video, used when subtitles should not be carried over to the output - `output` V1Output, nullable, required — The output configuration to store the transcoded video. - `bucket` string, required — Target S3 bucket name where transcoded video files will be stored (3-64 characters). - `endpoint` V1S3Endpoint, nullable, required — Optional S3-compatible storage endpoint configuration, defaults to system-configured endpoint if omitted. - `accessKey` string — S3 access key ID for authentication, required for non-Kise endpoints that need explicit credentials. - `address` string, required — S3-compatible endpoint URL (e.g., 's3.amazonaws.com' or custom MinIO endpoint), defines where to connect for S3 operations. - `kise` boolean, required — When true, uses Kise internal S3 service for storage operations, bypassing S3 credentials. - `secretKey` string — S3 secret access key for authentication, paired with AccessKey for secure S3 API access. - `prefix` string — Optional object key prefix (folder path) within the bucket for organizing transcoded outputs. - `pipelineName` string — Reference to an existing Pipeline resource by name for reusable transcode configurations. - `pipelineSpec` V1PipelineSpec — Desired configuration for the Pipeline - `autoPresets` boolean — When true, automatically generates outputs for all video presets in the namespace, eliminating the need to manually specify Outputs array. - `outputs` V1PipelineOutput[] — List of output configurations with their associated presets (1-5 outputs), required when AutoPresets is false, each defining a quality/format variant. - `excludeFromPlaylist` boolean — When true, excludes this output from being included in adaptive bitrate playlists (e.g., HLS master playlist). - `excludeFromThumbs` boolean — When true, skips thumbnail generation for this specific output, useful for audio-only or low-quality variants. - `key` string, required — Unique identifier for this output variant (1-64 characters), used as part of the output filename and for referencing in playlists. - `presetName` string — Reference to an existing Preset resource by name, the PresetSpec will be automatically populated from this preset at runtime. - `presetSpec` V1PresetSpec — Desired configuration for the Preset - `audio` V1PresetAudio, nullable — Audio encoding configuration including codec, bitrate, and sample rate, required unless SkipAudio is true - `bitrate` string — Target audio bitrate (e.g., '64k', '128k', '192k', '320k', '1m'), higher bitrates provide better quality but larger file sizes, typical range 96k-320k. - `codec` string, required — Audio codec for encoding (aac, mp3, vorbis, opus, copy), 'copy' streams without re-encoding for faster processing, aac recommended for broad compatibility. - `sampleRate` integer — Audio sample rate of input audio to produce output audio in Hz (22050, 32000, 44100, 48000, 96000), 44100/48000 are standard for most content, higher rates for professional audio. - `container` string, required — Output container format (mp4, m4v, mov, avi, flv), determines the file wrapper format that FFmpeg will mux the encoded streams into. - `description` string — Human-readable description of this preset's purpose (max 128 characters), useful for identifying preset characteristics like '720p High Quality'. - `noFragment` boolean — When true, disables MP4 fragmentation (faststart/moov atom relocation), may impact progressive playback but reduces processing overhead. - `pixelFormat` string — FFmpeg pixel format for video output, yuv420p is the most compatible format for H.264/H.265 ensuring broad device support. - `skipAudio` boolean — When true, removes all audio streams from the output, creating a video-only file useful for silent videos or separate audio processing - `skipSubtitle` boolean — When true, removes all subtitle streams from the output, useful when subtitles should be handled separately or not included. - `skipVideo` boolean — When true, removes all video streams from the output, creating an audio-only file for music or podcast extraction. - `speed` string — FFmpeg encoding speed preset (medium, veryfast, ultrafast), trades encoding time for compression efficiency - faster speeds produce larger files but good quality. - `video` V1PresetVideo, nullable — Video encoding configuration including codec, resolution, bitrate, and quality settings, required unless SkipVideo is true - `bitrate` string — Target video bitrate (e.g., '1000k', '5M'), used for constant/average bitrate encoding, mutually exclusive with CRF for rate control. - `bufferSize` string — Video buffer verifier (VBV) buffer size (e.g., '2M'), controls bitrate variability, typically 1-2x MaxBitrate for streaming. - `codec` string, required — Video codec for encoding (h264, h265/HEVC, vp9), h264 offers best compatibility, h265 better compression, vp9 for WebM/VP9 workflows. - `crf` integer — Constant Rate Factor for quality-based encoding (0-51), lower values = higher quality, 18-28 typical range, 23 is default for h264. - `fixedGOP` boolean — When true, enforces fixed Group of Pictures size disabling scene change detection, ensures consistent segment sizes for HLS/DASH. - `frameRate` integer — Target frame rate in fps (1-120), FFmpeg drops or duplicates frames to match, common values: 24, 25, 30, 50, 60, omit to preserve source fps. - `height` integer — Target height in pixels (0-2400), used with autoHeight or unconstrained ResizeType, common values: 360, 480, 720, 1080, 1440, 2160. - `keyframeInterval` integer — Maximum frames between keyframes/I-frames (1-1000), recommended default 250, lower values improve seeking but increase file size, critical for HLS segment alignment. - `maxBitrate` string — Maximum allowed bitrate for variable bitrate encoding (e.g., '2M'), prevents bitrate spikes, requires BufferSize to be set. - `minBitrate` string — Minimum allowed bitrate for variable bitrate encoding (e.g., '500k'), ensures minimum quality in low-complexity scenes. - `percentage` integer — Scaling percentage (1-1000), used when ResizeType is 'percentage', 50 = half size, 100 = same size, 200 = double size. - `resizeType` string, required — Video scaling strategy: empty (no resize), autoHeight (set width), autoWidth (set height), unconstrained (set both), percentage (scale by %). - `sceneChangeThreshold` integer — FFmpeg scene change detection sensitivity (0-1000), 0 disables scene detection, higher values require more significant changes to insert keyframe. - `width` integer — Target width in pixels (0-2400), used with autoWidth or unconstrained ResizeType, FFmpeg scales video maintaining or ignoring aspect ratio. - `playlist` V1PipelinePlaylist, nullable — Optional adaptive bitrate playlist configuration (e.g., HLS master playlist), combines multiple quality outputs for adaptive streaming. - `enabled` boolean, required — Whether to generate an adaptive bitrate playlist that combines multiple output qualities for seamless quality switching. - `format` string, required — Playlist format type, currently supports 'hls' (HTTP Live Streaming) for Apple-compatible adaptive streaming. - `hls` V1PipelinePlaylistHLS, nullable — HLS-specific configuration parameters when format is 'hls', defines segmentation and playlist generation settings - `segmentDuration` integer, required — Duration of each HLS segment in seconds, FFmpeg splits the video into chunks of this length for adaptive streaming (typical values: 2-10 seconds). - `name` string, required — Name of the playlist file to be generated (e.g., 'master.m3u8' for HLS), used as the entry point for video playback. - `playlistOnly` boolean — When true, only generates the playlist file without individual output files, useful for post-processing or external transcoding workflows. - `thumbs` V1PipelineThumbs, nullable — Optional thumbnail generation configuration, extracts still images from the video at specified intervals using FFmpeg. - `format` string, required — Image format for generated thumbnails (jpg or png), jpg provides smaller file sizes while png supports transparency. - `interval` integer, required — Time interval in seconds between thumbnail extractions, FFmpeg captures a frame every N seconds throughout the video duration. - `tile` boolean — When true, combines multiple thumbnails into a single tiled sprite sheet image, reducing HTTP requests and improving preview performance. - `watermarks` V1PipelineWatermark[] — Optional watermark overlays to apply to the video outputs, supports multiple watermarks with different positions and sizes. - `enabled` boolean, required — Whether to apply this watermark overlay to the transcoded video output. - `height` integer, required — Height of the watermark overlay in pixels (0-4096), maintains aspect ratio when combined with width. - `input` V1Input, nullable, required — Source location of the watermark image file (supports PNG with transparency for best results). - `default` boolean — When true, marks this input as the default track (used for audio/subtitle tracks to indicate the primary or preferred track) - `http` V1HTTPInput, nullable — HTTP input configuration when protocol is 'http', contains the URL to retrieve the file from. - `url` string, required — HTTP or HTTPS URL of the input file to download, supports direct video/audio/subtitle file downloads from web servers. - `protocol` string, required — Specifies the source protocol to use for retrieving the input file (s3 or http) - `s3` V1S3Input, nullable — S3 input configuration when protocol is 's3', contains bucket, object key, and optional endpoint credentials. - `bucket` string, required — S3 bucket name where the input file is stored (3-64 characters). - `endpoint` V1S3Endpoint, nullable, required — Optional S3-compatible storage endpoint configuration, defaults to system-configured endpoint if omitted. - … - `object` string, required — S3 object key (file name) of the input file to be retrieved, combined with prefix to form the full object path. - `prefix` string — Optional directory path prefix within the bucket, used to organize objects in folder-like structures. - `padding` V1WatermarkPadding, nullable, required — Positioning and padding configuration for placing the watermark on the video frame. - `h` integer, required — Vertical padding in pixels from the edge of the video frame, determines the distance between the watermark and top/bottom edge. - `position` string, required — Corner position where the watermark will be placed (top_left, top_right, bottom_left, or bottom_right). - `w` integer, required — Horizontal padding in pixels from the edge of the video frame, determines the distance between the watermark and left/right edge. - `width` integer, required — Width of the watermark overlay in pixels (0-7680), used by FFmpeg's overlay filter to scale the watermark. - `subtitles` V1Subtitle[] — Optional subtitle tracks to embed or burn into the transcoded video (max 4), supports SRT, VTT, ASS, and other FFmpeg-compatible subtitle formats. - `enabled` boolean, required — Whether this subtitle track should be processed and included in the transcoded output. - `input` V1Input, nullable, required — Source location of the watermark image file (supports PNG with transparency for best results). - `default` boolean — When true, marks this input as the default track (used for audio/subtitle tracks to indicate the primary or preferred track) - `http` V1HTTPInput, nullable — HTTP input configuration when protocol is 'http', contains the URL to retrieve the file from. - `url` string, required — HTTP or HTTPS URL of the input file to download, supports direct video/audio/subtitle file downloads from web servers. - `protocol` string, required — Specifies the source protocol to use for retrieving the input file (s3 or http) - `s3` V1S3Input, nullable — S3 input configuration when protocol is 's3', contains bucket, object key, and optional endpoint credentials. - `bucket` string, required — S3 bucket name where the input file is stored (3-64 characters). - `endpoint` V1S3Endpoint, nullable, required — Optional S3-compatible storage endpoint configuration, defaults to system-configured endpoint if omitted. - `accessKey` string — S3 access key ID for authentication, required for non-Kise endpoints that need explicit credentials. - `address` string, required — S3-compatible endpoint URL (e.g., 's3.amazonaws.com' or custom MinIO endpoint), defines where to connect for S3 operations. - `kise` boolean, required — When true, uses Kise internal S3 service for storage operations, bypassing S3 credentials. - `secretKey` string — S3 secret access key for authentication, paired with AccessKey for secure S3 API access. - `object` string, required — S3 object key (file name) of the input file to be retrieved, combined with prefix to form the full object path. - `prefix` string — Optional directory path prefix within the bucket, used to organize objects in folder-like structures. - `language` string, required — ISO 639-2 language code for the subtitle track (e.g., 'eng' for English, 'fra' for French) - `name` string — Optional display name for the subtitle track, useful for identifying the track in multi-subtitle videos - `status` V1TranscodeStatus, required — Current observed state of the Transcode - `changedOn` string, date-time - `lastError` string — Most recent error message encountered during transcoding, preserved across retries for troubleshooting. - `message` string — Human-readable status message providing additional context about the current state. - `outputBucket` string — S3 bucket where the transcoded output was stored, recorded for audit and tracking purposes. - `outputPrefix` string — S3 object key prefix (folder path) where the transcoded files were stored. - `outputSizes` V1OutputSize[] — List of output files with their sizes and compression ratios for each quality variant or format produced. - `compressionRatio` string, required — Compression ratio achieved compared to the original input (e.g., '0.45' means 45% of original size), indicating encoding efficiency. - `key` string, required — S3 object key (file path) of the transcoded output file, uniquely identifying each quality variant or format. - `size` string, required — File size of the transcoded output in human-readable format (e.g., '125.5 MB'), useful for storage and bandwidth planning. - `outputUrl` string — Public URL or path to access the transcoded video output after successful completion. - `progress` string — FFmpeg transcoding progress indicator (e.g., percentage or time processed), updated during the Transcoding state. - `retries` integer — Number of retry attempts for this transcode job in case of transient failures - `speed` string — FFmpeg transcoding speed multiplier (e.g., '2.5x' means processing 2.5 seconds of video per second of real time) - `state` string — Current state of the transcode job (Scheduled, Preparing, Downloading, Transcoding, Completed, Failed, etc.). - `worker` string — Identifier of the worker pod/node processing this transcode job, useful for debugging and load distribution. ## Other responses - `400` — Bad Request - invalid request payload or parameters - `401` — Unauthorized - invalid or expired authentication token - `403` — Forbidden - insufficient permissions - `409` — Conflict - resource with the same name already exists --- [API](https://skmtc.dev/sotoon/apis/sotoon-api.md) · [All operations](https://skmtc.dev/sotoon/apis/sotoon-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/sotoon/sotoon-api/revisions/c937cd9861c5/schema)