Skip to main content

How to upload a recording for transcription

You can hand Sally a file that was recorded somewhere else and get a transcript and a summary back, exactly as for a recorded meeting. There are two ways in, depending on where the file lives.

Before you start

Read the Quickstart and Rate limits & fair usage first.

Quick navigation

  1. The file is reachable by URL
  2. You have the file yourself
  3. Formats, size and quota

1. The file is reachable by URL​

One call. Sally fetches the file server-side and starts transcription and summarization:

POST /v1.0/directories/{directoryId}/recordings/from-url

{ "url": "https://files.example.com/weekly.mp4", "name": "Weekly team meeting" }

The URL must use https, must not contain credentials, must point to a public host and must not redirect. Pass the final address. The call returns once the recording exists, transcription then runs in the background.

Reference: POST/v1.0/directories/{directoryId}/recordings/from-url

2. You have the file yourself​

  1. Request an upload. You get an uploadId, an uploadUrl and the requiredHeaders to use with it. The transcription quota is already checked here, so a rejection costs you nothing.
POST /v1.0/directories/{directoryId}/recordings/uploads

{ "fileName": "weekly.mp4", "mimeType": "video/mp4", "sizeBytes": 184320000 }
  1. Upload the file with PUT directly to uploadUrl, using the headers you received. This request does not go through the Sally API.
  2. Finalize the upload. Only now does the recording exist and transcription starts. Optionally pass languageCode, speakerCount or an appointmentId.
POST /v1.0/directories/{directoryId}/recordings/uploads/{uploadId}/finalize
Important

Skipping step 3 is the classic mistake. The file is stored, but no recording is created, so nothing shows up in Sally and nothing is transcribed.

3. Formats, size and quota​

Supported are video files (mp4, mkv, avi, mov, webm) and audio files (mp3, wav, flac, ogg, amr, m4a, opus, aac) up to 5 GB each. Transcription also falls under a fair-usage policy:

  • When the quota is used up, requesting an upload answers 429 with code set to FUP_LIMIT_EXCEEDED.
  • When too many transcriptions of your company account run at the same time, finalizing or a URL import answers 429 with code set to TOO_MANY_CONCURRENT_TRANSCRIPTIONS.
Recommendation

Handle these two codes separately from a plain rate limit. Waiting a moment helps with a rate limit and with concurrent transcriptions, but not with a used-up quota.

To find out when the transcript is ready, poll the recording or register a webhook.