Tasks

Introduction

# Transform Tasks
GET https://api.ittybit.com/tasks
POST https://api.ittybit.com/tasks
# Task Details
GET https://api.ittybit.com/tasks/:id

Tasks are the most direct way to create new variants or Sources from your existing Media or to extract data from them.

Each task receives an input (typically a file_id or URL) and a kind. The kind determines the type of object that will be created from the input. For example, you can create a new image from a video, a new video from an image, or a new audio file from a video.

You can also add additional parameters such as width, height, and more to customize the output.

You can see a list of tasks, create new tasks, and view the status of a task using the endpoints below.

Endpoints

Create Task

const ITTYBIT_API_KEY = "YOUR API KEY HERE"
const BASE_URL = "https://api.ittybit.com";
const response = await fetch(`https://api.ittybit.com/tasks`, {
  headers: {
    Method: "POST",
    Authorization: `Bearer ${ITTYBIT_API_KEY}`,
    "Content-Type": "application/json",
    body: JSON.stringify({
      input: "med_abcdefgh1234",
      output: {
        kind: "image",
        filename: "poster.jpg",
        width: 640,
      },
    }),
  },
});
curl -X POST "https://api.ittybit.com/tasks"
-H "Authorization: Bearer ITTYBIT_API_KEY"
-H "Content-Type: application/json"
-d '{
  "input": "med_abcdefgh1234",
  "output": {
    "kind": "image",
    "filename": "poster.jpg",
    "width": 640
  }
}'

Creates a new task, which will use the file passed in via the input prop and create a new file based on the output props.

The example given creates a new image from a video, with the filename poster.jpg and a width of 640 pixels.

Available kinds

Endpoint

POST /tasks

{
  "meta":{
    "id": "req_abcdefgh1234",
    "org_id": "org_abcdefgh1234",
    "project_id": "prj_abcdefgh5678",
    "method": "POST",
    "host": "https://api.ittybit.com",
    "path": "/tasks",
    "version": "2024-08-21",
    "status": 200,
    "type": "object"
  },
  "data": {
    "id": "tsk_abcdefgh5678",
    "object": "task",
    "input": "med_abcdefgh1234",
    "output": {
      "kind": "image",
      "filename": "poster.jpg",
      "width": 640,
    },
    "status": "processing",
    "created": "2024-03-30T15:00:00Z",
    "updated": "2024-03-30T15:00:00Z",
  },
  "links": {
    "self": "https://api.ittybit.com/tasks/tsk_abcdefgh5678",
    "parent": "https://api.ittybit.com /tasks",
  }
}

Body Parameters

  • input string

    The ID of the media to use as the input for the task. You can use a media_id: the id from a Media object, or a file_id: the id from a File object.

  • output object

    Defines the output for the task. The output object must include a kind and may include additional options that are specific to the kind of task.

    See below for available kinds:

    Files vs Media vs Sources (Click to enlarge)

    • "video" - Outputs a video file, you can specify the format by specifying with the "format" key and the value can be one of the following: "mp4", "cmaf", "webm", "av1". Use this to convert or resize a video.

      • "format"
        • "mp4"
        • "cmaf"
        • "webm"
        • "av1"

    • "image" - Outputs a video file, you can specify the format by specifying with the "format" key and the value can be one of the following: "jpeg", "png", "webp", "avif". Use this to convert or resize an image.

      • "format"
        • "jpeg"
        • "png"
        • "webp"
        • "avif"

    • "audio" - Outputs an audio file, you can specify the format by specifying with the "format" key and the value can be one of the following: "mp3", "wav", "ogg". Use this to convert an audio file or to isolate the audio from a video.

      • "format"
        • "mp3"
        • "wav"
        • "ogg"

    • "objects" - Outputs a .json file with the detected objects in the video.

    • "faces" - Outputs a .json file with the detected faces in the video.

    • "text" - Outputs a .json file with the detected text in the video.

    • "nsfw" - Outputs a .json file with the detected NSFW content in the video.

    • "speech" - Outputs a .json file with the detected speech in the video.

    • "subtitles" - Outputs a .vtt file with the subtitles from the video.

    • "outline" - Outputs a .json file with the detected outline in the video.

    • "chapters" - Outputs a .json file with the detected chapters in the video.

    • "thumbnails" - Outputs a .json file with the detected thumbnails in the video.

View Task

const BASE_URL = "https://api.ittybit.com";
const response = await fetch(`https://api.ittybit.com/tasks/tsk_abcdefgh1234`, {
  headers: {
    Authorization: `Bearer ${ITTYBIT_API_KEY}`,
  },
});
curl "https://api.ittybit.com/tasks/tsk_abcdefgh1234"
-H "Authorization: Bearer ITTYBIT_API_KEY"

Returns the details for a single task.

Endpoint

GET /tasks/:id

{
  "meta":{
    "id": "req_abcdefgh1234",
    "org_id": "org_abcdefgh1234",
    "project_id": "prj_abcdefgh1234",
    "method": "GET",
    "host": "https://api.ittybit.com",
    "path": "/tasks/tsk_abcdefgh1234",
    "version": "2024-08-21",
    "status": 200,
    "type": "object"
  },
  "data": {
    "id": "tsk_abcdefgh1234",
    "object": "task",
    "input": "med_abcdefgh1234",
    "output": {
      "id": "file_abcdefgh1234",
      "object": "source",
      "kind": "image",
      // ... Source object
      // https://ittybit.com/docs/sources
    },
    "status": "ready",
    "created": "2024-03-30T13:00:00Z",
    "updated": "2024-03-30T13:00:01Z",
  },
  "links": {
    "self": "https://api.ittybit.com/tasks/tsk_abcdefgh1234",
    "parent": "https://api.ittybit.com/tasks",
  }
}

Response Parameters

  • id string

    Unique identifier for the task.

  • object string

    Always task.

  • input string

    The ID of the Media or File that was used as the input for the task.

  • output integer

    An object that details the created output. Will always include an id, object, and kind. The object will depend on the kind passed in to the task when it was created. If the task has completed successfully, the output object will include the created Source, Intelligence, or Track object.

  • status string

    The status of the task. Possible values are waiting, processing, ready, error.

  • created datetime

    The date and time the task was created. ISO 8601 format.

  • updated datetime

    The date and time the task was last updated. ISO 8601 format.

List Tasks

const BASE_URL = "https://api.ittybit.com";
const response = await fetch(`https://api.ittybit.com/tasks`, {
  headers: {
    Authorization: `Bearer ${ITTYBIT_API_KEY}`,
  },
});
curl "https://api.ittybit.com/tasks"
-H "Authorization: Bearer ITTYBIT_API_KEY"

Returns a list of recent tasks.

Endpoint

GET /tasks

{
  "meta":{
    "id": "req_abcdefgh1234",
    "org_id": "org_abcdefgh1234",
    "project_id": "prj_abcdefgh1234",
    "method": "GET",
    "host": "https://api.ittybit.com",
    "path": "/tasks",
    "version": "2024-08-21",
    "status": 200,
    "type": "list",
    "total": 18,
    "limit": 12,
    "page": 1,
    "pages": 2
  },
  "data": [
    {
    "id": "tsk_abcdefgh1234",
    "object": "task",
    "input": "med_abcdefgh1234",
    "output": {
      "kind": "image",
      "filename": "poster.jpg",
      "width": 640,
    },
    "created": "2024-03-30T13:00:00Z",
    "updated": "2024-03-30T13:00:01Z",
    "status": "ready"
    }
  ],
  "links": {
    "self": "https://api.ittybit.com/tasks",
    "next": "https://api.ittybit.com/tasks?page=2",
    "prev": null,
  }
}

Query Parameters

  • page integer

    The page number to return. Default is 1.

  • limit integer

    The number of items to return per page. Default is 12. Maximum is 100.

  • sort string

    The field to sort by. Default is created. Possible values are created, updated, filesize.

  • order string

    The order to sort by. Default is desc. Possible values are asc, desc.

  • kind string

    The kind of tasks to return. Possible values are image, video, audio, or any of the source, track, or intelligence task kinds.

  • status string

    The status of the tasks to return. Possible values are ready, processing, waiting, error.