# Tasks
[View original](https://ittybit.com/docs/tasks)
## 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:
```js
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.
```json
{
"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](/api/tasks/get) for updates until the task is complete:
```js
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.
```json
{
"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](/docs/api/tasks) for complete examples, and to try the API yourself.
In production apps with many tasks, it's recommended you use [Webhooks](/docs/webhooks) to get notified when a task is complete. Polling for updates may hit API rate limits.
***
## 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](/docs/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](/docs/tasks#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](/docs/media)'s `urls` object, with the `ref` as the key.
e.g. `"ref": "avatar"`
```json title="GET /media/med_abcdefgh1234"
{
"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"`
```json title="GET /files/file_abcdefgh1234"
{
"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"`
```json title="GET /files/file_abcdefgh1234"
{
"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.
```json title="GET /files/file_abcdefgh1234"
{
"id": "file_abcdefgh1234",
// ... other file props
"filename": "profile-20250101.jpg",
"folder": "uploads/user123",
"url": "https://you.ittybit.net/uploads/user123/profile-20250101.jpg"
}
```
***
If multiple files have the same path, only the most recently updated file will be returned by the delivery URL.
***
## 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").
```js
const options = {
url: 'https://example.com/video.mp4',
kind: 'speech',
speakers: true
}
```
The `video` task kind has `width` and `height` (and [many other](/docs/video)) props that can be used to control the output video size.
```js
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.
} />
} />
} />
} />
} />