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

  https://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.

Connections

We require all new connections to the 3Play API be made via encrypted HTTPS requests, not plain HTTP. If you have a choice of connection protocols, we recommend TLS v1.2 or v1.3.

TLS v1.1 is supported but not recommended, and earlier protocols (e.g. TLS v1.0 and its SSLv2/SSLv3 predecessors) are not supported.

After December 15, 2020, HTTPS will be mandatory. Any client accessing http://api.3playmedia.com will be immediately redirected (via HTTP status code 302) to an equivalent encrypted HTTPS endpoint (https://api.3playmedia.com). At this point clients must either originate connections on HTTPS (preferred) or, at minimum, respect 302 redirects. After December 15, API calls that do neither will fail.

Strong, encrypted connections should be the default for any new work.

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 https://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 https://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.

Signed requests

Standard API requests are guarded by HTTPS standards from third parties intercepting the API key and performing replay attacks. For an added level of security, contact us to set up your account to require signed requests. These signed requests use a secret key that is never transmitted or revealed to encrypt a signature for each request. Signatures include an expiration time that can be set to any value you desire.

Once your account is set up to require signed requests, all standard workflow and admin requests from any API key in your account are required to include signature and signature_expires parameters.

  • signature_expires: Time since epoch, in seconds, after which the signature is considered invalid. This can be any value of your chosing.
  • signature: A SHA-256 hash computed using the method outlined below.

To compute your request signature:

  • Join the following strings with the | character
    1. Request path (starting from /v3)
    2. Request method, in all caps
    3. Request querystring with parameters alphabetized, ecluding signature but including signature_expires
  • Compute the SHA-256 hash of the string above. Encode the result as a Base-64 string. (Use RFC4648, i.e. without line feeds.) The result is your request signautre.
  • Remember to URL-encode your signature in your request if you are using a low-level tool such as curl.

As an example, let's generate a signature for a request to update a media file. We will make a PATCH request to https://api.3playmedia.com/v3/files/100 with parameters name, api_key, signature, and signature_expires. Let's use the following mock values:

  • name=foo
  • api_key=123abc
  • signature_expires=1445471340

Our signature payload will be /v3/files/100|PATCH|api_key=123abc&name=foo&signature_expires=1445471340 (remember, paramters must be alphabetized). This gives us a Base-64 encoded SHA-256 hash value of iLwRQXzXq69A7Uxq965bYZi/StZDGr7+SFU3aj4l8pM= (no line feed).

When used in curl (where we have to remember to URI-escape characters such as / and =), this might look like:

curl -X PATCH "https://api.3playmedia.com/v3/files/100?api_key=123abc&name=foo&signature_expires=1445471340&signature=iLwRQXzXq69A7Uxq965bYZi%2FStZDGr7%2BSFU3aj4l8pM%3D"