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: Requests to list all imports and to import a closed captions file are limited to 10 requests per min. 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&api_secret_key=:secret_key&[params]
[params]
caption_file=<local_caption_file>
must conform to available input formats for project (note: this file must be attached, e.g. using the '@' syntax in curl)
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.
Caption Placement, Caption Encoding, and Audio Description for Caption Imports
Please note that Vertical Caption Placement, Caption Encoding and Audio Description services can be ordered for files imported into the 3Play Media account system once a source video has been added to the imported file
0 Comments