Alignment: Upload Using the API

Transcript alignment is the fastest and most cost-effective method to create captions and access 3Play Media's full suite of interactive video tools. By using the API, you can submit files directly via link or file upload for automated alignment and processing.

Prerequisites

• A Pro or Enterprise level 3Play Media account is required.
• Before you get started with alignment, you will need the following materials: 
  • API enabled on your 3Play Media account
  • A source media file
  • A plain text transcript with no unspoken elements
  • Please note that the duration of each file submitted for alignment should not exceed 2 hours.
  • DO NOT submit songs, music etc. This process is intended for speech not singing or sound effects
  • For users new to the transcript alignment process, it is suggested to set up the Alignment Review tool before submitting transcripts for alignment. See more information on the transcript alignment review tool

Steps to Upload Alignment Files Using API

Step 1: Use a POST call to post your file

• • Use the endpoint: [POST] http://api.3playmedia.com/files 

Step 2: Choose upload method

• To upload a link, specify your link in the link attribute.
• To upload a full file, attach the file as the file attribute.

Step 3: Assign to a Folder (Optional)

• Use batch_id if you know the folder id. 
• User batch_name if assign/create a folder by name.
  • 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"

Step 4: Include Transcript for Alignment

• Add transcript_for_alignment with your plain text transcript.

Step 5: Include Required Properties

• apikey
• api_secret_key
• link or file for_alignment=1

Step 6: Optional Available Properties

• name
• video_id
• attribute1
• attribute2
• attribute3
• batch_id
• batch_name
• callback_url
• transcript_for_alignment={all the text here}
• language_id

Step 7: Handle Response

• A successful upload returns an integer value tied to the internal file_id. If not, check the error response and adjust your POST request.
• The following values may be specified for the language_id parameter (default is 1):

• • 1 = English (generic)
  • 2 = US English
  • 3 = GB English
  • 4 = French (generic)
  • 5 = FR French
  • 6 = CA French
  • 7 = German
  • 8 = Dutch
  • 11 = Spanish (generic)
  • 12 = SP Spanish
  • 13 = LA Spanish
  • 14 = Portuguese (generic)
  • 15 = PT Portuguese
  • 16 = BR Portuguese
  • 49 = AU English
  • 50 = Catalan

Tips and best practices

• Stranded Media Files: If a media file is uploaded without a matching transcript, it will be flagged. After 24 hours: a warning is sent to project admins. After 48 hours: the file is deleted, and admins are notified.
• Always submit plain text transcripts containing only the spoken content—no URLs, sound effects, or directions.
• Avoid background music or sound effects, especially at the beginning of the file, as they can disrupt alignment.
• For consistent results, review our Alignment Best Practices.
• If alignment fails, consider upgrading to Full Transcription. 

Next steps

• Monitor your 3Play project for file completion.

• Review alignment quality via the Alignment Review tool.

• Upgrade to full transcription if alignment accuracy is affected by music or background noise Upgrade Instructions.

Reminder: Turnaround time varies, typically within a few hours or by the next business day, depending on file duration and system volume.