- Documentation
- API Reference
- Livepeer Dev Kit
- Catalyst
- What's New
- Community
Asset
Livestream
Multistream target
Session
Access control
Webhook
Task
Playback
Transcode
Viewership
APIs
Upload an asset
To upload an asset, your first need to request for a direct upload URL
and only then actually upload the contents of the asset.
Once you created a upload link, you have 2 options, resumable or direct
upload. For a more reliable experience, you should use resumable uploads
which will work better for users with unreliable or slow network
connections. If you want a simpler implementation though, you should
just use a direct upload.
Direct Upload
For a direct upload, make a PUT request to the URL received in the url field of the response above, with the raw video file as the request body. response above:
Resumable Upload
Livepeer supports resumable uploads via Tus. This section provides a
simple example of how to use tus-js-client to upload a video file.
From the previous section, we generated a URL to upload a video file to
Livepeer on POST /api/asset/request-upload. You should use the
tusEndpoint field of the response to upload the video file and track the
progress:
# This assumes there is an `input` element of `type="file"` with id
`fileInput` in the HTML
const input = document.getElementById('fileInput');
const file = input.files[0];
const upload = new tus.Upload(file, {
endpoint: tusEndpoint, // URL from `tusEndpoint` field in the
`/request-upload` response
metadata: {
filename,
filetype: 'video/mp4',
},
uploadSize: file.size,
onError(err) {
console.error('Error uploading file:', err);
},
onProgress(bytesUploaded, bytesTotal) {
const percentage = ((bytesUploaded / bytesTotal) * 100).toFixed(2);
console.log('Uploaded ' + percentage + '%');
},
onSuccess() {
console.log('Upload finished:', upload.url);
},
});
const previousUploads = await upload.findPreviousUploads();
if (previousUploads.length > 0) {
upload.resumeFromPreviousUpload(previousUploads[0]);
}
upload.start();
Note: If you are using tus from node.js, you need to add a custom URL storage to enable resuming from previous uploads. On the browser, this is enabled by default using local storage. In node.js, add urlStorage: new tus.FileUrlStorage(“path/to/tmp/file”), to the UploadFile object definition above.
Bearer authentication header of the form Bearer <token>
, where <token>
is your auth token.
The name of the asset. This is not necessarily the filename - it can be a custom name or title.
Type of the asset.
The playback ID to use with the Playback Info endpoint to retrieve playback URLs.
Whether to generate MP4s for the asset.
Whether the playback policy for a asset or stream is public or signed
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 from which the asset was uploaded.
Gateway URL from asset if parsed from provided URL on upload.
Encryption key used to encrypt the asset. Only writable in the upload asset endpoints and cannot be retrieved back.
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.
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
CID of the file on IPFS
The name of the asset. This is not necessarily the filename - it can be a custom name or title.
The ID of the project
Hash of the asset
Whether to generate MP4s for the asset.
Whether the playback policy for a asset or stream is public or signed
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)
Developer-managed ID of the user who created the resource.
Set to true to make default export to IPFS. To customize the pinned files, specify an object with a spec field. False or null means to unpin from IPFS, but it's unsupported right now.
Encryption key used to encrypt the asset. Only writable in the upload asset endpoints and cannot be retrieved back.
Decides if the output video should include C2PA signature
How many seconds the duration of each output segment should be
curl --request POST \
--url https://livepeer.studio/api/asset/request-upload \
--header 'Authorization: Bearer <api-key>' \
--header 'Content-Type: application/json' \
--data '{
"name": "my first asset",
}'
{
"url": "https://origin.livepeer.com/api/asset/upload/direct?token=eyJhbGciOiJIUzI1NiJ9.eyJtc2ciOiJoZWxsbyBoYWNrZXIsIHRoZXJlJ3Mgbm90aGluZyBmb3IgeW91IGhlcmUg8J-YhiJ9.1YDjmXsqLcgNyMSzT4kXl_kIni46_EuGX_xfqmC7e0Q",
"tusEndpoint": "https://origin.livepeer.com/api/asset/upload/tus?token=eyJhbGciOiJIUzI1NiJ9.eyJtc2ciOiJoZWxsbyBoYWNrZXIsIHRoZXJlJ3Mgbm90aGluZyBmb3IgeW91IGhlcmUg8J-YhiJ9.1YDjmXsqLcgNyMSzT4kXl_kIni46_EuGX_xfqmC7e0Q",
"asset": {
"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
}
]
}
},
"task": {
"id": "34d7618e-fd42-4798-acf5-19504616a11e"
}
}
Authorizations
Bearer authentication header of the form Bearer <token>
, where <token>
is your auth token.
Body
The name of the asset. This is not necessarily the filename - it can be a custom name or title.
Type of the asset.
video
, audio
The playback ID to use with the Playback Info endpoint to retrieve playback URLs.
Whether to generate MP4s for the asset.
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.
Encryption key used to encrypt the asset. Only writable in the upload asset endpoints and cannot be retrieved back.
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
CID of the file on IPFS
The name of the asset. This is not necessarily the filename - it can be a custom name or title.
The ID of the project
Hash of the asset
Hash of the asset
Hash algorithm used to compute the hash
Whether to generate MP4s for the asset.
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)
unverified
Developer-managed ID of the user who created the resource.
Set to true to make default export to IPFS. To customize the pinned files, specify an object with a spec field. False or null means to unpin from IPFS, but it's unsupported right now.
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.
Encryption key used to encrypt the asset. Only writable in the upload asset endpoints and cannot be retrieved back.
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
Response
The direct upload endpoint for which supports PUT requests. It is recommended to use the Tus endpoint for a better upload experience.
The Tus-compatible endpoint for resumable uploads. This is the recommended way to upload assets. See the Tus-js client for more information.
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
Was this page helpful?
curl --request POST \
--url https://livepeer.studio/api/asset/request-upload \
--header 'Authorization: Bearer <api-key>' \
--header 'Content-Type: application/json' \
--data '{
"name": "my first asset",
}'
{
"url": "https://origin.livepeer.com/api/asset/upload/direct?token=eyJhbGciOiJIUzI1NiJ9.eyJtc2ciOiJoZWxsbyBoYWNrZXIsIHRoZXJlJ3Mgbm90aGluZyBmb3IgeW91IGhlcmUg8J-YhiJ9.1YDjmXsqLcgNyMSzT4kXl_kIni46_EuGX_xfqmC7e0Q",
"tusEndpoint": "https://origin.livepeer.com/api/asset/upload/tus?token=eyJhbGciOiJIUzI1NiJ9.eyJtc2ciOiJoZWxsbyBoYWNrZXIsIHRoZXJlJ3Mgbm90aGluZyBmb3IgeW91IGhlcmUg8J-YhiJ9.1YDjmXsqLcgNyMSzT4kXl_kIni46_EuGX_xfqmC7e0Q",
"asset": {
"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
}
]
}
},
"task": {
"id": "34d7618e-fd42-4798-acf5-19504616a11e"
}
}