Tracks API

Ittybit's Tracks API allows you to chapterise content and generate subtitles from your media files to make them more accessible and engaging.

The API takes an input of a file_id or url (required) and outputs a outputs a .VTT file. Additionally, you can add optional parameters to modify the output.

Endpoint

# Sources
GET https://api.ittybit.com/tasks:id
POST https://api.ittybit.com/tasks

Sample request

Generate subtitles from a video file:

const API_KEY = "YOUR API KEY HERE" // Your Ittybit API key
const response = await fetch("https://api.ittybit.com/tasks", {
  headers: {
    Method: "POST",
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
    body: JSON.stringify({
    file_id: "med_abcdefgh1234", // Required parameter: file_id or file URL
    output: {
      kind: "subtitles", // Required parameter: desired output kind
    },
  }),
},
});

Sample response

"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": "subtitles",
  },
  "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",
}

Immediately after making a request, a Task is created and the response returned will be a Task Object in JSON format. The status will show as processing until the task is completed. Making the same request again once it has completed will return the Task Object with the status as completed and the output data which will include a link to the output source file.

Body Parameters

{
  "file_id": "file_abcdefgh1234",
  "kind": "subtitles",
}

Required

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 Tasks for available kinds:

Additional parameters and modifiers:

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

For a complete list of available kinds and other modifiers, see the Tasks documentation.

Available kinds for Tracks

  • "subtitles" - transcribed speech mapped to timestamps.
  • "chapters" - chapter titles mapped to timestamps, generated from a Speech Intelligence object.
  • "thumbnail" - used in video players to let users view a preview as they scrub though the video's timeline.