3Play Media: Docs

Media Files

Create, view and modify files in your 3Play Media account.

Object Representation

Unless otherwise specified, all routes return the following data structure in the data key.

Name Type Description
id Integer 3Play Media ID
name String Name of file
description String Description of file
duration Float File duration, in seconds
word_count Integer Word count from the default transcript (zero if there isn't a default transcript)
language_id Integer Primary language for file
language_ids Array<Integer> All langauges associated with this file
batch_id Integer The 3Play batch this file belongs to
reference_id String An arbitrary reference ID that can be used to identify the video in an external account, such as a CMS or other video platform. This is also referred to as the file's 'video_id'
labels Array<String> A list of labels currently applied to the file. Also referred to as 'tags' in the web UI
created_at String Date of file creation
updated_at String Date file was last updated

Actions

  • Create a new media file record at 3Play Media

    POST https://api.3playmedia.com/v3/files/

    Parameter Type Description Required Default
    source_file File An uploaded video or audio file No no default
    source_url String The URL to a publicly accessible video or audio file No no default
    name String The name of the file (maximum 300 characters) No no default
    description String The description of the file No no default
    batch_id Integer The file's batch No no default
    label String or Array<String> Label(s) for the file. Also referred to as 'tags' in the web UI No no default
    language_id Integer or Array<Integer> The file's language(s) Yes no default
    attribute1 String Arbitrary data attribute No no default
    attribute2 String Arbitrary data attribute No no default
    attribute3 String Arbitrary data attribute No no default
    reference_id String An arbitrary reference id that can be used to identify the file on an external system such as a CMS or video platform. No no default
    integration_id Integer ID of Video Platform Integration to which to link the file No no default
    vicc_parent_id Integer ID of 3Play file to act as this file's parent when ordering Video Clip Captioning. No no default

    Note: A source_file must be provided in a multipart post (e.g. using -F "source_file=@LOCAL_FILE_PATH" in curl)

    Note: A source_url should have appropriate url-encoding, e.g. for '&' and other potentially command-line confusable characters

    Note: If integration_id is provided, so must a valid reference_id (e.g. video_id)

  • List media files in your project

    GET https://api.3playmedia.com/v3/files/

    Parameter Type Description Required Default
    name String Filter by media file name No no default
    name_cont String Filter by media file name (partial match) No no default
    attribute1 String Filter by attribute1 No no default
    attribute2 String Filter by attribute2 No no default
    attribute3 String Filter by attribute3 No no default
    batch_id Integer Filter by 3Play batch ID No no default
    label String or Array<String> Filter by media file label(s) No no default
    reference_id String Filter by reference ID No no default
    created_before Datetime Filter by files created before specified date/time No no default
    created_after Datetime Filter by files created after specified date/time No no default
    archived Boolean Filter by archived / unarchived files No 0
  • Show a specific media file in your project

    GET https://api.3playmedia.com/v3/files/:id

  • Update a file's metadata

    PATCH https://api.3playmedia.com/v3/files/:id

    Parameter Type Description Required Default
    name String The name of the file (maximum 300 characters) No no default
    batch_id Integer The file's batch No no default
    label String or Array<String> Label(s) for the file. Also referred to as 'tags' in the web UI No no default
    attribute1 String Arbitrary data attribute No no default
    attribute2 String Arbitrary data attribute No no default
    attribute3 String Arbitrary data attribute No no default
    description String An open-ended description string for the media file No no default
    reference_id String An arbitrary reference id that can be used to identify the file on an external system such as a CMS or video platform. No no default
    integration_id Integer ID of Video Platform Integration to which to link the file No no default
    vicc_parent_id Integer ID of 3Play file to act as this file's parent when ordering Video Clip Captioning. No no default

    Note: The value(s) in the label parameter will result in the replacement of existing label(s). Passing in an empty value will result in all labels for that file being deleted

    Note: If integration_id is provided, file must have a valid reference_id (e.g. a video_id), or it must also be provided

    Note: If integration_id is provided as 'nil' or '0', all Video Platform Integrations will be unlinked

  • Set a file's language (only prior to ordering transcripts or audio description)

    POST https://api.3playmedia.com/v3/files/:id/set_language

    Parameter Type Description Required Default
    language_id Integer or Array<Integer> The file's language(s) Yes no default
  • Configure your file's settings

    POST https://api.3playmedia.com/v3/files/:id/configuration

    Parameter Type Description Required Default
    flag_settings String "Standard" to allow flags & uncertain terms to be marked with [? ?] or "Clean" to resolve all flags No no default
    transcript_style String "Clean Read", "Verbatim", or "Verbatim Light" No no default
    speaker_identification String Speaker identification setting No no default
    transcription_category String "Default", "Math", "Financial", or "Entertainment and Media" No no default
    audio_description_speaker Speaker Speaker name for Audio Description voice synthesis No no default
    audio_description_speaking_rate Integer Speaking rate, in words per minute, for Audio Description voice synthesis No no default
    starting_timecode String hh:mm:ss:ms No no default
    dropframe Boolean Are captions encoded with dropframe timing? No no default
    frame_rate_from_header Boolean Should the frame rate be inferred from the source file header? No no default
    fps Float Manually set the frame rate for your source file No no default
    alignment_review_mode String (Alignment service only) "Thresholded", "Off", or "On" to determine how to handle possibly suspect automated alignment No no default
    encoded_captions_single_line Boolean (Caption encoding only) Should encoded captions be displayed on a single line only? No no default
    encoded_captions_font_size Integer (Caption encoding: open captions only) Font size for encoded captions No no default

    Response contains an array of Configuration objects with the following attributes:

    Name Type Description
    name String Configuration name
    category String Configuration category
    value * Configuration value
    resource String Which resource is assigned to this configuration. Configurations are inherited from their parent resources (e.g. Project) unless set at a more specific level. "Default" means no value is set and your project is using the default value for this configuration.
  • Archive one or more files (hides from account view)

    POST https://api.3playmedia.com/v3/files/archive

    Parameter Type Description Required Default
    media_file_id Integer or Array<Integer> File id(s) Yes no default
  • Unarchive one or more files

    POST https://api.3playmedia.com/v3/files/unarchive

    Parameter Type Description Required Default
    media_file_id Integer or Array<Integer> File id(s) Yes no default

Source Actions

The following routes may be used to add or remove the source file associated with a given media file.

The POST routes return the following object representation.
Name Type Description
service_id Integer Unique ID associated with the source processing service
media_file_id Integer The 3Play media file id
status String The state of source processing service
duration Float The duration of the source file (can be nil if processing is not complete)
cancellation_reason String If status is 'rejected', this field is included and contains a brief explanation.
cancellation_details String If status is 'rejected', this field is included and may contain some details if available.
  • Upload a source file to a 3Play Media file record

    POST https://api.3playmedia.com/v3/files/:id/source

    Parameter Type Description Required Default
    source_file File File upload Yes no default
    override_duration Boolean If true, the file's duration will be replaced by that of the new source No 0
    callback String Callback URL for status updates No no default

    Note: The source_file must be provided in a multipart post (e.g. using -F "source_file=@LOCAL_FILE_PATH" in curl)

    Note: If a callback url is provided, the payload sent to that URL will be the source object representation, in application/x-www-form-urlencoded format.

  • Add a source URL to a 3Play Media file record

    POST https://api.3playmedia.com/v3/files/:id/source/set_url

    Parameter Type Description Required Default
    source_url String Downloadable audio/video file URL Yes no default
    override_duration Boolean If true, the file's duration will be replaced by that of the new source No 0
    callback String Callback URL for status updates No no default

    Note: The source_url should have appropriate url-encoding, e.g. for '&' and other potentially command-line confusable characters

    Note: If a callback url is provided, the payload sent to that URL will be the source object representation, in application/x-www-form-urlencoded format.

  • Remove a source (file or URL) from a 3Play Media file record (returns the Media File object)

    DELETE https://api.3playmedia.com/v3/files/:id/source