The Preset object

Presets are reusable encoding configurations that define video codec, resolution, quality, audio settings, and container format. Transcodely provides system presets for common use cases. You can create custom presets or duplicate system presets as a starting point.

Base path: transcodely.v1.PresetService Requires: X-Organization-ID header on all endpoints.

Attributes

Attribute	Type	Description
`id`	string	Unique identifier with `pst_` prefix (e.g., `"pst_x9y8z7w6v5"`).
`slug`	string	URL-safe slug. Lowercase letters, numbers, and underscores only.
`name`	string	Human-readable name.
`description`	string	Optional description. Omitted if not set.
`content_type`	string	Content type hint for encoder tuning. One of `"film"`, `"animation"`, `"grain"`, `"gaming"`, `"sports"`, `"stillimage"`.
`container`	string	Container format. One of `"mp4"`, `"webm"`, `"mkv"`, `"ts"`, `"mov"`.
`faststart`	boolean	Whether faststart (moov atom at beginning) is enabled for progressive MP4.
`delivery_format`	string	Delivery format. One of `"progressive"`, `"hls"`, `"dash"`, `"cmaf"`.
`streaming`	object	Streaming configuration for HLS/DASH outputs. `null` if not configured.
`video`	object	Video encoding settings. See Video settings.
`audio`	object	Audio encoding settings. See Audio settings.
`quality_tier`	string	Quality tier. One of `"economy"`, `"standard"`, `"premium"`.
`estimated_cost_per_minute`	number	Estimated cost per minute of encoded video in EUR. Omitted if not calculated.
`system_preset`	boolean	`true` if this is a read-only system preset.
`created_at`	string	ISO 8601 timestamp.
`updated_at`	string	ISO 8601 timestamp.

{
  "id": "pst_x9y8z7w6v5",
  "slug": "web_1080p_standard",
  "name": "Web 1080p Standard",
  "description": "H.264 1080p for web streaming",
  "content_type": "film",
  "container": "mp4",
  "faststart": true,
  "delivery_format": "progressive",
  "streaming": null,
  "video": {
    "codec": "h264",
    "resolution": "1080p",
    "bitrate_mode": "crf",
    "crf": 23,
    "profile": "high",
    "level": "4.0",
    "encoder_preset": "medium"
  },
  "audio": {
    "codec": "aac",
    "bitrate_kbps": 128,
    "sample_rate": 48000,
    "channels": 2
  },
  "quality_tier": "standard",
  "estimated_cost_per_minute": 0.053,
  "system_preset": false,
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:00Z"
}

Video settings

Attribute	Type	Description
`codec`	string	Video codec. One of `"h264"`, `"h265"`, `"vp9"`, `"av1"`.
`resolution`	string	Resolution preset. One of `"480p"`, `"720p"`, `"1080p"`, `"1440p"`, `"2160p"`, `"4320p"`.
`width`	integer	Custom width in pixels (128-7680). Use with `height` for non-standard dimensions.
`height`	integer	Custom height in pixels (128-4320).
`framerate`	integer	Target frame rate. `0` keeps the original. Max 240.
`bitrate_mode`	string	Bitrate control mode. One of `"crf"`, `"cbr"`, `"vbr"`.
`crf`	integer	Constant Rate Factor. Range depends on codec: H.264 15-35, H.265 18-35, VP9 15-50, AV1 20-55.
`bitrate_kbps`	integer	Target bitrate for CBR/VBR (100-100000 kbps).
`max_bitrate_kbps`	integer	Max bitrate for VBV buffering (100-240000 kbps).
`buffer_size_kbps`	integer	VBV buffer size (100-480000 kbps).
`profile`	string	Codec profile (e.g., `"baseline"`, `"main"`, `"high"`).
`level`	string	Codec level (e.g., `"3.0"`, `"4.0"`, `"5.1"`).
`encoder_preset`	string	Encoder speed/quality tradeoff. H.264/H.265: `"ultrafast"` to `"slower"`. AV1: `"3"` to `"12"`.
`tune`	string	Content-aware tuning. H.264: `"film"`, `"animation"`, `"grain"`, `"stillimage"`, `"fastdecode"`.
`keyint`	integer	GOP size / keyframe interval in frames (1-600).
`bframes`	integer	Number of B-frames (0-16).
`refs`	integer	Number of reference frames (1-16).

Audio settings

Attribute	Type	Description
`codec`	string	Audio codec. One of `"aac"`, `"opus"`, `"mp3"`.
`bitrate_kbps`	integer	Target bitrate (32-512 kbps).
`sample_rate`	integer	Sample rate in Hz. `0` keeps the original. Common values: 44100, 48000.
`channels`	integer	Number of channels. `0` keeps the original. Max 8.
`normalize`	boolean	Apply EBU R128 loudness normalization.

Create a preset

Create a new custom preset with video and audio encoding settings.

POST /transcodely.v1.PresetService/Create

Parameters

Parameter	Type	Required	Description
`slug`	string	Yes	URL-safe slug (3-64 chars). Lowercase letters, numbers, and underscores only. Must be unique per app.
`name`	string	Yes	Human-readable name (1-128 chars).
`description`	string	No	Description (max 1024 chars).
`content_type`	string	No	Content type hint: `"film"`, `"animation"`, `"grain"`, `"gaming"`, `"sports"`, `"stillimage"`.
`container`	string	Yes	Container format: `"mp4"`, `"webm"`, `"mkv"`, `"ts"`, `"mov"`.
`faststart`	boolean	No	Enable faststart for progressive MP4. Default: `true`.
`delivery_format`	string	No	Delivery format: `"progressive"`, `"hls"`, `"dash"`, `"cmaf"`.
`streaming`	object	No	Streaming configuration for HLS/DASH outputs.
`video`	object	Yes	Video encoding settings. See Video settings.
`audio`	object	Yes	Audio encoding settings. See Audio settings.
`quality_tier`	string	No	Quality tier: `"economy"`, `"standard"`, `"premium"`.

Returns

The created Preset object.

Example

curl -X POST https://api.transcodely.com/transcodely.v1.PresetService/Create 
  -H "Authorization: Bearer {{API_KEY}}" 
  -H "X-Organization-ID: {{ORG_ID}}" 
  -H "Content-Type: application/json" 
  -d '{
    "slug": "web_1080p_standard",
    "name": "Web 1080p Standard",
    "description": "H.264 1080p for web streaming",
    "content_type": "film",
    "container": "mp4",
    "faststart": true,
    "delivery_format": "progressive",
    "video": {
      "codec": "h264",
      "resolution": "1080p",
      "bitrate_mode": "crf",
      "crf": 23,
      "profile": "high",
      "level": "4.0",
      "encoder_preset": "medium"
    },
    "audio": {
      "codec": "aac",
      "bitrate_kbps": 128,
      "sample_rate": 48000,
      "channels": 2
    },
    "quality_tier": "standard"
  }'

{
  "preset": {
    "id": "pst_x9y8z7w6v5",
    "slug": "web_1080p_standard",
    "name": "Web 1080p Standard",
    "description": "H.264 1080p for web streaming",
    "content_type": "film",
    "container": "mp4",
    "faststart": true,
    "delivery_format": "progressive",
    "video": {
      "codec": "h264",
      "resolution": "1080p",
      "bitrate_mode": "crf",
      "crf": 23,
      "profile": "high",
      "level": "4.0",
      "encoder_preset": "medium"
    },
    "audio": {
      "codec": "aac",
      "bitrate_kbps": 128,
      "sample_rate": 48000,
      "channels": 2
    },
    "quality_tier": "standard",
    "estimated_cost_per_minute": 0.053,
    "system_preset": false,
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z"
  }
}

Retrieve a preset

Retrieve a preset by ID.

POST /transcodely.v1.PresetService/Get

Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Preset ID (e.g., `"pst_x9y8z7w6v5"`).

Returns

The Preset object.

Example

curl -X POST https://api.transcodely.com/transcodely.v1.PresetService/Get 
  -H "Authorization: Bearer {{API_KEY}}" 
  -H "X-Organization-ID: {{ORG_ID}}" 
  -H "Content-Type: application/json" 
  -d '{"id": "pst_x9y8z7w6v5"}'

{
  "preset": {
    "id": "pst_x9y8z7w6v5",
    "slug": "web_1080p_standard",
    "name": "Web 1080p Standard",
    "description": "H.264 1080p for web streaming",
    "content_type": "film",
    "container": "mp4",
    "faststart": true,
    "delivery_format": "progressive",
    "video": {
      "codec": "h264",
      "resolution": "1080p",
      "bitrate_mode": "crf",
      "crf": 23,
      "profile": "high",
      "level": "4.0",
      "encoder_preset": "medium"
    },
    "audio": {
      "codec": "aac",
      "bitrate_kbps": 128,
      "sample_rate": 48000,
      "channels": 2
    },
    "quality_tier": "standard",
    "estimated_cost_per_minute": 0.053,
    "system_preset": false,
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z"
  }
}

Retrieve a preset by slug

Retrieve a preset by its slug instead of ID.

POST /transcodely.v1.PresetService/GetBySlug

Parameters

Parameter	Type	Required	Description
`slug`	string	Yes	Preset slug (e.g., `"web_1080p_standard"`). 1-64 chars.

Returns

The Preset object.

Example

curl -X POST https://api.transcodely.com/transcodely.v1.PresetService/GetBySlug 
  -H "Authorization: Bearer {{API_KEY}}" 
  -H "X-Organization-ID: {{ORG_ID}}" 
  -H "Content-Type: application/json" 
  -d '{"slug": "web_1080p_standard"}'

{
  "preset": {
    "id": "pst_x9y8z7w6v5",
    "slug": "web_1080p_standard",
    "name": "Web 1080p Standard",
    "description": "H.264 1080p for web streaming",
    "content_type": "film",
    "container": "mp4",
    "faststart": true,
    "delivery_format": "progressive",
    "video": {
      "codec": "h264",
      "resolution": "1080p",
      "bitrate_mode": "crf",
      "crf": 23,
      "profile": "high",
      "level": "4.0",
      "encoder_preset": "medium"
    },
    "audio": {
      "codec": "aac",
      "bitrate_kbps": 128,
      "sample_rate": 48000,
      "channels": 2
    },
    "quality_tier": "standard",
    "estimated_cost_per_minute": 0.053,
    "system_preset": false,
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z"
  }
}

List presets

List presets including both system presets and custom presets.

POST /transcodely.v1.PresetService/List

Parameters

Parameter	Type	Required	Description
`include_system`	boolean	No	Include system presets. Default: `true`.
`content_type`	string	No	Filter by content type: `"film"`, `"animation"`, `"grain"`, `"gaming"`, `"sports"`, `"stillimage"`.
`quality_tier`	string	No	Filter by quality tier: `"economy"`, `"standard"`, `"premium"`.
`video_codec`	string	No	Filter by video codec: `"h264"`, `"h265"`, `"vp9"`, `"av1"`.
`pagination`	object	No	Pagination parameters. See Pagination.

Returns

A list of Preset objects and pagination metadata.

Example

curl -X POST https://api.transcodely.com/transcodely.v1.PresetService/List 
  -H "Authorization: Bearer {{API_KEY}}" 
  -H "X-Organization-ID: {{ORG_ID}}" 
  -H "Content-Type: application/json" 
  -d '{
    "video_codec": "h264",
    "quality_tier": "standard",
    "pagination": {"limit": 20}
  }'

{
  "presets": [
    {
      "id": "pst_x9y8z7w6v5",
      "slug": "web_1080p_standard",
      "name": "Web 1080p Standard",
      "content_type": "film",
      "container": "mp4",
      "quality_tier": "standard",
      "estimated_cost_per_minute": 0.053,
      "system_preset": false,
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "next_cursor": "",
    "total_count": 1
  }
}

Update a preset

Update a custom preset. System presets cannot be modified — use Duplicate to create a customizable copy.

POST /transcodely.v1.PresetService/Update

Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Preset ID.
`slug`	string	No	New slug (3-64 chars, must be unique).
`name`	string	No	New name (1-128 chars).
`description`	string	No	New description (max 1024 chars).
`content_type`	string	No	New content type.
`container`	string	No	New container format.
`faststart`	boolean	No	New faststart setting.
`delivery_format`	string	No	New delivery format.
`streaming`	object	No	New streaming configuration.
`video`	object	No	New video settings. Replaces the entire video config.
`audio`	object	No	New audio settings. Replaces the entire audio config.
`quality_tier`	string	No	New quality tier.

Returns

The updated Preset object.

Example

curl -X POST https://api.transcodely.com/transcodely.v1.PresetService/Update 
  -H "Authorization: Bearer {{API_KEY}}" 
  -H "X-Organization-ID: {{ORG_ID}}" 
  -H "Content-Type: application/json" 
  -d '{
    "id": "pst_x9y8z7w6v5",
    "name": "Web 1080p Standard (v2)",
    "video": {
      "codec": "h264",
      "resolution": "1080p",
      "bitrate_mode": "crf",
      "crf": 21,
      "profile": "high",
      "level": "4.1",
      "encoder_preset": "slow"
    }
  }'

{
  "preset": {
    "id": "pst_x9y8z7w6v5",
    "slug": "web_1080p_standard",
    "name": "Web 1080p Standard (v2)",
    "description": "H.264 1080p for web streaming",
    "content_type": "film",
    "container": "mp4",
    "faststart": true,
    "delivery_format": "progressive",
    "video": {
      "codec": "h264",
      "resolution": "1080p",
      "bitrate_mode": "crf",
      "crf": 21,
      "profile": "high",
      "level": "4.1",
      "encoder_preset": "slow"
    },
    "audio": {
      "codec": "aac",
      "bitrate_kbps": 128,
      "sample_rate": 48000,
      "channels": 2
    },
    "quality_tier": "standard",
    "estimated_cost_per_minute": 0.061,
    "system_preset": false,
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-02-28T15:00:00Z"
  }
}

Duplicate a preset

Copy a preset (system or custom) as a new custom preset. This is the recommended way to customize a system preset.

POST /transcodely.v1.PresetService/Duplicate

Parameters

Parameter	Type	Required	Description
`source_id`	string	Yes	ID of the preset to copy.
`slug`	string	Yes	Slug for the new preset (3-64 chars, must be unique).
`name`	string	Yes	Name for the new preset (1-128 chars).

Returns

The newly created Preset object (copy of the source).

Example

curl -X POST https://api.transcodely.com/transcodely.v1.PresetService/Duplicate 
  -H "Authorization: Bearer {{API_KEY}}" 
  -H "X-Organization-ID: {{ORG_ID}}" 
  -H "Content-Type: application/json" 
  -d '{
    "source_id": "pst_system_h264_1080p",
    "slug": "my_custom_1080p",
    "name": "My Custom 1080p"
  }'

{
  "preset": {
    "id": "pst_a1b2c3d4e5",
    "slug": "my_custom_1080p",
    "name": "My Custom 1080p",
    "content_type": "film",
    "container": "mp4",
    "faststart": true,
    "delivery_format": "progressive",
    "video": {
      "codec": "h264",
      "resolution": "1080p",
      "bitrate_mode": "crf",
      "crf": 23,
      "profile": "high",
      "level": "4.0",
      "encoder_preset": "medium"
    },
    "audio": {
      "codec": "aac",
      "bitrate_kbps": 128,
      "sample_rate": 48000,
      "channels": 2
    },
    "quality_tier": "standard",
    "estimated_cost_per_minute": 0.053,
    "system_preset": false,
    "created_at": "2025-02-28T15:00:00Z",
    "updated_at": "2025-02-28T15:00:00Z"
  }
}

Archive a preset

Soft-delete a custom preset. System presets cannot be archived. Archived presets are not available for new jobs.

POST /transcodely.v1.PresetService/Archive

Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Preset ID.

Returns

The archived Preset object.

Example

curl -X POST https://api.transcodely.com/transcodely.v1.PresetService/Archive 
  -H "Authorization: Bearer {{API_KEY}}" 
  -H "X-Organization-ID: {{ORG_ID}}" 
  -H "Content-Type: application/json" 
  -d '{"id": "pst_x9y8z7w6v5"}'

{
  "preset": {
    "id": "pst_x9y8z7w6v5",
    "slug": "web_1080p_standard",
    "name": "Web 1080p Standard",
    "system_preset": false,
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-02-28T15:00:00Z"
  }
}

#The Preset object

#Attributes

#Video settings

#Audio settings

#Create a preset

#Parameters

#Returns

#Example

#Retrieve a preset

#Parameters

#Returns

#Example

#Retrieve a preset by slug

#Parameters

#Returns

#Example

#List presets

#Parameters

#Returns

#Example

#Update a preset

#Parameters

#Returns

#Example

#Duplicate a preset

#Parameters

#Returns

#Example

#Archive a preset

#Parameters

#Returns

#Example

The Preset object

Attributes

Video settings

Audio settings

Create a preset

Parameters

Returns

Example

Retrieve a preset

Parameters

Returns

Example

Retrieve a preset by slug

Parameters

Returns

Example

List presets

Parameters

Returns

Example

Update a preset

Parameters

Returns

Example

Duplicate a preset

Parameters

Returns

Example

Archive a preset

Parameters

Returns

Example