- Documentation
- API Reference
- Livepeer Dev Kit
- Catalyst
- What's New
- Community
Asset
Livestream
Multistream target
Session
Access control
Webhook
Task
Playback
Transcode
Viewership
APIs
Transcode a video
POST /transcode transcodes a video file and uploads the results to the
specified storage service.
Transcoding is asynchronous so you will need to check the status of the
task in order to determine when transcoding is complete. The id field
in the response is the unique ID for the transcoding Task. The task
status can be queried using the GET tasks
endpoint:
When status.phase is completed, transcoding will be complete and
the results will be stored in the storage service and the specified
output location.
The results will be available under params.outputs.hls.path and
params.outputs.mp4.path in the specified storage service.
Input
This endpoint currently supports the following inputs:
- HTTP
- S3 API Compatible Service
HTTP
A public HTTP URL can be used to read a video file.
{
"url": "https://www.example.com/video.mp4"
}
| Name | Type | Description |
|---|---|---|
| url | string | A public HTTP URL for the video file. |
Note: For IPFS HTTP gateway URLs, the API currently only supports “path
style” URLs and does not support “subdomain style” URLs. The API will
support both styles of URLs in a future update.
S3 API Compatible Service
S3 credentials can be used to authenticate with a S3 API compatible
service to read a video file.
{
"type": "s3",
"endpoint": "https://gateway.storjshare.io",
"credentials": {
"accessKeyId": "$ACCESS_KEY_ID",
"secretAccessKey": "$SECRET_ACCESS_KEY"
},
"bucket": "inbucket",
"path": "/video/source.mp4"
}
Storage
This endpoint currently supports the following storage services:
- S3 API Compatible Service
- Web3 Storage
S3 API Compatible Service
{
"type": "s3",
"endpoint": "https://gateway.storjshare.io",
"credentials": {
"accessKeyId": "$ACCESS_KEY_ID",
"secretAccessKey": "$SECRET_ACCESS_KEY"
},
"bucket": "mybucket"
}
Web3 Storage
{
"type": "web3.storage",
"credentials": {
"proof": "$UCAN_DELEGATION_PROOF",
}
}
Outputs
This endpoint currently supports the following output types:
- HLS
- MP4
HLS
{
"hls": {
"path": "/samplevideo/hls"
}
}
MP4
{
"mp4": {
"path": "/samplevideo/mp4"
}
}
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
URL input video
URL of the video to transcode
Storage for the output files
Type of service used for output files
Service endpoint URL (AWS S3 endpoint list: https://docs.aws.amazon.com/general/latest/gr/s3.html, GCP S3 endpoint: https://storage.googleapis.com, Storj: https://gateway.storjshare.io)
Bucket with output files
Credentials for the output video storage
Access Key ID
Secret Access Key
Output formats
HLS output format
Path for the HLS output
MP4 output format
Path for the MP4 output
FMP4 output format
Path for the FMP4 output
How many seconds the duration of each output segment should be
Developer-managed ID of the user who created the resource.
Decides if the output video should include C2PA signature
curl --request POST \
--url https://livepeer.studio/api/transcode \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--data '{
"input": {
"url": "https://s3.amazonaws.com/bucket/file.mp4"
},
"storage": {
"type": "s3",
"endpoint": "https://gateway.storjshare.io",
"bucket": "outputbucket",
"credentials": {
"accessKeyId": "AKIAIOSFODNN7EXAMPLE",
"secretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
}
},
"outputs": {
"hls": {
"path": "/samplevideo/hls"
},
"mp4": {
"path": "/samplevideo/mp4"
},
"fmp4": {
"path": "/samplevideo/fmp4"
}
},
"profiles": [
{
"width": 129,
"name": "720p",
"height": 129,
"bitrate": 401,
"quality": 22,
"fps": 1,
"fpsDen": 2,
"gop": "<string>",
"profile": "H264Baseline",
"encoder": "h264"
}
],
"targetSegmentSizeSecs": 123,
"creatorId": {
"type": "unverified",
"value": "<string>"
},
"c2pa": true
}'
{
"id": "09F8B46C-61A0-4254-9875-F71F4C605BC7",
"type": "upload",
"createdAt": 1587667174725,
"scheduledAt": 1587667174725,
"inputAssetId": "09F8B46C-61A0-4254-9875-F71F4C605BC7",
"outputAssetId": "09F8B46C-61A0-4254-9875-F71F4C605BC7",
"requesterId": "<string>",
"params": {
"upload": {
"url": "https://cdn.livepeer.com/ABC123/filename.mp4",
"encryption": {},
"c2pa": true,
"profiles": [
{
"width": 129,
"name": "720p",
"height": 129,
"bitrate": 401,
"quality": 22,
"fps": 1,
"fpsDen": 2,
"gop": "<string>",
"profile": "H264Baseline",
"encoder": "H.264"
}
],
"targetSegmentSizeSecs": 123
},
"export": {
"custom": {
"url": "https://s3.amazonaws.com/my-bucket/path/filename.mp4?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=LLMMB",
"method": "<string>",
"headers": {}
}
},
"exportData": {
"content": {},
"ipfs": {
"pinata": {},
"nftMetadataTemplate": "file",
"nftMetadata": {}
},
"type": "<string>",
"id": "<string>"
},
"transcode-file": {
"input": {
"url": "https://cdn.livepeer.com/ABC123/filename.mp4"
},
"storage": {
"url": "s3+https://accessKeyId:secretAccessKey@s3Endpoint/bucket"
},
"outputs": {
"hls": {
"path": "/samplevideo/hls"
},
"mp4": {
"path": "/samplevideo/mp4"
}
},
"profiles": [
{
"width": 129,
"name": "720p",
"height": 129,
"bitrate": 401,
"quality": 22,
"fps": 1,
"fpsDen": 2,
"gop": "<string>",
"profile": "H264Baseline",
"encoder": "H.264"
}
],
"targetSegmentSizeSecs": 123,
"creatorId": {
"type": "unverified",
"value": "<string>"
},
"c2pa": true
},
"clip": {
"url": "<string>",
"clipStrategy": {
"startTime": 123,
"endTime": 123,
"playbackId": "<string>"
},
"catalystPipelineStrategy": "catalyst",
"sessionId": "<string>",
"inputId": "<string>"
}
},
"status": {
"phase": "pending",
"updatedAt": 1587667174725,
"progress": 123,
"errorMessage": "<string>",
"retries": 123
},
"output": {
"upload": {
"assetSpec": {
"id": "09F8B46C-61A0-4254-9875-F71F4C605BC7",
"type": "video",
"playbackId": "eaw4nk06ts2d0mzb",
"playbackUrl": "https://livepeercdn.com/asset/ea03f37e-f861-4cdd-b495-0e60b6d753ad/index.m3u8",
"downloadUrl": "https://livepeercdn.com/asset/eaw4nk06ts2d0mzb/video",
"playbackPolicy": {
"type": "public",
"webhookId": "<string>",
"webhookContext": {},
"refreshInterval": 123
},
"source": {
"type": "url",
"url": "<string>",
"gatewayUrl": "<string>",
"encryption": {}
},
"creatorId": {
"type": "unverified",
"value": "<string>"
},
"storage": {
"ipfs": {
"spec": {
"nftMetadataTemplate": "file",
"nftMetadata": {}
},
"nftMetadata": {
"cid": "<string>",
"url": "<string>",
"gatewayUrl": "<string>"
},
"updatedAt": 1587667174725,
"cid": "<string>",
"url": "<string>",
"gatewayUrl": "<string>"
},
"status": {
"phase": "waiting",
"progress": 123,
"errorMessage": "<string>",
"tasks": {
"pending": "<string>",
"last": "<string>",
"failed": "<string>"
}
}
},
"status": {
"phase": "uploading",
"updatedAt": 1587667174725,
"progress": 123,
"errorMessage": "<string>"
},
"name": "filename.mp4",
"projectId": "aac12556-4d65-4d34-9fb6-d1f0985eb0a9",
"createdAt": 1587667174725,
"createdByTokenName": "<string>",
"size": 84934509,
"hash": [
{
"hash": "9b560b28b85378a5004117539196ab24e21bbd75b0e9eb1a8bc7c5fd80dc5b57",
"algorithm": "sha256"
}
],
"videoSpec": {
"format": "mp4",
"duration": 23.8328,
"bitrate": 1000000,
"tracks": [
{
"type": "video",
"codec": "aac",
"startTime": 23.8238,
"duration": 23.8238,
"bitrate": 1000000,
"width": 1920,
"height": 1080,
"pixelFormat": "yuv420p",
"fps": 30,
"channels": 2,
"sampleRate": 44100,
"bitDepth": 16
}
]
}
}
},
"export": {
"ipfs": {
"videoFileCid": "<string>",
"videoFileUrl": "<string>",
"videoFileGatewayUrl": "<string>",
"nftMetadataCid": "<string>",
"nftMetadataUrl": "<string>",
"nftMetadataGatewayUrl": "<string>"
}
},
"exportData": {
"ipfs": {
"cid": "<string>"
}
}
}
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
URL input video
URL of the video to transcode
Storage for the output files
Type of service used for output files
s3 Service endpoint URL (AWS S3 endpoint list: https://docs.aws.amazon.com/general/latest/gr/s3.html, GCP S3 endpoint: https://storage.googleapis.com, Storj: https://gateway.storjshare.io)
Bucket with output files
Credentials for the output video storage
Access Key ID
Secret Access Key
Output formats
HLS output format
Path for the HLS output
MP4 output format
Path for the MP4 output
FMP4 output format
Path for the FMP4 output
Restricts the size of the output video using the constant quality feature. Increasing this value will result in a lower quality video. Note that this parameter might not work if the transcoder lacks support for it.
H264Baseline, H264Main, H264High, H264ConstrainedHigh H.264, HEVC, VP8, VP9 How many seconds the duration of each output segment should be
unverified Developer-managed ID of the user who created the resource.
Decides if the output video should include C2PA signature
Response
Task ID
Type of the task
upload, export, export-data, transcode-file, clip Timestamp (in milliseconds) at which task was created
Timestamp (in milliseconds) at which the task was scheduled for execution (e.g. after file upload finished).
ID of the input asset
ID of the output asset
ID of the requester hash(IP + SALT + PlaybackId)
Parameters of the task
Parameters for the upload task
URL of the asset to "upload"
Decides if the output video should include C2PA signature
Restricts the size of the output video using the constant quality feature. Increasing this value will result in a lower quality video. Note that this parameter might not work if the transcoder lacks support for it.
H264Baseline, H264Main, H264High, H264ConstrainedHigh H.264, HEVC, VP8, VP9 How many seconds the duration of each output segment should be
Parameters for the export task
custom URL parameters for the export task
URL where to export the asset
Method to use on the export request
Headers to add to the export request
Parameters for the export-data task
File content to store into IPFS
Custom credentials for the Piñata service. Must have either a JWT or an API key and an API secret.
Name of the NFT metadata template to export. 'player' will embed the Livepeer Player on the NFT while 'file' will reference only the immutable MP4 files.
file, player Additional data to add to the NFT metadata exported to IPFS. Will be deep merged with the default metadata exported.
Optional type of content
Optional ID of the content
Parameters for the transcode-file task
Input video file to transcode
URL of a video to transcode, accepts object-store format "s3+https"
Storage for the output files
URL of the output storage, accepts object-store format "s3+https"
Output formats
HLS output format
Path for the HLS output
MP4 output format
Path for the MP4 output
Restricts the size of the output video using the constant quality feature. Increasing this value will result in a lower quality video. Note that this parameter might not work if the transcoder lacks support for it.
H264Baseline, H264Main, H264High, H264ConstrainedHigh H.264, HEVC, VP8, VP9 How many seconds the duration of each output segment should be
unverified Developer-managed ID of the user who created the resource.
Decides if the output video should include C2PA signature
URL of the asset to "clip"
Strategy to use for clipping the asset. If not specified, the default strategy that Catalyst is configured for will be used. This field only available for admin users, and is only used for E2E testing.
The start timestamp of the clip in Unix milliseconds. See the ClipTrigger in the UI Kit for an example of how this is calculated (for HLS, it uses Program Date-Time tags, and for WebRTC, it uses the latency from server to client at stream startup).
The end timestamp of the clip in Unix milliseconds. See the ClipTrigger in the UI Kit for an example of how this is calculated (for HLS, it uses Program Date-Time tags, and for WebRTC, it uses the latency from server to client at stream startup).
The playback ID of the stream or stream recording to clip. Asset playback IDs are not supported yet.
Force to use a specific strategy in the Catalyst pipeline. If not specified, the default strategy that Catalyst is configured for will be used. This field only available for admin users, and is only used for E2E testing.
catalyst, catalyst_ffmpeg, background_external, background_mist, fallback_external, external ID of the session
ID of the input asset or stream
Status of the task
Phase of the task
pending, waiting, running, failed, completed, cancelled Timestamp (in milliseconds) at which task was updated
Current progress of the task in a 0-1 ratio
Error message if the task failed
Number of retries done on the task
Output of the task
Output of the upload task
Type of the asset.
video, audio The playback ID to use with the Playback Info endpoint to retrieve playback URLs.
URL for HLS playback. It is recommended to not use this URL, and instead use playback IDs with the Playback Info endpoint to retrieve the playback URLs - this URL format is subject to change (e.g. https://livepeercdn.com/asset/ea03f37e-f861-4cdd-b495-0e60b6d753ad/index.m3u8).
The URL to directly download the asset, e.g. https://livepeercdn.com/asset/eawrrk06ts2d0mzb/video. It is not recommended to use this for playback.
Whether the playback policy for a asset or stream is public or signed
public, jwt, webhook ID of the webhook to use for playback policy
User-defined webhook context
Interval (in seconds) at which the playback policy should be refreshed (default 600 seconds)
url URL from which the asset was uploaded.
Gateway URL from asset if parsed from provided URL on upload.
unverified Developer-managed ID of the user who created the resource.
Name of the NFT metadata template to export. 'player' will embed the Livepeer Player on the NFT while 'file' will reference only the immutable MP4 files.
file, player Additional data to add to the NFT metadata exported to IPFS. Will be deep merged with the default metadata exported.
CID of the file on IPFS
URL with IPFS scheme for the file
URL to access file via HTTP through an IPFS gateway
Timestamp (in milliseconds) at which IPFS export task was updated
CID of the file on IPFS
URL with IPFS scheme for the file
URL to access file via HTTP through an IPFS gateway
Phase of the asset storage
waiting, processing, ready, failed, reverted Current progress of the task updating the storage.
Error message if the last storage changed failed.
ID of any currently running task that is exporting this asset to IPFS.
ID of the last task to run successfully, that created the currently saved data.
ID of the last task to fail execution.
Status of the asset
Phase of the asset
uploading, waiting, processing, ready, failed Timestamp (in milliseconds) at which the asset was last updated
Current progress of the task creating this asset.
Error message if the asset creation failed.
The name of the asset. This is not necessarily the filename - it can be a custom name or title.
The ID of the project
Timestamp (in milliseconds) at which asset was created
Name of the token used to create this object
Size of the asset in bytes
Hash of the asset
Hash of the asset
Hash algorithm used to compute the hash
Video metadata
Format of the asset
Duration of the asset in seconds (float)
Bitrate of the video in bits per second
List of tracks associated with the asset when the format contemplates them (e.g. mp4)
type of track
video, audio Codec of the track
Start time of the track in seconds
Duration of the track in seconds
Bitrate of the track in bits per second
Width of the track - only for video tracks
Height of the track - only for video tracks
Pixel format of the track - only for video tracks
Frame rate of the track - only for video tracks
Amount of audio channels in the track
Sample rate of the track in samples per second - only for audio tracks
Bit depth of the track - only for audio tracks
Output of the export task
IPFS CID of the exported video file
URL for the file with the IPFS protocol
URL to access file via HTTP through an IPFS gateway
IPFS CID of the default metadata exported for the video
URL for the metadata file with the IPFS protocol
URL to access metadata file via HTTP through an IPFS gateway
Output of the export data task
IPFS CID of the exported data
Was this page helpful?
curl --request POST \
--url https://livepeer.studio/api/transcode \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--data '{
"input": {
"url": "https://s3.amazonaws.com/bucket/file.mp4"
},
"storage": {
"type": "s3",
"endpoint": "https://gateway.storjshare.io",
"bucket": "outputbucket",
"credentials": {
"accessKeyId": "AKIAIOSFODNN7EXAMPLE",
"secretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
}
},
"outputs": {
"hls": {
"path": "/samplevideo/hls"
},
"mp4": {
"path": "/samplevideo/mp4"
},
"fmp4": {
"path": "/samplevideo/fmp4"
}
},
"profiles": [
{
"width": 129,
"name": "720p",
"height": 129,
"bitrate": 401,
"quality": 22,
"fps": 1,
"fpsDen": 2,
"gop": "<string>",
"profile": "H264Baseline",
"encoder": "h264"
}
],
"targetSegmentSizeSecs": 123,
"creatorId": {
"type": "unverified",
"value": "<string>"
},
"c2pa": true
}'
{
"id": "09F8B46C-61A0-4254-9875-F71F4C605BC7",
"type": "upload",
"createdAt": 1587667174725,
"scheduledAt": 1587667174725,
"inputAssetId": "09F8B46C-61A0-4254-9875-F71F4C605BC7",
"outputAssetId": "09F8B46C-61A0-4254-9875-F71F4C605BC7",
"requesterId": "<string>",
"params": {
"upload": {
"url": "https://cdn.livepeer.com/ABC123/filename.mp4",
"encryption": {},
"c2pa": true,
"profiles": [
{
"width": 129,
"name": "720p",
"height": 129,
"bitrate": 401,
"quality": 22,
"fps": 1,
"fpsDen": 2,
"gop": "<string>",
"profile": "H264Baseline",
"encoder": "H.264"
}
],
"targetSegmentSizeSecs": 123
},
"export": {
"custom": {
"url": "https://s3.amazonaws.com/my-bucket/path/filename.mp4?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=LLMMB",
"method": "<string>",
"headers": {}
}
},
"exportData": {
"content": {},
"ipfs": {
"pinata": {},
"nftMetadataTemplate": "file",
"nftMetadata": {}
},
"type": "<string>",
"id": "<string>"
},
"transcode-file": {
"input": {
"url": "https://cdn.livepeer.com/ABC123/filename.mp4"
},
"storage": {
"url": "s3+https://accessKeyId:secretAccessKey@s3Endpoint/bucket"
},
"outputs": {
"hls": {
"path": "/samplevideo/hls"
},
"mp4": {
"path": "/samplevideo/mp4"
}
},
"profiles": [
{
"width": 129,
"name": "720p",
"height": 129,
"bitrate": 401,
"quality": 22,
"fps": 1,
"fpsDen": 2,
"gop": "<string>",
"profile": "H264Baseline",
"encoder": "H.264"
}
],
"targetSegmentSizeSecs": 123,
"creatorId": {
"type": "unverified",
"value": "<string>"
},
"c2pa": true
},
"clip": {
"url": "<string>",
"clipStrategy": {
"startTime": 123,
"endTime": 123,
"playbackId": "<string>"
},
"catalystPipelineStrategy": "catalyst",
"sessionId": "<string>",
"inputId": "<string>"
}
},
"status": {
"phase": "pending",
"updatedAt": 1587667174725,
"progress": 123,
"errorMessage": "<string>",
"retries": 123
},
"output": {
"upload": {
"assetSpec": {
"id": "09F8B46C-61A0-4254-9875-F71F4C605BC7",
"type": "video",
"playbackId": "eaw4nk06ts2d0mzb",
"playbackUrl": "https://livepeercdn.com/asset/ea03f37e-f861-4cdd-b495-0e60b6d753ad/index.m3u8",
"downloadUrl": "https://livepeercdn.com/asset/eaw4nk06ts2d0mzb/video",
"playbackPolicy": {
"type": "public",
"webhookId": "<string>",
"webhookContext": {},
"refreshInterval": 123
},
"source": {
"type": "url",
"url": "<string>",
"gatewayUrl": "<string>",
"encryption": {}
},
"creatorId": {
"type": "unverified",
"value": "<string>"
},
"storage": {
"ipfs": {
"spec": {
"nftMetadataTemplate": "file",
"nftMetadata": {}
},
"nftMetadata": {
"cid": "<string>",
"url": "<string>",
"gatewayUrl": "<string>"
},
"updatedAt": 1587667174725,
"cid": "<string>",
"url": "<string>",
"gatewayUrl": "<string>"
},
"status": {
"phase": "waiting",
"progress": 123,
"errorMessage": "<string>",
"tasks": {
"pending": "<string>",
"last": "<string>",
"failed": "<string>"
}
}
},
"status": {
"phase": "uploading",
"updatedAt": 1587667174725,
"progress": 123,
"errorMessage": "<string>"
},
"name": "filename.mp4",
"projectId": "aac12556-4d65-4d34-9fb6-d1f0985eb0a9",
"createdAt": 1587667174725,
"createdByTokenName": "<string>",
"size": 84934509,
"hash": [
{
"hash": "9b560b28b85378a5004117539196ab24e21bbd75b0e9eb1a8bc7c5fd80dc5b57",
"algorithm": "sha256"
}
],
"videoSpec": {
"format": "mp4",
"duration": 23.8328,
"bitrate": 1000000,
"tracks": [
{
"type": "video",
"codec": "aac",
"startTime": 23.8238,
"duration": 23.8238,
"bitrate": 1000000,
"width": 1920,
"height": 1080,
"pixelFormat": "yuv420p",
"fps": 30,
"channels": 2,
"sampleRate": 44100,
"bitDepth": 16
}
]
}
}
},
"export": {
"ipfs": {
"videoFileCid": "<string>",
"videoFileUrl": "<string>",
"videoFileGatewayUrl": "<string>",
"nftMetadataCid": "<string>",
"nftMetadataUrl": "<string>",
"nftMetadataGatewayUrl": "<string>"
}
},
"exportData": {
"ipfs": {
"cid": "<string>"
}
}
}
}