Accounts & Credentials

Create Salad Account

To start, visit https://portal.salad.com/ to log in or create a free account.

Create Salad Account

Create Salad Organization

Next, create a new organization or select an existing one you’d like to use for transcription. Click on Switch to this Organization for the org you want to use.

Create Salad Organization

Get Transcription API URL

Then, click on Inference Endpoints in the left-hand nav and open up the Transcription API.

Access Salad Transcription API

Copy your Transcription API URL

Copy Transcription API URL

Authentication

Copy your Salad API key from your account here.

Token Instructions

API Reference

Example cURL Post Transcript

curl -X POST https://api.salad.com/api/public/organizations/{my-organization}/inference-endpoints/transcribe/jobs \
   -H "Salad-Api-Key: {your-api-key}" \
   -H "Content-Type: application/json" \
   -d '{
      "input": {
         "url": "https://example.com/path/to/file.mp3",
         "language_code": "en",
         "word_level_timestamps": false,
         "diarization": false,
         "srt": false
      },
	  "metadata": {
      "my-job-id": 1234
      }
   }'

Example cURL Get Transcript

curl https://api.salad.com/api/public/organizations/{my-organization}/inference-endpoints/transcribe/jobs/54e84442-3576-45ca-904c-a1d90bc77baf \
   -H "Salad-Api-Key: {your-api-key}"

Step1 | Configure Header

Configure you header to include your unique Salad API URL which can be found above as the variable “API URL”. Also include your unique Salad API key which can be found here as the variable “Salad-Api-Key”.

Step 2 | Set Input Parameters

Update the JSON input parameters to customize your transcription output.

“url”

We recommend using a file service like S3 that offers secure presigned URLs. It should look like this (https://bucketname.s3.us-east-2.amazonaws.com/filename.mp4?response-content-disposition=inline&X-Amz-Security-Token=IQoJb3JpZ2). You can’t use YouTube videos, Google Drive, or other file-sharing services.

Send media in any of these formats.

Audio: AIFF, FLAC, M4A, MP3, WAV Video: MKV, MOV, WEBM, WMA

“language_code”

Transcription is available in 97 languages. We automatically identify the source language. We don’t support multiple-language media files at this time.

“diarization”

Set to “true” for speaker separation and identification. If you don’t require it, set it to “false”.

Diarization requires the language_code to be defined. By default, it is set to “en” (English).

You can also diarize in “fr” (French), “de” (German), “es” (Spanish), “it” (Italian), “ja” (Japanese), “zh” (Chinese), “nl” (Dutch), “uk” (Ukrainian), “pt” (Portuguese), “ar” (Arabic), “cs” (Czech), “ru” (Russian), “pl” (Polish), “hu” (Hungarian), “fi” (Finnish), “fa” (Persian), “el” (Greek), “tr” (Turkish), “da” (Danish), “he” (Hebrew), “vi” (Vietnamese), “ko” (Korean), “ur” (Urdu), “te” (Telugu), “hi” (Hindi), “ca” (Catalan), “ml” (Malayalam).

“word_level_timestamps”

Set to “true” to get word-level timestamps. Set to “false”, to get only sentence-level timestamps.

“srt”

Set to “true” to generate a .srt output for caption and subtitles. If you don’t require it, set it to “false”.

“my-job-id”

If you need an identifier from your system you can the job id as desired.

Step 3 | Make Post Request

Make your POST transcript request. If successful, you will recieve a confirmation response that will include the job “id” *(ex: 00-681d01e03cec5f7122952100b66f2330-aa5b353301b6bc50-01).

Step 4 | Make Get Request

Make your GET transcript request. If successful, you will receive a JSON transcript output that will include the inputs you requested.

Example Transcript Output
{
  "id": "54e84442-3576-45ca-904c-a1d90bc77baf",
  "input": {
    "url": "https://example.com/path/to/file.mp3",
    "language_code": "en",
    "word_level_timestamps": true,
    "diarization": true,
    "srt": true
  },
  "metadata": {
    "my-job-id": 1234
  },
  "status": "succeeded",
  "events": [
    {
      "action": "created",
      "time": "2024-05-15T23:49:37.9946816+00:00"
    },
    {
      "action": "started",
      "time": "2024-05-15T23:50:23.0483322+00:00"
    },
    {
      "action": "succeeded",
      "time": "2024-05-15T23:50:23.4688229+00:00"
    }
  ],
  "output": {
    "segments": [
      {
        "start": 19.2,
        "end": 19.903,
        "text": "Thank you.",
        "words": [
          {
            "word": "Thank",
            "start": 19.662,
            "end": 19.783,
            "score": 0.232
          },
          {
            "word": "you.",
            "start": 19.803,
            "end": 19.903,
            "score": 0.545
          }
        ],
        "speaker": "SPEAKER_00"
      }
    ],
    "word_segments": [
      {
        "word": "Thank",
        "start": 19.662,
        "end": 19.783,
        "score": 0.232,
        "speaker": "SPEAKER_00"
      },
      {
        "word": "you.",
        "start": 19.803,
        "end": 19.903,
        "score": 0.545,
        "speaker": "SPEAKER_00"
      }
    ],
    "srt_content": "1
00:00:19,2 --> 00:00:22,233
Because when we change the dialogue, we can change our world.

",
    "duration": 142.7795,
    "processing_time": 51.17370915412903
  },
  "create_time": "2024-05-15T23:49:37.9946816+00:00",
  "update_time": "2024-05-15T23:50:23.4688229+00:00"
}

“status”

If your transcription request is “pending”, it has not yet been picked up for processing.

“created” the transcription job is now in our queue to be processed.

“running” the transcription is processing.

“succeeded” the transcript is ready.

“failed” the transcript was not created. We will automatically re-try the transcription process until it fails three times. If we are unable to transcribe your media, you will get a 200 error with one of the following messages. Send us a support request at support@salad.com if this happens.

If for some reason we had an issue with the file you sent, you will get a mesage in the result: *File size is more than 3GB *File can not be downloaded or duration is missing. Please check your file and try again. *File duration is more than 2.5 hours

Transcription Automation

In the coming weeks, our transcription service will be enhanced with webhook functionality, allowing you to receive notifications when your transcription jobs are completed. Until then, you can use the following Python code snippet to automate the process of sending requests and retrieving transcription results.

Pass 1: Submitting Audio Files for Transcription

This part of the script submits audio files for transcription and collects job IDs. The job IDs are used in the second pass to check the status and retrieve the results.

import requests
import json
# Set the organization name, url, and API key
organization_name = "your_organization_name"
url = f"https://api.salad.com/api/public/organizations/{organization_name}/inference-endpoints/transcribe/jobs"
salad_key = "your_salad_key"
language_code = "en"
# Add your audio links here 
list_of_audio_files = [
    "audio_url",
    "audio_url",
    "audio_url",
]
# If you want to pull links from a file, you can use the following code
# with open('audio_links.txt', 'r') as f:
#     list_of_audio_files = f.readlines()
# Placeholder for job_ids
list_of_job_ids = []
headers = {
    "Salad-Api-Key": salad_key,
    "Content-Type": "application/json",
    "accept": "application/json",
}
# Pass 1: Submit audio files for transcription
# Loop through the list of audio files and construct body of each request
for audio_file in list_of_audio_files:
    data = {
        "input": {
            "url": audio_file,
            "language_code": language_code,
            "word_level_timestamps": True,
            "diarization": True,
            "srt": True,
        }
    }
    # Send the request
    response = requests.post(url, headers=headers, json=data)
    # Pull job id from response. And save it to a list or a file
    job_id = response.json()["id"]
    list_of_job_ids.append(job_id)
    #save job_ids to a file if needed (uncomment the code below)
    # job_id_str = f'"{job_id}",'
    # # Open a file and write the job_id to it
    # with open('queue_test.txt', 'a') as f:
    #     f.write(job_id_str + '\n')

Pass 2: Checking Job Status and Retrieving Results

This part of the script checks the status of each transcription job periodically and retrieves the results once the transcription is completed.

    # Pass 2. Loop though the job_ids and get the results
    # If you use both passes in the same script, just continue. 
    # If you use scripts separatly you need to set up connection again 
    # and initialize the list of job ids : 
    # Uncomment the code below if you need to 
    # import requests
    # import json
    # Set the organization name, url, and API key
    # organization_name = "your_organization_name"
    # url = f"https://api.salad.com/api/public/organizations/{organization_name}/inference-endpoints/transcribe/jobs"
    # salad_key = "your_salad_key"
    # language_code = "en"
    # headers = {
    #     "Salad-Api-Key": salad_key,
    #     "Content-Type": "application/json",
    #     "accept": "application/json",
    # }
    # Pull list from a file:
    # with open('queue_test.txt', 'r') as f:
    #     list_of_job_ids = f.readlines()
    # or initialize the list manually
    # list_of_job_ids = ["job_id1", "job_id2", "job_id3", "job_id4"]
import time
# Loop though the job_ids and get the results
while len(list_of_job_ids) > 0:
    for job in list_of_job_ids:
        response_url = f"https://api.salad.com/api/public/organizations/salad/inference-endpoints/transcribe/jobs/{job}"
        response = requests.get(response_url, headers=headers)
        if response.json()['status']  'running' or response.json()['status']  'pending':
            print(f"Job {job} is still {response.json()['status']}, waiting for retry...")
            # wait for 30 seconds and retry
            time.sleep(30) 
            continue
        if response.json()['status']  'succeded':
            #save the response to a file
            with open(f'result_{job}.json', 'w', encoding='utf-8') as f:
                json.dump(response.json(), f, ensure_ascii=False)  
            #remove the job_id from the list
            list_of_job_ids.remove(job)
        else:
            print(f"Job {job} failed, waiting for retry...")
            # wait for 30 seconds and retry
            time.sleep(30)
            continue