openapi: 3.1.0
info:
title: Livepeer AI Runner accessControl transcode API
description: An application to run AI pipelines
version: 0.0.0
servers:
- url: https://dream-gateway.livepeer.cloud
description: Livepeer Cloud Community Gateway
- url: https://livepeer.studio/api/beta/generate
description: Livepeer Studio Gateway
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:
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
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-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:
type: string
description: Path for the MP4 output
example: /samplevideo/mp4
fmp4:
type: object
additionalProperties: false
required:
- path
description: FMP4 output format
properties:
path:
type: string
description: Path for the FMP4 output
example: /samplevideo/fmp4
profiles:
type: array
items:
$ref: '#/components/schemas/transcode-profile'
targetSegmentSizeSecs:
type: number
description: How many seconds the duration of each output segment should be
creatorId:
$ref: '#/components/schemas/input-creator-id'
c2pa:
type: boolean
description: Decides if the output video should include C2PA signature
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-export-params:
type: object
additionalProperties: false
properties:
$ref: {}
pinata:
description: 'Custom credentials for the Piñata service. Must have either
a JWT or an API key and an API secret.
'
oneOf:
- type: object
additionalProperties: false
required:
- jwt
properties:
jwt:
type: string
writeOnly: true
description: 'Will be added to the Authorization header as a
Bearer token.
'
example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
- type: object
additionalProperties: false
required:
- apiKey
- apiSecret
properties:
apiKey:
type: string
description: Will be added to the pinata_api_key header.
example: '1234567890'
apiSecret:
type: string
writeOnly: true
description: Will be added to the pinata_secret_api_key header.
example: 1234567890abcdef
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:
$ref: '#/components/schemas/new-asset-payload/properties/encryption'
- 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:
$ref: '#/components/schemas/new-asset-payload/properties/encryption'
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:
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.
'
$ref: {}
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
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
clip-payload:
properties:
playbackId:
type: string
description: The playback ID of the stream or stream recording to clip. Asset playback IDs are not supported yet.
example: eaw4nk06ts2
# --- truncated at 32 KB (48 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/livepeer-com/refs/heads/main/openapi/livepeer-com-transcode-api-openapi.yml