Files API Methods

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

 

Please Note: If you query the API more than 200 times per minute your API access may be shut off. 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.

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=attribute2=111111112

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.

 

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=

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

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

 

Upload a New File                                                      

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

 

This method allows a link or full 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 link in the link attribute. To upload a full file, attach the file as the file attribute.

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

You can also use the 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

Before uploading a file, the API can also 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:

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

 

Required Properties:

  • apikey
  • api_secret_key
  • link or file

 

Available Properties:

  • name
  • turnaround_level (options: same_day, rush, expedited, 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

 

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.

Amending an existing file's metadata

Use a PUT method to edit the metadata (video ID, file name, wildcard attribute fields) of an existing 3Play Media file via API.

So if you have

apikey=ABC
api_secret_key=XYZ
file_id=123
 

POST to http://api.3playmedia.com/files/123

 

_method=PUT
apikey=ABC
api_secret_key=XYZ
 
Available properties that can be edited
  • attribute1=something
  • video_id=1A2B
  • name=something
 

Managing Tags

List Tags

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


List out the tags for a given media file. The result will be a JSON object with tags as the array.


Example Result:
["physics","robots","spycraft"]

Add a Tag

[POST] http://api.3playmedia.com/files/:id/tags

required params:
apikey
api_secret_key
name


If you want to add the tag physics, set name to physics.

Remove a Tag

[POST] http://api.3playmedia.com/files/:id/tags/:tag_name


required params:
apikey
api_secret_key
_method=delete


If you want to remove the tag physics, post to http://api.3playmedia.com/files/:id/tags/physics

 

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

Note that 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)

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:

complete

rejected

pending

in_progress

Have more questions? Submit a request

3 Comments

  • 0
    Avatar
    Alex Britez

    Looking to click a button to send a Brightcove to get transcoded.  How would i go about doing this? I see that your example has a POST

    [POST] api.3playmedia.com/files

    Does this mean that my call should look like

    [POST] api.3playmedia.com/files?api=3PLAYMEDIA_APIKEY&api_secret_key=BRIGHTCOVE_READ_TOKEN&video_id=BRIGHTCOVE_ID&attribute1=SOME_METADATA_HERE

    Also, is there a way to test these upload calls without actually sending files to get get processed?

    Thanks,

    Alex B.

     

     

  • 0
    Avatar
    Gregory Sternig

    What are all the possible "states" when listing one file with http://api.3playmedia.com/files/:video_id?apikey=:api_key&usevideoid=1?  Is there a state=error and state=processing?

  • 0
    Avatar
    David Zylber

    Hi Gregory,

    Here are the states that a file may be in:

    pending
    in_progress
    complete
    delivered
    error
    under_investigation

     

    I hope this is helpful!

    Best,
    David

Please sign in to leave a comment.
Powered by Zendesk