> ## Documentation Index
> Fetch the complete documentation index at: https://docs.livepeer.org/llms.txt
> Use this file to discover all available pages before exploring further.
# Upload an asset
> Upload a video or audio asset
## OpenAPI
````yaml POST /asset/request-upload
openapi: 3.1.0
info:
title: Livepeer API Reference
description: |
Welcome to the Livepeer API reference docs. Here you will find all the
endpoints exposed on the standard Livepeer API, learn how to use them and
what they return.
version: 1.0.0
servers:
- url: https://livepeer.studio/api
security:
- apiKey: []
tags:
- name: stream
description: Operations related to livestream api
- name: asset
description: Operations related to asset/vod api
- name: webhook
description: Operations related to webhook api
- name: multistream
description: Operations related to multistream api
- name: session
description: Operations related to session api
- name: room
description: Operations related to rooms api
- name: transcode
description: Operations related to transcode api
- name: metrics
description: Operations related to metrics api
- name: playback
description: Operations related to playback api
- name: accessControl
description: Operations related to access control/signing keys api
- name: task
description: Operations related to tasks api
- name: generate
description: Operations related to AI generate api
paths:
/asset/request-upload:
post:
tags:
- asset
summary: Upload an asset
description: |
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.
operationId: requestUpload
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/new-asset-payload'
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
additionalProperties: false
required:
- url
- tusEndpoint
- asset
- task
properties:
url:
type: string
description: >-
The direct upload endpoint for which supports PUT
requests. **It is recommended to use the Tus endpoint for
a better upload experience.**
example: >-
https://origin.livepeer.com/api/asset/upload/direct?token=eyJhbGciOiJIUzI1NiJ9.eyJtc2ciOiJoZWxsbyBoYWNrZXIsIHRoZXJlJ3Mgbm90aGluZyBmb3IgeW91IGhlcmUg8J-YhiJ9.1YDjmXsqLcgNyMSzT4kXl_kIni46_EuGX_xfqmC7e0Q
tusEndpoint:
type: string
description: >-
The [Tus-compatible](https://tus.io/) endpoint for
resumable uploads. **This is the recommended way to upload
assets.** See the
[Tus-js](https://github.com/tus/tus-js-client) client for
more information.
example: >-
https://origin.livepeer.com/api/asset/upload/tus?token=eyJhbGciOiJIUzI1NiJ9.eyJtc2ciOiJoZWxsbyBoYWNrZXIsIHRoZXJlJ3Mgbm90aGluZyBmb3IgeW91IGhlcmUg8J-YhiJ9.1YDjmXsqLcgNyMSzT4kXl_kIni46_EuGX_xfqmC7e0Q
asset:
$ref: '#/components/schemas/asset'
task:
type: object
required:
- id
additionalProperties: false
properties:
id:
type: string
example: 34d7618e-fd42-4798-acf5-19504616a11e
x-speakeasy-name-override: data
default:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/error'
x-codeSamples:
- lang: typescript
label: requestUpload
source: >-
import { Livepeer } from "livepeer";
import { TranscodeProfileEncoder, TranscodeProfileProfile, Type }
from "livepeer/models/components";
const livepeer = new Livepeer({
apiKey: "",
});
async function run() {
const result = await livepeer.asset.create({
name: "filename.mp4",
staticMp4: true,
playbackPolicy: {
type: Type.Webhook,
webhookId: "1bde4o2i6xycudoy",
webhookContext: {
"streamerId": "my-custom-id",
},
refreshInterval: 600,
},
profiles: [
{
width: 1280,
name: "720p",
height: 720,
bitrate: 3000000,
quality: 23,
fps: 30,
fpsDen: 1,
gop: "2",
profile: TranscodeProfileProfile.H264Baseline,
encoder: TranscodeProfileEncoder.H264,
},
],
});
// Handle the result
console.log(result);
}
run();
- lang: go
label: requestUpload
source: "package main\n\nimport(\n\tlivepeergo \"github.com/livepeer/livepeer-go\"\n\t\"context\"\n\t\"github.com/livepeer/livepeer-go/models/components\"\n\t\"log\"\n)\n\nfunc main() {\n s := livepeergo.New(\n livepeergo.WithSecurity(\"\"),\n )\n\n ctx := context.Background()\n res, err := s.Asset.Create(ctx, components.NewAssetPayload{\n Name: \"filename.mp4\",\n StaticMp4: livepeergo.Bool(true),\n PlaybackPolicy: &components.PlaybackPolicy{\n Type: components.TypeWebhook,\n WebhookID: livepeergo.String(\"1bde4o2i6xycudoy\"),\n WebhookContext: map[string]any{\n \"streamerId\": \"my-custom-id\",\n },\n RefreshInterval: livepeergo.Float64(600),\n },\n Profiles: []components.TranscodeProfile{\n components.TranscodeProfile{\n Width: livepeergo.Int64(1280),\n Name: livepeergo.String(\"720p\"),\n Height: livepeergo.Int64(720),\n Bitrate: 3000000,\n Quality: livepeergo.Int64(23),\n Fps: livepeergo.Int64(30),\n FpsDen: livepeergo.Int64(1),\n Gop: livepeergo.String(\"2\"),\n Profile: components.TranscodeProfileProfileH264Baseline.ToPointer(),\n Encoder: components.TranscodeProfileEncoderH264.ToPointer(),\n },\n },\n })\n if err != nil {\n log.Fatal(err)\n }\n if res.Data != nil {\n // handle response\n }\n}"
- lang: python
label: requestUpload
source: |-
from livepeer import Livepeer
from livepeer.models import components
s = Livepeer(
api_key="",
)
res = s.asset.create(request={
"name": "filename.mp4",
"static_mp4": True,
"playback_policy": {
"type": components.Type.WEBHOOK,
"webhook_id": "1bde4o2i6xycudoy",
"webhook_context": {
"streamerId": "my-custom-id",
},
"refresh_interval": 600,
},
"profiles": [
{
"width": 1280,
"name": "720p",
"height": 720,
"bitrate": 3000000,
"quality": 23,
"fps": 30,
"fps_den": 1,
"gop": "2",
"profile": components.TranscodeProfileProfile.H264_BASELINE,
"encoder": components.TranscodeProfileEncoder.H_264,
},
],
})
if res.data is not None:
# handle response
pass
components:
schemas:
new-asset-payload:
additionalProperties: false
required:
- name
properties:
name:
type: string
description: >
The name of the asset. This is not necessarily the filename - it can
be a custom name or title.
example: filename.mp4
staticMp4:
type: boolean
description: Whether to generate MP4s for the asset.
example: true
playbackPolicy:
$ref: '#/components/schemas/playback-policy'
creatorId:
$ref: '#/components/schemas/input-creator-id'
storage:
type: object
additionalProperties: false
properties:
ipfs:
description: |
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.
oneOf:
- type: object
additionalProperties: false
properties:
spec:
oneOf:
- type: 'null'
- a5ce122c-526a-4e1e-bcdd-b808d47f5838
- type: boolean
- type: 'null'
encryption:
type: object
additionalProperties: false
required:
- encryptedKey
properties:
encryptedKey:
type: string
writeOnly: true
description: >-
Encryption key used to encrypt the asset. Only writable in the
upload asset endpoints and cannot be retrieved back.
c2pa:
type: boolean
description: Decides if the output video should include C2PA signature
profiles:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/transcode-profile'
targetSegmentSizeSecs:
type: number
description: How many seconds the duration of each output segment should be
asset:
type: object
additionalProperties: false
required:
- id
- name
- source
properties:
id:
type: string
readOnly: true
example: 09F8B46C-61A0-4254-9875-F71F4C605BC7
type:
type: string
enum:
- video
- audio
description: Type of the asset.
example: video
playbackId:
type: string
example: eaw4nk06ts2d0mzb
description: >-
The playback ID to use with the Playback Info endpoint to retrieve
playback URLs.
userId:
type: string
readOnly: true
example: 66E2161C-7670-4D05-B71D-DA2D6979556F
deprecated: true
staticMp4:
type: boolean
writeOnly: true
description: Whether to generate MP4s for the asset.
playbackUrl:
readOnly: true
type: string
example: >-
https://livepeercdn.com/asset/ea03f37e-f861-4cdd-b495-0e60b6d753ad/index.m3u8
description: >-
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).
downloadUrl:
readOnly: true
type: string
example: https://livepeercdn.com/asset/eaw4nk06ts2d0mzb/video/download.mp4
description: >-
The URL to directly download the asset, e.g.
`https://livepeercdn.com/asset/eawrrk06ts2d0mzb/video`. It is not
recommended to use this for playback.
playbackPolicy:
$ref: '#/components/schemas/playback-policy'
source:
oneOf:
- additionalProperties: false
required:
- type
- url
properties:
type:
type: string
enum:
- url
url:
type: string
description: URL from which the asset was uploaded.
gatewayUrl:
type: string
description: >-
Gateway URL from asset if parsed from provided URL on
upload.
encryption: db5036d7-c6cf-4962-b87b-3d09bb609f31
- additionalProperties: false
required:
- type
- sessionId
properties:
type:
type: string
enum:
- recording
sessionId:
type: string
description: ID of the session from which this asset was created
- additionalProperties: false
required:
- type
properties:
type:
type: string
enum:
- directUpload
- clip
encryption: fbc80452-e8f0-43c9-b346-64491631dbdf
sourceId:
type: string
description: ID of the asset or stream from which this asset was created.
sessionId:
type: string
description: ID of the session from which this asset was created.
playbackId:
type: string
description: >-
Playback ID of the asset or stream from which this asset was
created.
requesterId:
type: string
description: ID of the requester from which this asset was created.
assetId:
type: string
description: ID of the asset from which this asset was created.
creatorId:
$ref: '#/components/schemas/creator-id'
profiles:
type: array
description: |
Requested profiles for the asset to be transcoded into. Configured
on the upload APIs payload or through the `stream.recordingSpec`
field for recordings. If not specified, default profiles are derived
based on the source input. If this is a recording, the source will
not be present in this list but will be available for playback.
items:
$ref: '#/components/schemas/transcode-profile'
storage:
type: object
additionalProperties: false
properties:
ipfs:
type: object
additionalProperties: false
properties:
$ref: d873c64b-1df3-4ee7-bc3a-f3a52dd7e242
spec:
type: object
additionalProperties: false
default: {}
properties:
nftMetadataTemplate:
type: string
enum:
- file
- player
default: file
description: |
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.
nftMetadata:
type: object
description: |
Additional data to add to the NFT metadata exported to
IPFS. Will be deep merged with the default metadata
exported.
nftMetadata:
$ref: '#/components/schemas/ipfs-file-info'
updatedAt:
readOnly: true
type: number
description: |
Timestamp (in milliseconds) at which IPFS export task was
updated
example: 1587667174725
status:
$ref: '#/components/schemas/storage-status'
status:
readOnly: true
type: object
additionalProperties: false
required:
- phase
- updatedAt
description: Status of the asset
properties:
phase:
type: string
description: Phase of the asset
enum:
- uploading
- waiting
- processing
- ready
- failed
- deleting
- deleted
updatedAt:
type: number
description: Timestamp (in milliseconds) at which the asset was last updated
example: 1587667174725
progress:
type: number
description: Current progress of the task creating this asset.
errorMessage:
type: string
description: Error message if the asset creation failed.
name:
type: string
description: >
The name of the asset. This is not necessarily the filename - it can
be a custom name or title.
example: filename.mp4
projectId:
type: string
description: The ID of the project
example: aac12556-4d65-4d34-9fb6-d1f0985eb0a9
createdAt:
readOnly: true
type: number
description: Timestamp (in milliseconds) at which asset was created
example: 1587667174725
createdByTokenName:
type: string
readOnly: true
description: Name of the token used to create this object
size:
readOnly: true
type: number
description: Size of the asset in bytes
example: 84934509
hash:
type:
- array
- 'null'
description: Hash of the asset
items:
type: object
additionalProperties: false
properties:
hash:
type: string
description: Hash of the asset
example: >-
9b560b28b85378a5004117539196ab24e21bbd75b0e9eb1a8bc7c5fd80dc5b57
algorithm:
type: string
description: Hash algorithm used to compute the hash
example: sha256
videoSpec:
readOnly: true
type: object
additionalProperties: false
description: Video metadata
properties:
format:
type: string
description: Format of the asset
example: mp4
duration:
type: number
description: Duration of the asset in seconds (float)
example: 23.8328
bitrate:
type: number
description: Bitrate of the video in bits per second
example: 1000000
tracks:
type: array
description: |
List of tracks associated with the asset when the format
contemplates them (e.g. mp4)
items:
type: object
additionalProperties: false
required:
- type
- codec
properties:
type:
type: string
description: type of track
enum:
- video
- audio
example: video
codec:
type: string
description: Codec of the track
example: aac
startTime:
type: number
description: Start time of the track in seconds
example: 23.8238
duration:
type: number
description: Duration of the track in seconds
example: 23.8238
bitrate:
type: number
description: Bitrate of the track in bits per second
example: 1000000
width:
type: number
description: Width of the track - only for video tracks
example: 1920
height:
type: number
description: Height of the track - only for video tracks
example: 1080
pixelFormat:
type: string
description: Pixel format of the track - only for video tracks
example: yuv420p
fps:
type: number
description: Frame rate of the track - only for video tracks
example: 30
channels:
type: number
description: Amount of audio channels in the track
example: 2
sampleRate:
type: number
description: |
Sample rate of the track in samples per second - only for
audio tracks
example: 44100
bitDepth:
type: number
description: Bit depth of the track - only for audio tracks
example: 16
error:
type: object
properties:
errors:
type: array
minItems: 1
items:
type: string
example:
- id not provided
- Account not found
playback-policy:
type:
- object
- 'null'
description: Whether the playback policy for an asset or stream is public or signed
additionalProperties: false
required:
- type
properties:
type:
type: string
enum:
- public
- jwt
- webhook
example: webhook
webhookId:
type: string
description: ID of the webhook to use for playback policy
example: 1bde4o2i6xycudoy
webhookContext:
type: object
description: User-defined webhook context
additionalProperties: true
example:
streamerId: my-custom-id
refreshInterval:
type: number
description: |
Interval (in seconds) at which the playback policy should be
refreshed (default 600 seconds)
example: 600
allowedOrigins:
type: array
description: >-
List of allowed origins for CORS playback
(://:, ://)
items:
type: string
input-creator-id:
oneOf:
- type: object
additionalProperties: false
required:
- type
- value
properties:
type:
type: string
enum:
- unverified
value:
type: string
- type: string
description: >-
Helper syntax to specify an unverified creator ID, fully managed by
the developer.
transcode-profile:
type: object
description: Transcode API profile
additionalProperties: false
required:
- bitrate
properties:
width:
type: integer
minimum: 128
example: 1280
name:
type: string
minLength: 1
maxLength: 500
example: 720p
height:
type: integer
minimum: 128
example: 720
bitrate:
type: integer
minimum: 400
example: 3000000
quality:
type: integer
description: >
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.
minimum: 0
maximum: 44
example: 23
fps:
type: integer
minimum: 0
example: 30
fpsDen:
type: integer
minimum: 1
example: 1
gop:
type: string
example: 2
profile:
type: string
enum:
- H264Baseline
- H264Main
- H264High
- H264ConstrainedHigh
example: H264Baseline
encoder:
type: string
enum:
- H.264
- HEVC
- VP8
- VP9
example: H.264
creator-id:
oneOf:
- type: object
additionalProperties: false
required:
- type
- value
properties:
type:
type: string
enum:
- unverified
example: unverified
value:
type: string
description: Developer-managed ID of the user who created the resource.
example: user123
ipfs-file-info:
type: object
required:
- cid
additionalProperties: false
properties:
cid:
type: string
description: CID of the file on IPFS
url:
readOnly: true
type: string
description: URL with IPFS scheme for the file
gatewayUrl:
readOnly: true
type: string
description: URL to access file via HTTP through an IPFS gateway
storage-status:
readOnly: true
additionalProperties: false
required:
- phase
- tasks
properties:
phase:
type: string
description: Phase of the asset storage
enum:
- waiting
- processing
- ready
- failed
- reverted
example: ready
progress:
type: number
description: Current progress of the task updating the storage.
example: 0.5
errorMessage:
type: string
description: Error message if the last storage changed failed.
example: Failed to update storage
tasks:
type: object
additionalProperties: false
properties:
pending:
type: string
description: |
ID of any currently running task that is exporting this
asset to IPFS.
example: 09F8B46C-61A0-4254-9875-F71F4C605BC7
last:
type: string
description: |
ID of the last task to run successfully, that created
the currently saved data.
example: 09F8B46C-61A0-4254-9875-F71F4C605BC7
failed:
type: string
description: ID of the last task to fail execution.
example: 09F8B46C-61A0-4254-9875-F71F4C605BC7
securitySchemes:
apiKey:
type: http
scheme: bearer
bearerFormat: JWT
````