openapi: 3.1.0
info:
title: Livepeer API Reference accessControl transcode API
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: transcode
description: Operations related to transcode api
paths:
/transcode:
post:
operationId: transcodeVideo
x-speakeasy-name-override: create
summary: Transcode a video
tags:
- transcode
description: "`POST /transcode` transcodes a video file and uploads the results to the\nspecified storage service.\n\\\n\\\nTranscoding is asynchronous so you will need to check the status of the\ntask in order to determine when transcoding is complete. The `id` field\nin the response is the unique ID for the transcoding `Task`. The task\nstatus can be queried using the [GET tasks\nendpoint](https://docs.livepeer.org/reference/api/get-tasks):\n\\\n\\\nWhen `status.phase` is `completed`, transcoding will be complete and\nthe results will be stored in the storage service and the specified\noutput location.\n\\\n\\\nThe results will be available under `params.outputs.hls.path` and\n`params.outputs.mp4.path` in the specified storage service.\n## Input\n\\\nThis endpoint currently supports the following inputs:\n- HTTP\n- S3 API Compatible Service\n\\\n\\\n**HTTP**\n\\\nA public HTTP URL can be used to read a video file.\n```json\n{\n \"url\": \"https://www.example.com/video.mp4\"\n}\n```\n| Name | Type | Description |\n| ---- | ------ | ------------------------------------ |\n| url | string | A public HTTP URL for the video file. |\n\nNote: For IPFS HTTP gateway URLs, the API currently only supports “path\nstyle” URLs and does not support “subdomain style” URLs. The API will\nsupport both styles of URLs in a future update.\n\\\n\\\n**S3 API Compatible Service**\n\\\n\\\nS3 credentials can be used to authenticate with a S3 API compatible\nservice to read a video file.\n\n```json\n{\n \"type\": \"s3\",\n \"endpoint\": \"https://gateway.storjshare.io\",\n \"credentials\": {\n \"accessKeyId\": \"$ACCESS_KEY_ID\",\n \"secretAccessKey\": \"$SECRET_ACCESS_KEY\"\n },\n \"bucket\": \"inbucket\",\n \"path\": \"/video/source.mp4\"\n}\n```\n\n\n## Storage\n\\\nThis endpoint currently supports the following storage services:\n- S3 API Compatible Service\n- Web3 Storage\n\\\n\\\n**S3 API Compatible Service**\n```json\n{\n \"type\": \"s3\",\n \"endpoint\": \"https://gateway.storjshare.io\",\n \"credentials\": {\n \"accessKeyId\": \"$ACCESS_KEY_ID\",\n \"secretAccessKey\": \"$SECRET_ACCESS_KEY\"\n },\n \"bucket\": \"mybucket\"\n}\n```\n\n**Web3 Storage**\n\n```json\n{\n \"type\": \"web3.storage\",\n \"credentials\": {\n \"proof\": \"$UCAN_DELEGATION_PROOF\",\n }\n}\n```\n\n\n\n## Outputs\n\\\nThis endpoint currently supports the following output types:\n- HLS\n- MP4\n\n**HLS**\n\n```json\n{\n \"hls\": {\n \"path\": \"/samplevideo/hls\"\n }\n}\n```\n\n\n**MP4**\n\n```json\n{\n \"mp4\": {\n \"path\": \"/samplevideo/mp4\"\n }\n}\n```\n"
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/transcode-payload'
responses:
default:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/error'
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/task'
x-speakeasy-name-override: data
x-codeSamples:
- lang: typescript
label: transcodeVideo
source: "import { Livepeer } from \"livepeer\";\nimport {\n TranscodePayloadSchemasStorageType,\n TranscodeProfileEncoder,\n TranscodeProfileProfile,\n} from \"livepeer/models/components\";\n\nconst livepeer = new Livepeer({\n apiKey: \"<YOUR_BEARER_TOKEN_HERE>\",\n});\n\nasync function run() {\n const result = await livepeer.transcode.create({\n input: {\n url: \"https://s3.amazonaws.com/bucket/file.mp4\",\n },\n storage: {\n type: TranscodePayloadSchemasStorageType.Web3Storage,\n credentials: {\n proof: \"EaJlcm9vdHOAZ3ZlcnNpb24BmgIBcRIg2uxHpcPYSWNtifMKFkPC7IEDvFDCxCd3ADViv0coV7SnYXNYRO2hA0AnblHEW38s3lSlcwaDjPn\",\n },\n },\n outputs: {\n hls: {\n path: \"/samplevideo/hls\",\n },\n mp4: {\n path: \"/samplevideo/mp4\",\n },\n fmp4: {\n path: \"/samplevideo/fmp4\",\n },\n },\n profiles: [\n {\n width: 1280,\n name: \"720p\",\n height: 720,\n bitrate: 3000000,\n quality: 23,\n fps: 30,\n fpsDen: 1,\n gop: \"2\",\n profile: TranscodeProfileProfile.H264Baseline,\n encoder: TranscodeProfileEncoder.H264,\n },\n ],\n });\n\n // Handle the result\n console.log(result);\n}\n\nrun();"
- lang: go
label: transcodeVideo
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(\"<YOUR_BEARER_TOKEN_HERE>\"),\n )\n\n ctx := context.Background()\n res, err := s.Transcode.Create(ctx, components.TranscodePayload{\n Input: components.CreateInputInput1(\n components.Input1{\n URL: \"https://s3.amazonaws.com/bucket/file.mp4\",\n },\n ),\n Storage: components.CreateTranscodePayloadStorageStorage1(\n components.Storage1{\n Type: components.StorageTypeS3,\n Endpoint: \"https://gateway.storjshare.io\",\n Bucket: \"outputbucket\",\n Credentials: components.StorageCredentials{\n AccessKeyID: \"AKIAIOSFODNN7EXAMPLE\",\n SecretAccessKey: \"wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY\",\n },\n },\n ),\n Outputs: components.Outputs{\n Hls: &components.Hls{\n Path: \"/samplevideo/hls\",\n },\n Mp4: &components.Mp4{\n Path: \"/samplevideo/mp4\",\n },\n Fmp4: &components.Fmp4{\n Path: \"/samplevideo/fmp4\",\n },\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.Task != nil {\n // handle response\n }\n}"
- lang: python
label: transcodeVideo
source: "from livepeer import Livepeer\nfrom livepeer.models import components\n\ns = Livepeer(\n api_key=\"<YOUR_BEARER_TOKEN_HERE>\",\n)\n\nres = s.transcode.create(request={\n \"input\": {\n \"url\": \"https://s3.amazonaws.com/bucket/file.mp4\",\n },\n \"storage\": {\n \"type\": components.StorageType.S3,\n \"endpoint\": \"https://gateway.storjshare.io\",\n \"bucket\": \"outputbucket\",\n \"credentials\": {\n \"access_key_id\": \"AKIAIOSFODNN7EXAMPLE\",\n \"secret_access_key\": \"wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY\",\n },\n },\n \"outputs\": {\n \"hls\": {\n \"path\": \"/samplevideo/hls\",\n },\n \"mp4\": {\n \"path\": \"/samplevideo/mp4\",\n },\n \"fmp4\": {\n \"path\": \"/samplevideo/fmp4\",\n },\n },\n \"profiles\": [\n {\n \"width\": 1280,\n \"name\": \"720p\",\n \"height\": 720,\n \"bitrate\": 3000000,\n \"quality\": 23,\n \"fps\": 30,\n \"fps_den\": 1,\n \"gop\": \"2\",\n \"profile\": components.TranscodeProfileProfile.H264_BASELINE,\n \"encoder\": components.TranscodeProfileEncoder.H_264,\n },\n ],\n})\n\nif res.task is not None:\n # handle response\n pass"
components:
schemas:
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
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 (<scheme>://<hostname>:<port>, <scheme>://<hostname>)
items:
type: string
clip-payload:
properties:
startTime:
type: number
description: 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)._
example: 1587667174725
endTime:
type: number
description: 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)._
example: 1587667174725
playbackId:
type: string
description: The playback ID of the stream or stream recording to clip. Asset playback IDs are not supported yet.
example: eaw4nk06ts2d0mzb
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
new-asset-payload:
properties:
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.
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
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.
error:
type: object
properties:
errors:
type: array
minItems: 1
items:
type: string
example:
- id not provided
- Account not found
task:
type: object
additionalProperties: false
properties:
id:
type: string
description: Task ID
readOnly: true
example: 09F8B46C-61A0-4254-9875-F71F4C605BC7
type:
type: string
description: Type of the task
enum:
- upload
- export
- export-data
- transcode-file
- clip
example: upload
createdAt:
readOnly: true
type: number
description: Timestamp (in milliseconds) at which task was created
example: 1587667174725
scheduledAt:
readOnly: true
type: number
description: 'Timestamp (in milliseconds) at which the task was scheduled for
execution (e.g. after file upload finished).
'
example: 1587667174725
inputAssetId:
type: string
description: ID of the input asset
example: 09F8B46C-61A0-4254-9875-F71F4C605BC7
outputAssetId:
type: string
description: ID of the output asset
example: 09F8B46C-61A0-4254-9875-F71F4C605BC7
projectId:
type: string
description: ID of the project
example: 09F8B46C-61A0-4254-9875-F71F4C605BC7
requesterId:
type: string
description: ID of the requester hash(IP + SALT + PlaybackId)
example: 09F8B46C-61A0-4254-9875-F71F4C605BC7
params:
type: object
additionalProperties: false
description: Parameters of the task
properties:
upload:
type: object
additionalProperties: false
description: Parameters for the upload task
properties:
url:
type: string
description: URL of the asset to "upload"
example: https://cdn.livepeer.com/ABC123/filename.mp4
encryption:
$ref: '#/components/schemas/new-asset-payload/properties/encryption'
c2pa:
type: boolean
description: Decides if the output video should include C2PA signature
example: true
profiles:
type: array
items:
$ref: '#/components/schemas/transcode-profile'
targetSegmentSizeSecs:
type: number
description: How many seconds the duration of each output segment should be
example: 6
export:
$ref: '#/components/schemas/export-task-params'
exportData:
type: object
additionalProperties: false
description: Parameters for the export-data task
required:
- content
properties:
content:
type: object
description: File content to store into IPFS
example:
data: Hello, World!
ipfs:
$ref: '#/components/schemas/ipfs-export-params'
type:
type: string
description: Optional type of content
example: text/plain
id:
type: string
description: Optional ID of the content
example: 09F8B46C-61A0-4254-9875-F71F4C605BC7
transcode-file:
type: object
additionalProperties: false
description: Parameters for the transcode-file task
properties:
input:
type: object
additionalProperties: false
description: Input video file to transcode
properties:
url:
type: string
description: 'URL of a video to transcode, accepts object-store format
"s3+https"
'
example: https://cdn.livepeer.com/ABC123/filename.mp4
storage:
type: object
additionalProperties: false
description: Storage for the output files
properties:
url:
type: string
description: 'URL of the output storage, accepts object-store format
"s3+https"
'
example: s3+https://accessKeyId:secretAccessKey@s3Endpoint/bucket
outputs:
type: object
additionalProperties: false
description: Output formats
properties:
hls:
type: object
additionalProperties: false
description: HLS output format
properties:
path:
type: string
description: Path for the HLS output
example: /samplevideo/hls
mp4:
type: object
additionalProperties: false
description: MP4 output format
properties:
path:
type: string
description: Path for the MP4 output
example: /samplevideo/mp4
profiles:
type: array
items:
$ref: '#/components/schemas/transcode-profile'
targetSegmentSizeSecs:
type: number
description: 'How many seconds the duration of each output segment should
be
'
example: 10
creatorId:
$ref: '#/components/schemas/input-creator-id'
c2pa:
type: boolean
description: Decides if the output video should include C2PA signature
example: false
clip:
properties:
url:
type: string
description: URL of the asset to "clip"
example: https://asset-cdn.lp-playback.monster/hls/1bde4o2i6xycudoy/static360p0.mp4
clipStrategy:
type: object
description: 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.
additionalProperties: false
properties:
startTime:
$ref: '#/components/schemas/clip-payload/properties/startTime'
endTime:
$ref: '#/components/schemas/clip-payload/properties/endTime'
playbackId:
$ref: '#/components/schemas/clip-payload/properties/playbackId'
catalystPipelineStrategy:
type: string
description: 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.
enum:
- catalyst
- catalyst_ffmpeg
- background_external
- background_mist
- fallback_external
- external
example: catalyst_ffmpeg
sessionId:
type: string
description: ID of the session
example: d32ae9e6-c459-4931-9898-e86e2f5e7e16
inputId:
type: string
description: ID of the input asset or stream
example: 09F8B46C-61A0-4254-9875-F71F4C605BC7
status:
readOnly: true
type: object
additionalProperties: false
description: Status of the task
required:
- phase
- updatedAt
properties:
phase:
type: string
description: Phase of the task
enum:
- pending
- waiting
- running
- failed
- completed
- cancelled
example: pending
updatedAt:
type: number
description: Timestamp (in milliseconds) at which task was updated
example: 1587667174725
progress:
type: number
description: Current progress of the task in a 0-1 ratio
example: 0.5
errorMessage:
type: string
description: Error message if the task failed
example: Failed to upload file
retries:
type: number
description: Number of retries done on the task
example: 3
step:
type: string
writeOnly: true
description: Step of the task processing
example: upload
output:
type: object
additionalProperties: false
description: Output of the task
properties:
upload:
type: object
additionalProperties: true
description: Output of the upload task
properties:
videoFilePath:
type: string
writeOnly: true
example: https://s3.amazonaws.com/my-bucket/path/filename.mp4
metadataFilePath:
type: string
writeOnly: true
example: https://s3.amazonaws.com/my-bucket/path/filename.json
assetSpec:
$ref: '#/components/schemas/asset'
export:
type: object
additionalProperties: false
description: Output of the export task
properties:
ipfs:
type: object
additionalProperties: false
required:
- videoFileCid
properties:
videoFileCid:
type: string
description: IPFS CID of the exported video file
example: Qmabc123xyz341
videoFileUrl:
type: string
readOnly: true
description: URL for the file with the IPFS protocol
example: ipfs://Qmabc123xyz341
videoFileGatewayUrl:
readOnly: true
type: string
description: URL to access file via HTTP through an IPFS gateway
example: https://gateway.ipfs.io/ipfs/Qmabc123xyz341
nftMetadataCid:
type: string
description: IPFS CID of the default metadata exported for the video
example: Qmabc123xyz341
nftMetadataUrl:
readOnly: true
type: string
description: URL for the metadata file with the IPFS protocol
example: ipfs://Qmabc123xyz341
nftMetadataGatewayUrl:
readOnly: true
type: string
description: 'URL to access metadata file via HTTP through an IPFS
gateway
'
example: https://gateway.ipfs.io/ipfs/Qmabc123xyz341
exportData:
type: object
additionalProperties: false
description: Output of the export data task
properties:
ipfs:
type: object
additionalProperties: false
required:
- cid
properties:
cid:
type: string
description: IPFS CID of the exported data
example: Qmabc123xyz341
transcode-payload:
additionalProperties: false
required:
- input
- storage
- outputs
properties:
input:
oneOf:
- type: object
additionalProperties: false
description: URL input video
required:
- url
properties:
url:
type: string
format: uri
pattern: ^(https?|ipfs|ar)://
description: URL of the video to transcode
example: https://s3.amazonaws.com/bucket/file.mp4
- type: object
additionalProperties: false
description: S3-like storage input video
required:
- type
- endpoint
- bucket
- path
- credentials
properties:
type:
type: string
enum:
- s3
description: 'Type of service. This is optional and defaults to `url` if
ŚURL field is provided.
'
endpoint:
type: string
format: uri
pattern: ^http(s)?://
description: '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)'
example: https://gateway.storjshare.io
bucket:
type: string
description: Bucket with input file
example: inputbucket
path:
type: string
description: Path to the input file inside the bucket
example: /path/file.mp4
credentials:
type: object
additionalProperties: false
required:
- accessKeyId
- secretAccessKey
description: Credentials for the private input video storage
properties:
accessKeyId:
type: string
description: Access Key ID
example: AKIAIOSFODNN7EXAMPLE
secretAccessKey:
type: string
description: Secret Access Key
example: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
storage:
oneOf:
- type: object
additionalProperties: false
required:
- type
- endpoint
- bucket
- credentials
description: Storage for the output files
properties:
type:
type: string
enum:
- s3
description: Type of service used for output files
endpoint:
type: string
format: uri
pattern: ^http(s)?://
description: '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)'
example: https://gateway.storjshare.io
bucket:
type: string
description: Bucket with output files
example: outputbucket
credentials:
type: object
additionalProperties: false
required:
- accessKeyId
- secretAccessKey
description: Credentials for the output video storage
properties:
accessKeyId:
type: string
description: Access Key ID
example: AKIAIOSFODNN7EXAMPLE
secretAccessKey:
type: string
description: Secret Access Key
example: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
- type: object
additionalProperties: false
required:
- type
- credentials
description: Storage for the output files
properties:
type:
type: string
enum:
- web3.storage
description: Type of service used for output files
credentials:
type: object
additionalProperties: false
required:
- proof
description: 'Delegation proof for Livepeer to be able to upload to
web3.storage
'
properties:
proof:
type: string
description: Base64 encoded UCAN delegation proof
example: EaJlcm9vdHOAZ3ZlcnNpb24BmgIBcRIg2uxHpcPYSWNtifMKFkPC7IEDvFDCxCd3ADViv0coV7SnYXNYRO2hA0AnblHEW38s3lSlcwaDjPn
outputs:
type: object
additionalProperties: false
description: Output formats
properties:
hls:
type: object
additionalProperties: false
required:
- path
description: HLS output format
properties:
path:
type: string
description: Path for the HLS output
example: /samplevideo/hls
mp4:
type: object
additionalProperties: false
required:
- path
description: MP4 output format
properties:
path:
# --- truncated at 32 KB (48 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/livepeer/refs/heads/main/openapi/livepeer-transcode-api-openapi.yml