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:
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.
We require connections to the 3Play API be made via encrypted HTTPS requests, using TLS v1.2 or v1.3. Older, less-secure protocol options such as TLSv1.1, TLSv1.0, and their SSLv2/SSLv3 predecessors are not supported.
There is a limited exception to this HTTPS-everywhere rule for API::P requests. They are for publishing and therefore public by transit HTTP unencrypted.
Any client accessing http://api.3playmedia.com (other than for API::P) will be redirected via a standard HTTP status code (such as 301 or 302) to an equivalent HTTPS endpoint (https://api.3playmedia.com). Clients should originate connections on HTTPS, but failing that, they must at minimum respect and follow redirects.
Most endpoints are limited to 500 requests per minute per API key. When this limit is exceeded, a "429 Too Many Requests"
response will be returned. The exception to this is the /v3/transcripts/:id/text endpoint, which
is limited to 120 requests per minute per API key.
API resources are finite, so we ask customers to follow good design practice when using the API. This mostly refers to minimizing unnecessary api calls:
| Inefficient | Best Practice |
|---|---|
| Requesting status on all files in your account | Limiting status requests to those files that are currently in progress |
| Making status request calls every second on regular turnaround files | Making status requests calls every hour on regular turnaround files |
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.
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:
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.
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:
| character
/v3)signature but including signature_expiresAs 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=fooapi_key=123abcsignature_expires=1445471340Our 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"