API overview

Overview

CaptionHub offers a fully formed RESTful API for our users to develop against, allowing deep integration with your existing tools.

Documentation

Interactive documentation is available here.

API Tokens

API Tokens are issued at a team-level: the token allows the bearer to manipulate anything to do with that 'team' (and nothing outside that team).

GET Project Status

Project Status can be acquired by GETing the endpoint for an individual project (providing a valid auth token for that project's team is supplied).

A JSON object will be returned containing:

• some project metadata
• details of the original captionset, if present (% complete, language)
• details of each translation, if present (% complete, language, email of assigned editor, whether it's approved or not)

This request can be used at any point to get the state of a project.

Project Creation API Workflow

The project creation workflow reflects some of CaptionHub's internal structures, and requires anyone implementing code against it to be able to handle callbacks.

1. Create Project

Project creation is initiated by POSTing to the projects endpoint. The data supplied by a user is:

• project name
• media (video) file for that project
• a URL that callbacks related to that project can be sent to.
• auth token

On a successful upload, a 201 Created will be returned, along with a json packet, along the lines:

{
  "projectCreated":true,
  "projectId": 123
}

The project now exists in CaptionHub - however, before any captionsets can be created for it, it needs to have its proxy video encoded, its waveform generated, and so forth. This process begins in the background.

When the encode processes are all complete, a JSON message is sent to the project's callback URL. As we use one URL for all project callbacks, this message will specify the name of the message as well as data related to it. For instance:

{
  "message": "projectEncodeState",
  "projectEncoded": true,
  "projectId": 123
}

2. Create original captionset

It's now possible to create original captions for the project. This is done by POSTing to the Project Original Captions endpoint. The data submitted should consists of:

• method to create originals (blank, plain text, timed text, automatic transcription)
• (optional) a data file to use (eg plain text or timed text)
• (optional) an alignment method for plain text import (eg 'automatic' or 'sentences')
• (optional) limits for captions (minimum duration, max length, etc). If not supplied, team defaults will be used.

CaptionHub will return 200 OK and begin to create the original captionset. This may be almost instantaneous; it may take some time if automatic transcription is used.

When the transcription is complete, a JSON message is sent again to the project callback URL.

{
  "message": "originalCaptionSetCreation",
  "originalCaptionSetCreated": true,
  "projectId": 123
}

It's now possible to either edit this original captionset via the CaptionHub UI. It's also now possible to make translated captionsets for it, either via the UI or via the API.

3. Create translated captionsets

If you wish to create translations via the API ready to be translated by end users, it's now possible to do so, by POSTing to the project captions endpoint and supplying a list of language codes to use. (This step is TBD as it's quite often performed in CaptionHub). There is no callback when this completes.

4. Callback on captionset approval

Individual captionsets (and, indeed, individual segments of captionsets) can be approved or unapproved. Every time a captionset or captionset is approved or unapproved, that state is posted to the Callback URL created on Project creation:

{
  "message": "captionSetApproved",
  "project": {
    "id": 123,
    "name": "Test Project"
  },
  "captionSet": {
    "captionSetId": 456,
    "language": {
      "name": "French",
      "code": "FR-FR"
    },
    "segment": {
      "id": 789,
      "number": 3,
      "totalSegments": 5,
    }
  }
}

segment will only be sent if there's more than one segment in the captionset (ie totalSegments > 1).

A similar message will be sent on each approval or unapproval.

N.B. Automatic callbacks/retries on failed positive responses are not supported.