Captions Imports API

The captions import API can be used to import and download closed captions or translated subtitles as well as be used for file management purposes.

Click here for more information on file formats that are supported by caption import service.

IMPORTANT: If you want your API key to be encrypted please remember to use the HTTPS protocol! 

Please Note: If you query the API more than 200 times per minute your API access may be shut off. Speak to your account manager if you believe you will exceed that limit.

Import a Closed Captions File

[POST] http://api.3playmedia.com/caption_imports?apikey:apikey&[params]

[params]

caption_file=<local_caption_file> 
must conform to available input formats for project

project_id=<project_id> 
default is first project in the api collection

language_id=<language_id> 
defaults to 1, see below for querying for language_id

autodetect_language=1|0
defaults to 0, this will override any language_id that is provided

media_file_id=<existing_media_file_id> 
if provided, this is MUST exist in your api_collection
See more information on API collections

batch_id=<batch_id> 
optional. otherwise it goes into the most recent batch for the project

batch_name=<batch_name>
string, name of existing batch/folder or name a new batch

autoparagraph=1|0 
defaults to 0, set to 1 to add paragraph breaks each time a caption frame ends a sentence giving the output a cleaner looking, easier to read formatting.If you do not want do not add any paragraph breaks to imported captions then keep the default of autoparagraph=0

The POST method, if it returns successfully, returns an object like:

{"import":{"id":6758,"project_id":000,"language_id":13,"upload_method":"api","uploaded_file_name":"spanish_sample.srt","autoparagraph":false,"imported_file_type":"srt","conversion_error":null,"conversion_success":true,"archived":false,"deleted":false,"created_at":"2016-06-17T14:44:01.158-04:00","updated_at":"2016-06-17T14:44:02.382-04:00","media_file_id":1092536,"old_translation_id":null,"state":"in_progress","threeplay_transcript_id":2732698,"uploaded_by_user":"unknown"},"media_file":{"id":1092536,"project_id":000,"batch_id":47125,"duration":0,"attribute1":null,"attribute2":null,"video_id":null,"name":"spanish_sample","attribute3":null,"callback_url":null,"description":null,"created_at":"2016-06-17T14:44:02.000-04:00","updated_at":"2016-06-17T14:44:02.000-04:00","word_count":0,"thumbnail_url":null,"language_id":13,"default_service_type_id":4,"downloaded":false},"errors":[]}

Get Available Language

[GET] http://api.3playmedia.com/caption_imports/available_languages?apikey=:api_key

This API calls returns all available languages and the language_id

This call returns the following result similar to the response below but please note that this is only a partial list so run this call for the entire language_id list.

[{"language_id":1,"ietf_code":"en","iso_639_1_code":"en","name":"English","full_name":"English","description":"All English variants"},

{"language_id":3,"ietf_code":"en","iso_639_1_code":"en","name":"English","full_name":"English (GB)","description":"English as spoken/written in Great Britain"},

{"language_id":5,"ietf_code":"fr","iso_639_1_code":"fr","name":"French","full_name":"French (France)","description":"French as spoken/written in France"},

{"language_id":6,"ietf_code":"fr","iso_639_1_code":"fr","name":"French","full_name":"French (Canada)","description":"French as spoken/written in Canada"},..............

 

List All Imports

[GET] http://api.3playmedia.com/caption_imports?apikey=:api_key

This API call returns an array of imported caption file objects.
This call returns a result similar to the following...

[{"id":2,"project_id":000,"language_id":1,"upload_method":"account","uploaded_file_name":"test captions.srt","autoparagraph":true,"imported_file_type":"srt","conversion_error":null,"conversion_success":true,"archived":true,"deleted":false,"created_at":"2014-12-03T15:56:19.000-05:00","updated_at":"2016-03-19T07:57:53.000-04:00","media_file_id":520164,"old_translation_id":null,"state":"delivered","threeplay_transcript_id":000000,"uploaded_by_user":"Mickey Jagger"},{"id":3,"project_id":000,"language_id":1,"upload_method":"account","uploaded_file_name":"test captions.srt","autoparagraph":true,"imported_file_type":"srt","conversion_error":null,"conversion_success":true,"archived":true,"deleted":false,"created_at":"2014-12-03T15:57:17.000-05:00","updated_at":"2016-03-19T07:57:53.000-04:00","media_file_id":520165,"old_translation_id":null,"state":"delivered","threeplay_transcript_id":22232323,"uploaded_by_user":"Mickey Jagger"},

 

List One Import

 [GET]http://api.3playmedia.com/caption_imports/:import_id?apikey=:api_key

This API call returns an individual imported caption file object.
This call returns a result similar to the following...

{"id":6754,"project_id":000,"language_id":1,"upload_method":"account","uploaded_file_name":"EA0902H_PlacementTest.vtt","autoparagraph":false,"imported_file_type":"vtt","conversion_error":null,"conversion_success":true,"archived":false,"deleted":false,"created_at":"2016-06-06T21:48:59.000-04:00","updated_at":"2016-06-06T21:49:00.000-04:00","media_file_id":1092453,"old_translation_id":null,"state":"delivered","threeplay_transcript_id":01010101,"uploaded_by_user":"Wilson Forbin}

 

Download Closed Captions

IMPORTANT NOTE: As of 03/2016 imported files are assigned a threeplay_transcript_id.

See the above examples where the threeplay_transcript_id attribute is in bold

See more information on using the transcripts API to retrieve transcripts using the threeplay_transcript_id
See more information on using the captions API to retrieve the captions using the threeplay_transcript_id

 

Using the translations API to download captions for older captions imports

 Imported translations prior to 3/2016 will instead have old_translation_id.
 If it has an old_translation_id, you can use the (authenticated) translations API GET for the captions or transcript (where you use this old_translation_id as the translation_id)

See more information on the translations API 

If import was the default_service (i.e. you created the media_file AS the caption_import), then you can use the captions API to get the captions using the media_file_id.

Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.
Powered by Zendesk