Create an Asset from a video Source. Processing starts asynchronously.
POST
/assets
Authorization
Authorization
header
string
required
Enter the project access token with the Bearer prefix, e.g. "Bearer project_access_token"
Bodyapplication/json
source_id
string
required
ID of the video Source to process.
max_resolution
string
Maximum streaming resolution. Omit to use the Project default, or the plan maximum if unset. 2160p requires Starter or above. Smaller sources are not upscaled. Does not affect static renditions.
Available options:
1080p2160p
metadata
object
String metadata with a maximum encoded JSON size of 2048 bytes.
Examples:
map[key:value key2:value2]
min_resolution
string
Minimum streaming resolution. Omit to use the Project default; auto removes the minimum. Must not exceed max_resolution. Smaller sources are not upscaled. Does not affect static renditions.
Available options:
auto240p360p540p720p1080p1440p2160p
path_template
string
PathTemplate specifies the Asset output folder relative to Storage base_prefix.
Supports {assetID} and case-sensitive {metadata.}; referenced values must be non-empty.
Ignored for Chunkify storage, which always uses {assetID}.
Overrides the Project default. Defaults to {assetID} when neither is set. Maximum template size: 1024 UTF-8 bytes. Expanded prefix: 768 bytes including base_prefix and trailing slash.
Examples:
videos/{metadata.VideoID}
preview_enabled
boolean
Allow public preview access without an API token. Omit to use the Project default. Does not control CDN or static download access.
storage
object
Output Storage. Omit to use the Project default. The path_template controls the folder for generated output paths.
id
string
ID of output Storage in this Project. Omit to use the Project default. Applies to all outputs, including static renditions added later.
title
string
Asset title, up to 256 characters. Defaults to an empty string.
Examples:
Launch video
workflow_id
object
WorkflowId specifies the Workflow to select. Omit to use the Project default. Set null to disable automatic actions. The current revision is pinned when creation is accepted.
Responses
application/json
data
object
required
can_add_static_renditions
boolean
required
Whether the Asset can accept new static rendition requests. Creation can still fail if the original video is no longer accessible.
created_at
string
date-time
required
When the Asset was created.
id
string
required
Unique Asset ID.
max_resolution
string
required
Maximum streaming resolution selected at creation. Does not limit static renditions.
Available options:
1080p2160p
metadata
object
required
String metadata attached to the Asset.
Examples:
map[key:value key2:value2]
min_resolution
string
required
Minimum streaming resolution selected at creation. auto means no minimum; smaller sources are not upscaled.
Available options:
auto240p360p540p720p1080p1440p2160p
playback_ready
boolean
required
Whether HLS playback is available, including while the Asset is preparing.
preview_enabled
boolean
required
Allow public preview access without an API token. Does not control CDN or static download access. Disabling it does not revoke signed URLs already issued.
source_metadata
object
required
audio_bitrate
integer
required
Original audio bitrate in bits per second, or zero when unavailable.
audio_codec
string
required
Original audio codec, or an empty string when there is no audio.
audio_samplerate
integer
required
Original audio sample rate in Hz, or zero when unavailable.
duration
number
required
Original duration in seconds.
height
integer
required
Original video height in pixels.
size
integer
required
Original file size in bytes.
video_bitrate
integer
required
Original video bitrate in bits per second, or zero when unknown.
video_codec
string
required
Original video codec.
video_framerate
number
required
Original video frame rate in frames per second.
width
integer
required
Original video width in pixels.
status
string
required
Status specifies the Asset preparation state. ready means the video is prepared for playback, with its poster and timeline previews available. Static renditions and captions have independent statuses.
Available options:
preparingreadyfailedexpired
storage_id
string
required
ID of the output Storage.
title
string
required
Asset title.
updated_at
string
date-time
required
When the Asset was last updated.
workflow_id
object
required
Selected Workflow ID, or null.
workflow_revision
object
required
Pinned Workflow revision, or null.
cdn_url
string
uri
Unsigned CDN URL of the HLS master playlist. Available when playback_ready is true and Storage has a CDN URL.
created_by_token_id
string
CreatedByTokenId specifies the Project token used to create the resource. It remains set after the token is revoked.
Omitted for dashboard requests, MCP OAuth connections, Workflow actions, and unknown creators.
Examples:
tok_2G6MJiNz71bHQGNzGwKx5cJwPFS
created_by_user_id
string
CreatedByUserId specifies the team member who created the resource.
Omitted for Workflow actions, unknown creators, and deleted accounts.
Examples:
u_2G6MJiNz71bHQGNzGwKx5cJwPFS
created_via
string
CreatedVia specifies how the resource was created: api for API requests, dashboard for the Chunkify dashboard, mcp for MCP clients, and workflow for Workflow actions.
Omitted when the creator is unknown.
When managed outputs expire, 24 hours after readiness. Omitted for customer-connected Storage.
playback_path
string
Path of the HLS master playlist in Storage. Available when playback_ready is true.
playback_ready_at
string
date-time
When HLS playback first became available.
poster
object
Poster image, available once generated.
height
integer
required
Image height in pixels.
Required range: x >= 0
path
string
required
Image path in Storage.
width
integer
required
Image width in pixels.
Required range: x >= 0
cdn_url
string
uri
Unsigned image CDN URL. Available once the poster exists and Storage has a CDN URL.
preview_url
string
uri
Public poster preview URL. Available when the Asset is ready and preview_enabled is true.
size
integer
Image size in bytes.
Required range: x >= 0
time_seconds
number
Position of the selected frame in seconds.
Required range: x >= 0
url
string
uri
Signed image URL, valid for up to ten minutes. Available once the poster exists, regardless of preview_enabled.
preview_url
string
uri
Public HLS preview URL. Available when playback_ready and preview_enabled are true. No API token is required.
ready_at
string
date-time
When all required Asset outputs finished processing.
size
integer
Size specifies the total bytes of available streaming, playback preview, poster, and timeline files. Excludes static renditions. Omitted until the Asset is ready.
Required range: x >= 0
source_id
string
Original Source ID. Omitted after Source deletion.
timeline_previews
object
Timeline thumbnails. The WebVTT file maps video timestamps to image URLs and crop coordinates.
format
"sprite"
string
required
Thumbnail image layout.
vtt_path
string
required
WebVTT file path in Storage.
cdn_url
string
uri
Unsigned WebVTT CDN URL. Available when the Asset is ready and Storage has a CDN URL.
image_count
integer
Number of thumbnails.
Required range: x >= 0
interval_seconds
number
Target thumbnail sampling interval in seconds. The WebVTT file provides actual cue timestamps.
Required range: x >= 0
preview_url
string
uri
Public WebVTT preview URL with signed image references. Available when the Asset is ready and preview_enabled is true.
size
integer
Combined WebVTT and sprite image size in bytes.
Required range: x >= 0
sprite_count
integer
Number of sprite images containing the thumbnails.
Required range: x >= 0
thumbnail_height
integer
Thumbnail height in pixels.
Required range: x >= 0
thumbnail_width
integer
Thumbnail width in pixels.
Required range: x >= 0
status
"success"
string
required
Create an Asset
application/json
error
object
required
code
400
integer
required
Code is the HTTP status code
Examples:
400
message
string
required
Message is a human-readable error description
Examples:
Invalid request parameters
type
"ValidationError"
string
required
Type indicates the error category
Available options:
ValidationError
status
"error"
string
required
Status indicates the response status "error"
Validation error
application/json
error
object
required
Error response details
code
401
integer
required
Code is the HTTP status code
Examples:
401
message
string
required
Message is a human-readable error description
Examples:
Authentication error: invalid token or subscription inactive
type
"AuthenticationError"
string
required
Type indicates the error category
Available options:
AuthenticationError
status
"error"
string
required
Status indicates the response status "error"
Authentication error
application/json
error
object
required
Error response details
code
403
integer
required
Code is the HTTP status code
Examples:
403
message
string
required
Message is a human-readable error description
Examples:
Unauthorized to perform this action
type
"ForbiddenError"
string
required
Type indicates the error category
Available options:
ForbiddenError
status
"error"
string
required
Status indicates the response status "error"
Forbidden error
application/json
error
object
required
Error response details
code
404
integer
required
Code is the HTTP status code
Examples:
404
message
string
required
Message is a human-readable error description
Examples:
Ressource not found
type
"NotFoundError"
string
required
Type indicates the error category
Available options:
NotFoundError
status
"error"
string
required
Status indicates the response status "error"
NotFound error
application/json
error
object
required
Error response details
code
409
integer
required
Code is the HTTP status code
Examples:
409
message
string
required
Message is a human-readable error description
Examples:
source_unavailable: the original video is no longer accessible
type
"ConflictError"
string
required
Type indicates the error category
Available options:
ConflictError
status
"error"
string
required
Status indicates the response status "error"
Conflict error
application/json
error
object
required
Error response details
code
429
integer
required
Code is the HTTP status code
Examples:
429
message
string
required
Message is a human-readable error description
Examples:
Rate limit exceeded
type
"TooManyRequestsError"
string
required
Type indicates the error category
Available options:
TooManyRequestsError
status
"error"
string
required
Status indicates the response status "error"
TooManyRequests error
application/json
error
object
required
Error response details
code
503
integer
required
Code is the HTTP status code
Examples:
503
message
string
required
Message is a human-readable error description
Examples:
The service is temporarily unavailable; retry the request