3Play Media: Docs


APIv3: Getting Started

To get started, you need to get a v3 API key. Please note that these are NOT the same as v1 API keys; they cannot be used interchangeably. API keys can have the following access levels:

  • Admin -- manage other api keys, users, and projects.
  • Project -- manage files, transcripts, audio descriptions and live ASRs. Place orders.
  • Observer -- Read-only access to files, transcripts, audio descriptions, etc., including ids and metadata.

Once you have an API key, you can test your access by issuing a GET request to

  http://api.3playmedia.com/v3/authenticate?api_key=<YOUR_API_KEY>

There are two methods of authentication, "basic" and "signed", set up at the account level. Basic authentication works just as described above: you provide an API key in your request parameters. For an added layer of security, signed authentication adds an expiring signature to requests, which is generated using an API secret key that is never exposed unless you request it. Such requests must be made over https. Please contact us to set up signed authentication for your account if you want this added security.

Sandbox

We strongly recommend creating a sandboxed project first to test your integration with our API. Additional information about sandboxed projects is available on our Sandbox page.

Structure

APIv3 is designed for a very natural relationship to how resources are actually represented in your project. Understanding this structure will help you navigate the APIv3 routes with ease. In your project you can have the following resources:

  • Batch -- a collection of media files.
  • File -- a named container for video, transcripts, audio descriptions, and similar assets.
  • Transcript -- Textual representation of the audio content in a file.
  • Audio Description -- Audio and/or textual representation of the video content in a file.

So, for example, to order transcription for a new video that is not yet in 3Play's system, you could:

1. Create a new media file in your project with a source (requires Project level API access):

curl -X POST -F source_file=@/path/to/your/video.mp4 http://api.3playmedia.com/v3/files?api_key=<KEY>&name=My+new+file&language_id=1

Note: Instead of providing source_file, you can provide the parameter source_url, pointing to a publicly downloadable media file source.
Note: In the above example, the '+' will get converted into spaces by curl. Using url-encoded spaces ('%20') would also do this. If the plus signs are desired in the name, then using the URL-encoded '%2B' would be used.

2. Next, order your transcript using the media file id returned from the above call (requires Project Level API access):

curl -X POST http://api.3playmedia.com/v3/transcripts/order/transcription?api_key=&media_file_id=&turnaround_level_id=1

To order additional resources, such as audio description, encoding, and translations, you can issue requests similar to step 2 to the appropriate route.