Ittybit

Introduction

Tasks let you do powerful things with your media files in just a few lines of code.

The input to a task is any publicly-accessible (or signed) URL pointing to a media file.

Tasks create new output files such as transcoded video, resized images, extracted audio, subtitles, and more.

How tasks work

Tasks take a url as input, plus a kind to specify what type of processing to perform.

That's all that's needed for some tasks. For example, to transcribe a video:

curl -X POST "https://api.ittybit.com/tasks" \
-H "Authorization: Bearer ITTYBIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "url": "https://example.com/video.mp4",
  "kind": "speech"
}'

For tasks that support additional configuration, options are passed under the options key:

curl -X POST "https://api.ittybit.com/tasks" \
-H "Authorization: Bearer ITTYBIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "url": "https://example.com/video.mp4",
  "kind": "video",
  "options": {
    "width": 1280,
    "height": 720,
    "format": "mp4",
    "quality": "high"
  }
}'

Task object

When a task is created, it returns a 201 Created response containing the task object.

{
  "id": "task_abcdefgh12345678",
  "object": "task",
  "kind": "video",
  "status": "waiting",
  "run_id": "run_abcdefgh12345678",
  "parent_id": null,
  "progress": null,
  "options": {
    "width": 1280,
    "height": 720,
    "format": "mp4",
    "quality": "high"
  },
  "inputs": [],
  "outputs": [],
  "metadata": {},
  "error": null,
  "created_at": 1735689825,
  "started_at": null,
  "finished_at": null,
  "updated_at": 1735689825
}

Task statuses

Tasks progress through the following statuses:

Status	Description
`waiting`	Task has been created and is waiting to be processed
`validating`	Input is being validated
`queued`	Task is queued for processing
`processing`	Task is actively being processed
`finishing`	Processing is complete, outputs are being finalized
`succeeded`	Task completed successfully
`failed`	Task failed — check the `error` field for details
`cancelled`	Task was cancelled

Task progress

Tasks are processed asynchronously. You can poll the task endpoint for updates:

curl "https://api.ittybit.com/tasks/task_abcdefgh12345678" \
-H "Authorization: Bearer ITTYBIT_API_KEY"

A completed task will have status: "succeeded" and populated outputs:

{
  "id": "task_abcdefgh12345678",
  "object": "task",
  "kind": "video",
  "status": "succeeded",
  "run_id": "run_abcdefgh12345678",
  "parent_id": null,
  "progress": 100,
  "options": {
    "width": 1280,
    "height": 720,
    "format": "mp4",
    "quality": "high"
  },
  "inputs": [
    {
      "kind": "source",
      "type": "video/mp4",
      "width": 3840,
      "height": 2160,
      "duration": 123.45,
      "url": "https://store.ittybit.net/..."
    }
  ],
  "outputs": [
    {
      "kind": "source",
      "type": "video/mp4",
      "width": 1280,
      "height": 720,
      "duration": 123.45,
      "url": "https://store.ittybit.net/..."
    }
  ],
  "metadata": {},
  "error": null,
  "created_at": 1735689825,
  "started_at": 1735689830,
  "finished_at": 1735689886,
  "updated_at": 1735689886
}

In production apps with many tasks, use Webhooks to get notified when a task completes instead of polling.

Required fields

All tasks require:

url — a publicly accessible or signed URL pointing to the input file
kind — the type of task to create

Task options

Different task kinds have different options that control the output. Options are passed under the options key.

For example, the video task has width, height, format, quality, and other options:

{
  "url": "https://example.com/video.mp4",
  "kind": "video",
  "options": {
    "width": 1920,
    "height": 1080,
    "quality": "high"
  }
}

The speech task has no options — all analysis is returned by default:

{
  "url": "https://example.com/video.mp4",
  "kind": "speech"
}

Tasks

Introduction

How tasks work

Task object

Task statuses

Task progress

Required fields

Task options

Task kinds

Media

Video

Image

Audio

Adaptive Video

Tracks

Subtitles

Chapters

Thumbnails

Intelligence

Speech

NSFW

Summary

Outline

On this page