Skip to content

Endpoints

Jump to bottom
Veronica edited this page Aug 5, 2019 · 11 revisions

Creating a new captions job

POST /captions

Parameters

Name Type Description
media_url string Required. The URL for the video to get the transcriptions/captions from.
parent_id string Required. Parent id that will be used to group all related jobs.
provider string Required. Provider used to dispatch job.
provider_params object Any extra parameters that should be passed to provider.
output_types array[string] Required. List of types wanted from the captions provider.

Example (3Play):

$ curl -X POST localhost:8000/captions --data @- << EOF 
{
 "media_url":"https://vp.nyt.com/video.mp4",
 "parent_id": "123",
 "provider": "3play",
 "provider_params": {"turnaround_level_id": "asr", "language_id": "1", "source_url": "https://vp.nyt.com/video.mp4", "callback": "https://callback.com" (optional)},
 "output_types": ["srt", "vtt"]
}
EOF

Response:

Status: 201 Created

{
  "id": "81e0e13b-e7d7-4064-7c3d-3989e177624b",
  "parent_id": "123",
  "media_url": "https://vp.nyt.com/video.mp4",
  "status": "processing",
  "provider": "3play",
  "provider_params": {
    "ProviderID": "1863943",
    "for_asr": "1"
  },
  "created_at": "2017-08-03T16:13:56.540697064-04:00",
  "outputs": [
    {
      "url": "",
      "type": "srt",
      "filename": "video.srt"
    },
    {
      "url": "",
      "type": "vtt",
      "filename": "video.vtt"
    }
  ],
  "done": false
}

Example (3play review):

{
 "media_url":"https://vp.nyt.com/video.mp4",
 "language": "en",
 "provider": "3play",
 "provider_params": {"provider_id": "11118500" (the ID of the transcript/caption you want to review on the 3play side), "hours_until_expiration": "4"}
}
EOF

Response:

Status: 201 Created

{
  "id": "81e0e13b-e7d7-4064-7c3d-3989e177624b",
  "parent_id": "123",
  "media_url": "https://vp.nyt.com/video.mp4",
  "status": "processing",
  "provider": "3play",
  "provider_params": {
    "ProviderID": "11118500",
    "ReviewURL":"http://external.3playmedia.com/transcripts/11118500/edit?exp_key=yWd9EeOiymheDgq7GSGdrHFC",
    "hours_until_expiration":"4",
    "provider_id":"11118500"
  },
  "created_at": "2017-08-03T16:13:56.540697064-04:00",
  "outputs": [
    {
      "url": "",
      "type": "vtt",
      "filename": "video.vtt"
    }
  ],
  "done": false
}

Example (Amara):

{
 "media_url":"https://vp.nyt.com/video.mp4",
 "parent_id": "123",
 "language": "en",
 "provider": "amara",
 "provider_params": {"subtitles_url": "https://storage.googleapis.com/caption.vtt", "sub_format": "vtt"}
}
EOF

Response:

Status: 201 Created

{
  "id": "81e0e13b-e7d7-4064-7c3d-3989e177624b",
  "parent_id": "123",
  "media_url": "https://vp.nyt.com/video.mp4",
  "status": "processing",
  "provider": "3play",
  "provider_params": {
    "ProviderID": "1863943",
    "ReviewURL":"https://amara.org/en/login-to-editor/ID/",
    "SubVersion":"1",
    "sub_format":"vtt",
    "subtitles_url":"https://storage.googleapis.com/caption.vtt"
  },
  "created_at": "2017-08-03T16:13:56.540697064-04:00",
  "outputs": [
    {
      "url": "",
      "type": "vtt",
      "filename": "video.vtt"
    }
  ],
  "done": false
}

Get Job

Get a single job by id

GET /jobs/{id}

Sample response for GET /jobs/0491f6ce-4fe7-409c-4e0b-fc8e7749695a

 {
    "id": "0491f6ce-4fe7-409c-4e0b-fc8e7749695a",
    "parent_id": "123",
    "media_url": "https://vp.nyt.com/video/2017/06/02/72801_1_guide_retirement2_wg_240p.mp4",
    "status": "error",
    "provider": "3play",
    "provider_params": {
      "ProviderID": "1861214",
      "for_asr": "1"
    },
    "created_at": "2017-08-02T17:47:06.27944-04:00",
    "outputs": [
      {
        "url": "",
        "type": "srt",
        "filename": "72801_1_guide_retirement2_wg_240p.srt"
      }
    ],
    "done": true
  }

Listing jobs

List all jobs owned by the same ParentID, we try to keep it sorted by creation date

GET /captions/{parentID}

Sample response for GET /captions/123:

Status: 200 OK

[
  {
    "id": "0491f6ce-4fe7-409c-4e0b-fc8e7749695a",
    "parent_id": "123",
    "media_url": "https://vp.nyt.com/video/2017/06/02/72801_1_guide_retirement2_wg_240p.mp4",
    "status": "error",
    "provider": "3play",
    "provider_params": {
      "ProviderID": "1861214",
      "for_asr": "1"
    },
    "created_at": "2017-08-02T17:47:06.27944-04:00",
    "outputs": [
      {
        "url": "",
        "type": "srt",
        "filename": "72801_1_guide_retirement2_wg_240p.srt"
      }
    ],
    "done": true
  },
  {
    "id": "693a288e-3dfc-4320-545c-cf4b5ea51b5d",
    "parent_id": "123",
    "media_url": "https://vp.nyt.com/video/2017/06/02/72801_1_guide_retirement2_wg_240p.mp4",
    "status": "processing",
    "provider": "3play",
    "provider_params": {
      "ProviderID": "1860935",
      "for_asr": "1"
    },
    "created_at": "2017-08-02T16:44:29.229129-04:00",
    "outputs": [
      {
        "url": "",
        "type": "srt",
        "filename": "72801_1_guide_retirement2_wg_240p.srt"
      }
    ],
    "done": false
  }
]

Caption Transcript

Generate a transcript for a given captioning job as long as the captions have been successfully created

curl -X GET /jobs/{jobId}/transcript/{captionFormat}

Sample response for GET /jobs/a5a88270-7ffd-47de-6eda-a0af96f48725/transcript/vtt:

MARCIA MARCIA MARCIA!!! right now, less than two weeks till the Iowa caucuses. So that finish in Iowa. WHY AM I BEING PERSECUTED?! But it’s a small state with a population of three million people. So why do we care. So much about it. New York Times reporter trip Gabriel has been living in Des Moines for the past year to try and answer that question. It’s easy to get.

Download Captions

Download the captions for a successful job in the specified format

curl -X GET /jobs/{jobId}/download/{captionFormat}

Sample response for GET /jobs/a5a88270-7ffd-47de-6eda-a0af96f48725/download/vtt:

WEBVTT

NOTE Paragraph

00:00:09.240 --> 00:00:11.010
MARCIA MARCIA MARCIA!!!

00:00:11.010 --> 00:00:14.190
right now, less than two
weeks till the Iowa caucuses.

00:00:14.190 --> 00:00:15.670
So that finish in Iowa.

00:00:15.670 --> 00:00:18.270
WHY AM I BEING
PERSECUTED?!

00:00:18.270 --> 00:00:20.280
But it’s a small state
with a population

00:00:20.280 --> 00:00:21.510
of three million people.

00:00:21.510 --> 00:00:22.360
So why do we care.

00:00:22.360 --> 00:00:24.180
So much about it.

00:00:24.180 --> 00:00:25.740
New York Times
reporter trip Gabriel

00:00:25.740 --> 00:00:27.698
has been living in Des
Moines for the past year

00:00:27.698 --> 00:00:29.550
to try and answer that question.

00:00:29.550 --> 00:00:31.220
It’s easy to get.%
Clone this wiki locally