IMPORTANT: If you want your API key to be encrypted please remember to use the HTTPS protocol!

 

Please Note: The API can only be queried 120 times per minute. Requests above this limit will not be processed and the response header will display a 403 Forbidden. Requests can be resumed once the rate limit will allow it. Speak to your account manager if you believe you will exceed that limit.

 

Files API Methods

API methods are handled at the Collection level.
Collections are groups of files that a user can access in the account system.

Note: On any method that lists files, you can use the pagination parameters to control output:

• 
per_page
• page
• limit 

List All Files & Filter Based On File Attributes

To list all files use the following format:

[GET] http://api.3playmedia.com/files?apikey=:api_key

Tip: Filter your request by using a URL encoded string as the q param. For example, to filter for files that are in Complete or Delivered state from batch_id 2160, add q=state%3Dcomplete,delivered%26batch_id=2160

Here is a list of all file attributes that may be filtered on:

Attribute1

api.3playmedia.com/files?apikey=:api_key&q=attribute1=111111111

Attribute2

api.3playmedia.com/files?apikey=:api_key&q=attribute2=111111112

Attribute3

api.3playmedia.com/files?apikey=:api_key&q=attribute3=111111113

Name

api.3playmedia.com/files?apikey=:api_key&q=name=MonsterWalks

Project id

api.3playmedia.com/files?apikey=:api_key&q=project_id=999

File id

api.3playmedia.com/files?apikey=:api_key&q=file_id=1000566

State

api.3playmedia.com/files?apikey=:api_key&q=state=complete

Batch id

api.3playmedia.com/files?apikey=:api_key&q=batch_id=39813

Video id

api.3playmedia.com/files?apikey=:api_key&q=video_id=123456789

Note: The Archived parameter will have no effect because archived files are not included in the api collection.

Tip: In order to use the Downloaded parameter, the query must be done with a boolean.

api.3playmedia.com/files?apikey=:api_key&q=downloaded=1

api.3playmedia.com/files?apikey=:api_key&q=downloaded=0

 

Sample output: 

The response to all of these queries will have the following format

{"files":[{"duration":97800,"name":"Viewing and Editing Your Transcript and Caption Files","attribute1":"","created_at":"2011-01-27T12:38:46-05:00","attribute2":"","public":null,"video_id":"764301874001","attribute3":"","project_id":10219,"batch_id":2160,"id":22497,"rush":false,"description":"","state":"complete"},{"duration":89333,"name":"File Management","attribute1":"","created_at":"2011-01-27T12:38:47-05:00","attribute2":"","public":null,"video_id":"764301876001","attribute3":"","project_id":10219,"batch_id":2160,"id":22498,"rush":false,"description":"","state":"complete"},{"duration":116400,"name":"Quick Start","attribute1":"","created_at":"2011-01-27T12:38:48-05:00","attribute2":"","public":null,"video_id":"764427413001","attribute3":"","project_id":10219,"batch_id":2160,"id":22499,"rush":false,"description":"","state":"complete"}],"summary":{"total_entries":7,"total_pages":3,"per_page":3,"current_page":1}}

 

List One File By ID

[GET] http://api.3playmedia.com/files/:id?apikey=:api_key

 

Sample Output

{"name":"Viewing and Editing Your Transcript and Caption Files","duration":97800,"created_at":"2011-01-27T12:38:46-05:00","attribute1":"","video_id":"764301874001","public":null,"attribute2":"","project_id":10219,"attribute3":"","batch_id":2160,"id":22497,"rush":false,"description":"","state":"complete"}

 

List One File By Video ID

[GET] http://api.3playmedia.com/files/:video_id?apikey=:api_key&usevideoid=1

 

When you upload files, you can specify a video_id parameter if you would like to track files on the 3Play system by your own internal tracking mechanism.

NOTE: If there are multiple files with the same video ID, this endpoint will return an arbitrary file. The current behavior is to return the oldest file with that video_id, but this behavior should not be relied upon and may change without warning in the future.  To list all files with a given video_id use the files endpoint to filter on the video_id attribute 

Search Within File Transcripts

[GET] http://api.3playmedia.com/files/search?apikey=:api_key&query=

Note: a query string must be inserted after the last "=" sign at the end of the above query.

This search method returns matching files based on the specified query string being present within the transcript of the file.

 

 

Search Files, Return Matching Files with Detailed Segments

[GET] http://api.3playmedia.com/files/segmentmap?apikey=:api_key&query=:query

 Note: The :query string should be URL-encoded (e.g. with '%20' for spaces). 

This search method returns matching files along with a breakdown of which segments contained in that file match the specified query string.

To only return all files that contain segments which match the complete string, use quotes around the :query string.

Example

&query=%22hello%20world%22

This will return only files that contain the string 'hello world' and populate the segment map with a breakdown of the segments that match those strings. 

To search for all files that contain all of a set of words, but in no particular order, do not use quotations around the :query string. 

Example

&query=hello%20world

The above would return all files that contained both 'hello' and 'world.' It would only populate segment maps with instances where 'hello world' appear as a string. Files that contain both words, but never contained the complete string will be returned with empty segment maps.

 

 

Upload a New File                                                   

[POST] https://api.3playmedia.com/files?apikey=:apikey&api_secret_key=:secretkey

This method allows a link or file to be posted to the 3Play Account system. As soon as the file reaches the system, it will begin processing.  

To upload a link, specify your downloadable media file url in the link parameter.

To upload a file, attach the :localfile as the file parameter (e.g. using a multi-part form).

In both cases, you can upload to a specific folder. If you know the system id for that folder, use the batch_id attribute.

Alternatively, you can upload to a specific folder with the batch_name attribute. If a folder with that name already exists, the file will go there. If it does not exist, it will be created for you.

If a folder is not specified, or the specified folder is not found, the upload will go into your last created folder. If you have no folders on file, the file will go into a new folder named "API Upload Folder".

By default, this POST creates an order for transcription service on the file. You may provide the for_alignment=1 or for_asr=1 to order an alignment or ASR service on the file.

Required Properties:

• apikey
• api_secret_key
• link or file

Available Properties:

• name
• turnaround_level (options: same_day, rush, expedited, two_hour, and extended.  standard defaults to standard)
• video_id
• attribute1
• attribute2
• attribute3
• batch_id
• batch_name
• callback_url
• for_alignment=1
• transcript_for_alignment=<raw_text>
• for_asr=1
• language_id (options for transcription:  1=English, 13=Spanish)

A successful upload will return an integer value tied to the internal file_id for processing. If you do not receive this integer value, please check the error status, make necessary modifications to your POST, and try again.

PLEASE NOTE:

a) If the user provides BOTH for_alignment=1 AND for_asr=1, THEN for_alignment=1 supersedes.
     There is no validation/error-return for this pathological case.

b) If EITHER for_asr=1 OR for_alignment=1 is provided, then ANY turnaround_level option is ignored. 
     The turnaround is always set to Standard for_asr or for_alignment.

Character limits

Note that database limits in regards to character limits are now explicitly checked on POST. 

When the character limit is exceeded an error message (e.g. "URLs and callback URLs are restricted to 500 characters"), or in the case of other fields, we truncate to the length that is restricted in the database:

Character limits: File name

• The name of a file cannot exceed 300 characters name (even if derived from the filename or URL). When the character limit is exceeded the name is truncated to 300 characters.
• If you provide a name it cannot be empty string
• If a file name is not provided, the name then is derived from either the url or the filename of the uploaded file.

Character limits: URLS and Callback URLs

• URLs and callback URLs are restricted to 500 characters. When the character limit is exceeded the name is truncated to 500 characters.

Character limits: Attribute fields and video ID field Attribute fields and Video ID

• The attribute1, attribute2, attribute3, and video_id fields cannot exceed 127 characters per field. Fields that exceed this character limit are truncated to 127 characters.

You can also use this API to upload pre-existing transcripts and media files to create captions and/or use the 3Play Media interactive video plugins using the alignment service.
See more information on using the API to upload transcripts and media files for alignment.  

Note: Before uploading a file, the API can be used to query for a file's delivery date for the different turnaround times available at the time the file would be uploaded. To query for the delivery date use the following API call:

[GET] http://api.3playmedia.com/turnaround_levels.js?apikey=:apikey

 

Updating an existing file's metadata

Use a PUT method to edit the metadata of an existing 3Play Media file via API.

       [PUT] http://api.3playmedia.com/files/:fileid?apikey=:apikey&api_secret_key=:secret&:properties

Setting Up a Status Postback Worfklow using callback_url

When building a workflow over the 3Play API, you can streamline your processes by utilizing the callback_url parameter when creating files.

If a callback_url is specified, the 3Play system will automatically ping the callback_url when a file is complete or goes to an error state.  The 3Play system will execute a HTTP POST to the callback_url and include the following params:

• file_id - 3Play unique system ID for your file
• video_id - Your internal unique system ID for the file, if specified when the file was created
• status - The new status of the file (either "complete" or "error")
• error_description - text error description if the status is "error"
• duration - The duration of the file, in milliseconds
• attribute1 - Wildcard field that can be used for custom metadata and tracking
• attribute2 - Wildcard field that can be used for custom metadata and tracking
• attribute3 - Wildcard field that can be used for custom metadata and tracking
• project_name - The name of the project that the file is processing in
• batch_id - The folder or "batch" id that the file is currently in
• batch_name - The folder or "batch" name that the file is currently in

If you are tracking files internally with a database of your own, we recommend using the video_id field when posting files so that you can drive the workflow off of your internal tracking system, to make things easier on your end.  Alternatively, you can store the file_id value that is returned when you POST a file to 3Play and reference that ID when Status Postback alerts are sent.

Simulating Status Postbacks

If you are testing demo files with the 3Play system and want to simulate an error or completion status post back, you can do this by posting to:

[POST] http://api.3playmedia.com/files/:file_id/simulate_status_update

Required params: 
apikey, api_secret_key
state (complete or error)

Note: The file associated with the file_id must have a callback_url for this to succeed.

The 3Play API will return a JSON object with the response from your server if the callback was successful.

Sample response:
{iserror:false, message{}, server_response: “hello world”}

 

Querying for Complete Files

Finished files have a single state "complete"

A "complete" file is one that has finished processing but has not undergone the daily email notification process. 

If you want to grab a list of all complete files, use the query:

[GET] http://api.3playmedia.com/files?apikey=:api_key&q=state%3Dcomplete

Here are the states that a file may be in:

in_progress

error

complete

delivered