Tasks

Introduction

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

The input to a task can be:

• Any of the Files in your ittybit project
• Any publicly-accessible (or signed) URL, no matter where it's hosted

Tasks output new files, which can be:

• Sources
• Tracks
• Intelligence

How tasks work

Tasks take either a file_id or a url as input, plus a kind prop to describe which output file will be created.

That's all that's needed for some tasks!

e.g. to transcribe a video:

const options = {
  url: 'https://example.com/video.mp4',
  kind: 'speech',
}
// Pass options to an SDK or API request e.g:
const task = await ittybit.tasks.create(options);

Task objects

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

This object contains information about the task, including the id, status, and created timestamp.

{
  "id": "task_abcdefgh12345678",
  "object": "task",
  "kind": "speech",
  "input": {
    "id": "file_abcdefgh12345678",
    "kind": "video",
    "type": "video/mp4",
    "width": 3840,
    "height": 2160,
    "duration": 123.45,
    "fps": 24,
    "filesize": 123456789,
    "bitrate": 8000440,
    "url": "https://you.ittybit.net/file_abcdefgh12345678.mp4",
    "metadata": {},
    "created": "2025-01-01T01:23:45.678Z",
    "updated": "2025-01-01T01:23:45.678Z"
  },
  "options": {
    "speakers": true,
  },
  "output": null,
  "status": "pending",
  "created": "2025-01-01T01:23:45.678Z",
  "updated": "2025-01-01T01:23:45.678Z",
}

Task progress

Tasks are sent to a queue and processed asynchronously.

You can use the task's id to poll the task endpoint for updates until the task is complete:

const updatedTask = await ittybit.tasks.get(task.id);

A completed task will have a status of completed, and a output object containing the details of the created file.

{
  "id": "task_abcdefgh12345678",
  "object": "task",
  "kind": "speech",
  "input": {
    "id": "file_abcdefgh12345678",
    "kind": "video",
    "type": "video/mp4",
    "width": 3840,
    "height": 2160,
    "duration": 123.45,
    "fps": 24,
    "filesize": 123456789,
    "bitrate": 8000440,
    "url": "https://you.ittybit.net/file_abcdefgh12345678.mp4",
    "metadata": {},
    "created": "2025-01-01T01:23:45.678Z",
    "updated": "2025-01-01T01:23:45.678Z"
  },
  "options": {
    "speakers": true,
  },
  "output": {
    "id": "file_abcdefgh90123456",
    "kind": "speech",
    "type": "application/json",
    "filesize": 123456,
    "url": "https://you.ittybit.net/file_abcdefgh90123456.json",
    "metadata": {},
    "created": "2025-01-01T01:23:46.789Z",
    "updated": "2025-01-01T01:23:46.789Z"
  },
  "status": "completed",
  "created": "2025-01-01T01:23:45.678Z",
  "updated": "2025-01-01T01:23:46.789Z",
}

See the Task API docs for complete examples, and to try the API yourself.

Required props

All tasks require:

• either a file_id or url to use as the input file
• the kind of task to create

File ID

The file_id should be the unique ID of a file in your project's Files collection.

e.g. "file_id": "file_abcdefgh1234"

URL

The url should be the URL of the video file to process.

This should be a publicly accessible or signed URL.

e.g. "url": "https://example.com/video.mp4"

Kind

The kind of file to create. This should be one of ittybit's available task kinds.

e.g. "kind": "video"

Shared options

All tasks support the following (optional) props:

• ref
• folder
• filename

Ref

The reference name for the file.

When set, the output file will be included in the Media Object's urls object, with the ref as the key.

e.g. "ref": "avatar"

{
  "id": "med_abcdefgh1234",
  // ... other media props
  "urls": { 
    "original": "https://you.ittybit.net/file_abcdefgh1234.mp4", 
    "avatar": "https://you.ittybit.net/file_abcdefgh5678.jpg" 
  }
}

Folder

The folder to save the output file to.

When set, the output file will be added to the specified folder and the delivery URL will include the folder in the path.

e.g. "folder": "uploads/user123"

{
  "id": "file_abcdefgh1234",
  // ... other file props
  "folder": "uploads/user123",
  "url": "https://you.ittybit.net/uploads/user123/file_abcdefgh1234.mp4"
}

Filename

The filename to save the output file to.

When set, the output file will be saved with the specified filename and the delivery URL will include the filename in the path.

e.g. "filename": "user123-profile-20250101.jpg"

{
  "id": "file_abcdefgh1234",
  // ... other file props
  "filename": "user123-profile-20250101.jpg",
  "url": "https://you.ittybit.net/user123-profile-20250101.jpg"
}

You can also use the filename option in combination with the folder option to save the output file to a specific path.

{
  "id": "file_abcdefgh1234",
  // ... other file props
  "filename": "profile-20250101.jpg",
  "folder": "uploads/user123",
  "url": "https://you.ittybit.net/uploads/user123/profile-20250101.jpg"
}

Task options

Different task kinds have different (optional) props that can be used to control the output.

For example, the speech task kind has a speakers (boolean) prop that can be used to control whether the output should identify and label separate speakers (known as "diarization").

const options = {
  url: 'https://example.com/video.mp4',
  kind: 'speech',
  speakers: true
}

The video task kind has width and height (and many other) props that can be used to control the output video size.

const options = {
  url: 'https://example.com/video.mp4',
  kind: 'video',
  width: 1920,
  height: 1080
}

See the individual task kind docs (below) for more information on the available options.

Task kinds

Sources

Sources are files that contain actual content, such as video, audio, or image data.

Tracks

Tracks provide additional information about your media, such as subtitles, chapters, and thumbnails.

Intelligence

Intelligence files contain rich data about your media, such as transcripts, descriptions, and NSFW detection.