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 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.
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_expires
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"