Audio Description API

Prelude

All of the routes described in this document use a new api framework as of October, 2017. There are two important things to note about this that differs from some of our other api routes:

1. the apikey parameter has been replaced with api_key

2. Return values are now more standardized and machine-readable, and include sensible header codes!

With that in mind, let's proceed! 

 

API Methods

Ordering a new Audio Description

URL api.3playmedia.com/orders
Method POST
Parameters

api_key: Your API group's key to authenticate access

api_secret_key: Your API group's secret key to authenticate write access

media_file_id: Value of an existing 3Play media file id, if you are ordering a new service on an existing file.

source_url: Url of a downloadable media asset to process as a new media file

file_upload: A file upload to process as a new media file.

Note, exactly one of media_file_id, source_url, and file_upload is required.

service: Name of the service being ordered. Possible values include transcription and audio_description.

turnaround_level: [TRANSCRIPTION ONLY] The name of the turnaround level desired. Values: "two hour", "same day", "rush", "expedited", "standard", "extended". Please consult your 3Play Media account manager for more details.

extended: Use "1" for extended audio description, in which we may pause the source audio if there is not enough silence to fit in the desired amount of audio description. Use 0 (or omit) to use basic audio description, where descriptions will only be placed in existing audio spaces in your file. Use "auto" to use 3Play's recommendation, which is computed automatically based on the amount of available time between speech in the source.

You may also add the following additional attributes to the media file: "name", "description", "attribute1", "attribute2", "attribute3", "video_id", "callback_url", "thumnbail_url", "public". To specify attribute1 for your media file, for example, use the parameter "media_file[description]" (Use CGI encoding: media_file%5Bdescription%5D).

Success response

Code: 200

Body: {
  id: <Integer>,
  created_at: <Datetime>,
  state: <String>,
  project_id: <Integer>,
  media_files: <Array: {
    id: <Integer>,
    name: <String>,
    language_id: <Integer>,
    url: <String>,
    services: <Array: {
      id: <Integer>,
      type: <String>,
      state: <String>,
      media_file_id: <Integer>,
      order_id: <Integer>
    }>
  }>
}

Error response

Code: 4xx, 5xx

Body: {error: <String>}

Example

http://api.3play.dev/orders?api_key=xyz&api_secret_key=12345&media_file_id=123000&service=audio_description&extended=1 

List existing audio descriptions

URL api.3playmedia.com/audio_descriptions
Method GET
Parameters

apikey: Your API group's key to authenticate access

state: Filter by state. Valid values are "complete", "in_progress", and "rejected"

Success response

Code: 200

Body: {data: <Array: {
  id: <Integer>,
  media_file_id: <Integer>,
  state: <String>,
  extended: <Boolean>,
  speaker_name: <String>,
  speaking_rate: <Integer>
}>}

Error response

 Code: 4xx, 5xx

Body: {error: <String>}

Example

http://api.3playmedia.com/audio_descriptions/state=in_progress


Show details for a specific audio description

URL api.3playmedia.com/audio_descriptions/:id
Method GET
Parameters

apikey: Your API group's key to authenticate access

Success response

Code: 200

Body: {data: {
  id: <Integer>,
  media_file_id: <Integer>,
  state: <String>,
  extended: <Boolean>,
  speaker_name: <String>,
  speaking_rate: <Integer>
}}

Error response

 Code: 4xx, 5xx

Body: {error: <String>}

Example

http://api.3playmedia.com/audio_descriptions/123

List available formats for [audio|mix|text] download

URL

api.3playmedia.com/audio_descriptions/audio_formats

api.3playmedia.com/audio_descriptions/mix_formats

api.3playmedia.com/audio_descriptions/text_formats

Method GET
Parameters

apikey: Your API group's key to authenticate access 

Success response

Code: 200

Body: {data: <Array: <String>>}

Error response

 Code: 4xx, 5xx

Body: {error: <String>}

Example

http://api.3playmedia.com/audio_descriptions/mix_formats

Get expiring authorized URL to download audio | mix | text

URL

api.3playmedia.com/audio_descriptions/:id/audio

api.3playmedia.com/audio_descriptions/:id/mix

api.3playmedia.com/audio_descriptions/:id/text

Method GET
Parameters

apikey: Your API group's key to authenticate access 

Success response

Code: 200

Body: {data: <String>}

Error response

 Code: 4xx, 5xx

Body: {error: <String>}

Example

http://api.3playmedia.com/audio_descriptions/123/mix?format=mp4

 

Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.
Powered by Zendesk