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 requires 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 convert an image to a different format, resize a video, or create a transcript from an audio file.

You can also include additional parameters such as width, duration, or confidence to customize the output. For a complete list of modifiers, see the Tasks documentation.

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

Endpoints

Create Task

const task = {
  url: 'https://demo-files.ittybit.net/video.mp4', 
  format: 'jpeg'
}
  
const response = await fetch('https://api.ittybit.com/tasks', {
  method: 'POST',  
  headers: { 'Authorization': 'Bearer ITTYBIT_API_KEY' },  
  body: JSON.stringify(task)
});

Creates a new task, which will use the file specified by file_id or url to create an output specified by kind.

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

Required:

  • Either url or file_id must be provided.

    • url string - The URL of the file to use as the input for the task. This must be a publicly accessible URL.
    • file_id string - The ID of the file to use as the input for the task. This must be a file that has been uploaded to Ittybit. You can find the file_id in the response when you upload a file via the API.

  • kind string - The desired output type. See below for available kinds:

Additional parameters and modifiers:

  • format string - The desired format of the output file. This is only applicable for certain kinds. See below for available formats.

  • confidence float - The minimum confidence level required for the output. This is only applicable for certain kinds. See below for available confidence levels.

    • "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" - a .json file with the detected objects in the video.

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

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

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

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

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

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

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

    • "thumbnails" - 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.