Transcoding Jobs Quickstart

Submit an on-demand transcoding job through the Livepeer Studio API and track it to completion using the Tasks API.

AI-ready summary (for humans and assistants)

Use the Studio API base URL: https://livepeer.studio/api
Submit jobs with POST /transcode
Transcoding is asynchronous; poll GET /task/{id}
A successful POST /transcode returns a task.id
Final technical accuracy review is required from Rick (TD)

Review status

This quickstart is structurally complete and based on the GitHub-validated Studio OpenAPI spec, but Rick (TD) review is required before final publish for canonical flow accuracy and user-facing defaults.

1. Prerequisites

A Livepeer API key (backend use only)
curl (and optionally jq)
Input video accessible over HTTP or a S3-compatible source
Output storage destination (S3-compatible or web3.storage delegation proof)

2. Base URL and authentication

Base URL: https://livepeer.studio/api
Auth header: Authorization: Bearer <LIVEPEER_API_KEY>

export LIVEPEER_API_KEY="<YOUR_API_KEY>"

3. Submit a transcode job

The Studio spec requires:

input
storage
outputs

The example below uses:

HTTP input URL
S3-compatible storage output
HLS + MP4 outputs

Example request body

{
  "input": {
    "url": "https://example.com/video.mp4"
  },
  "storage": {
    "type": "s3",
    "endpoint": "https://gateway.storjshare.io",
    "bucket": "outputbucket",
    "credentials": {
      "accessKeyId": "<ACCESS_KEY_ID>",
      "secretAccessKey": "<SECRET_ACCESS_KEY>"
    }
  },
  "outputs": {
    "hls": {
      "path": "/samplevideo/hls"
    },
    "mp4": {
      "path": "/samplevideo/mp4"
    }
  },
  "profiles": [
    {
      "name": "720p",
      "width": 1280,
      "height": 720,
      "bitrate": 3000000,
      "fps": 30
    }
  ]
}

Example curl request

curl -sS \
  -X POST "https://livepeer.studio/api/transcode" \
  -H "Authorization: Bearer $LIVEPEER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": { "url": "https://example.com/video.mp4" },
    "storage": {
      "type": "s3",
      "endpoint": "https://gateway.storjshare.io",
      "bucket": "outputbucket",
      "credentials": {
        "accessKeyId": "<ACCESS_KEY_ID>",
        "secretAccessKey": "<SECRET_ACCESS_KEY>"
      }
    },
    "outputs": {
      "hls": { "path": "/samplevideo/hls" },
      "mp4": { "path": "/samplevideo/mp4" }
    },
    "profiles": [
      {
        "name": "720p",
        "width": 1280,
        "height": 720,
        "bitrate": 3000000,
        "fps": 30
      }
    ]
  }'

4. Capture the task ID

Transcoding is asynchronous. The response is a task object. Save the id field and poll the task endpoint. Example response shape (trimmed):

{
  "id": "09F8B46C-61A0-4254-9875-F71F4C605BC7",
  "type": "transcode-file",
  "status": {
    "phase": "pending",
    "updatedAt": 1587667174725
  }
}

5. Poll the task status

Use GET /task/{id} until status.phase is completed or failed.

TASK_ID="<TASK_ID_FROM_TRANSCODE_RESPONSE>"

curl -sS \
  -H "Authorization: Bearer $LIVEPEER_API_KEY" \
  "https://livepeer.studio/api/task/$TASK_ID"

Phases defined in the Studio spec include:

pending
waiting
running
failed
completed
cancelled

6. Verify completion and outputs

When status.phase is completed:

Confirm the task did not report an errorMessage
Inspect task output metadata and/or linked asset IDs
Verify the output paths you requested under outputs in your destination storage

7. Common failure modes

`401 Unauthorized`

Invalid API key
Missing/incorrect Authorization header

`422 Validation Error`

Missing required top-level fields (input, storage, outputs)
Invalid input schema (URL vs S3 object mismatch)
Invalid profiles shape

Task enters `failed`

Check status.errorMessage
Verify input URL is accessible to the service
Verify output storage credentials and bucket permissions
Re-run with a minimal profile/output combination first

8. Rick (TD) review checklist (blocking before final publish)

Confirm canonical user-facing transcoding flow for 2026 docs
Confirm recommended default profile example(s)
Confirm polling expectations and completion verification guidance
Confirm deprecated legacy examples should be removed/labeled
Confirm boundary with realtime APIs (what belongs elsewhere)

9. Next steps

Canonical references (source-of-truth first)

GitHub (primary): livepeer/docs api/studio.yaml
GitHub (primary): livepeer/docs api/gateway.openapi.yaml (for shared generate tag context)
DeepWiki (corroboration only): livepeer/docs | DeepWiki
Repo-local docs refs (unvalidated until cross-checked): /solutions/livepeer-studio/docs/api-reference/transcode/create, /solutions/livepeer-studio/docs/api-reference/tasks/get

Start Here

Concepts

Get Started

Custom AI Workflows

Guides

Resources

Transcoding Jobs Quickstart

AI-ready summary (for humans and assistants)

Review status

1. Prerequisites

2. Base URL and authentication

3. Submit a transcode job

Example request body

Example curl request

4. Capture the task ID

5. Poll the task status

6. Verify completion and outputs

7. Common failure modes

`401 Unauthorized`

`422 Validation Error`

Task enters `failed`

8. Rick (TD) review checklist (blocking before final publish)

9. Next steps

Canonical references (source-of-truth first)

Start Here

Concepts

Get Started

Custom AI Workflows

Guides

Resources

​AI-ready summary (for humans and assistants)

​Review status

​1. Prerequisites

​2. Base URL and authentication

​3. Submit a transcode job

​Example request body

​Example curl request

​4. Capture the task ID

​5. Poll the task status

​6. Verify completion and outputs

​7. Common failure modes

​401 Unauthorized

​422 Validation Error

​Task enters failed

​8. Rick (TD) review checklist (blocking before final publish)

​9. Next steps

​Canonical references (source-of-truth first)

AI-ready summary (for humans and assistants)

Review status

1. Prerequisites

2. Base URL and authentication

3. Submit a transcode job

Example request body

Example curl request

4. Capture the task ID

5. Poll the task status

6. Verify completion and outputs

7. Common failure modes

`401 Unauthorized`

`422 Validation Error`

Task enters `failed`

8. Rick (TD) review checklist (blocking before final publish)

9. Next steps

Canonical references (source-of-truth first)