3Play Media: Docs

• APIv3
  • Overview
  • Sandbox
  • Quick Start
  • Response Structure
  • Errors
  • Sorting & Pagination
  • Media File
  • Orders
  • Transcript
  • Audio Description
  • Live Auto Captioning
  • Batch (Folder)
  • Project
  • Delivery Routes
  • Translation Profile
  • Cheat Sheet
  • Glossary
  • Configuration
  • Additional routes
  • (Admin only) API access
  • (Admin only) Invoice
  • (Admin only) Invoice Line Item
  • (Admin only) Project
  • (Admin only) User
  • (Admin only) User Access

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.