Skip to content

API for transcoding in S3

General Information

This section describes API methods for working with transcoding tasks in S3.

All responses, including errors, are returned in JSON format.

Service Overview

The service provides an API for transcoding and trimming video files stored in S3-compatible storage systems.

It enables you to:

  • Change formats: adapt videos for web and mobile devices.
  • Modify resolution and bitrate: create lightweight versions from heavy source files (downscaling).
  • Trim videos: extract specific fragments.
  • Use presets: apply ready-made configuration templates for quick integration.

The service retrieves the source file from your S3 bucket, processes it, and uploads the result back to the specified S3 bucket.

Core Concepts

Task — the basic unit of work in the service. A single task can process one source file into multiple output formats (for example, converting one 4K video into 1080p, 720p, and preview versions).

Preset — a saved set of transcoding settings (resolution, bitrate, codec) that can be reused. Presets simplify integration by eliminating the need to pass technical parameters with each request.

S3-Source / S3-Target — storage connection parameters. - Source: where the service downloads the original file from. - Target: where the service uploads the processed result to.

How It Works

Workflow

  1. Initiation: You send an API request to create a task, specifying access to the source file and desired parameters (or a preset).
  2. Queueing: The service accepts the task and returns a task_id. Task status becomes pending.
  3. Processing: An available worker picks up the task, downloads the file from S3, and performs transcoding (status changes to processing).
  4. Completion: The result is uploaded to your S3 bucket. Status changes to completed (or failed on error).

Operation Types

Operation Type Description Use Cases
Transcoding Full re-encoding of the video stream with changes to resolution, bitrate, or codec. Creating versions for different devices (720p, 1080p), web optimization.
Trimming Cutting a video fragment by time markers (from_s, duration). Creating teasers, clips, removing unnecessary beginning/end.

Technical Limitations

The following limits apply to ensure service stability:

  1. Supported Containers:

    • Input: MP4, MKV, AVI, MOV, FLV, WEBM.
    • Output: MP4.

  2. Video Parameters:

    • Maximum resolution: 8294400 pixels with max side length 3840 (4K)
    • Maximum bitrate: 50 Mbps (50000 kbps)

  3. Task Limitations:

    • Maximum 10 output files per task (one source → up to 10 versions).

Best Practices

  1. Use presets: This reduces the likelihood of errors when manually entering bitrate and resolution parameters.
  2. Monitor tasks: Regularly poll task status to track progress and catch errors early.
  3. Security: Use separate Access Key/Secret Key pairs for the transcoding service with read-only permissions on the source bucket and write permissions on the target bucket.

API for Transcoding to S3

  • Required headers: CDN-AUTH-TOKEN (authorization token, see Authorization)
  • Response Content-Type: application/json
  • All responses, including errors, are returned in a common structure: the status key is always returned (except for 204 response code); in case of a successful response, the data key is returned with response data where applicable, otherwise the description key is sometimes returned with an error description.