Quickstart

How to transcribe pre-recorded audio with Gladia’s speech-to-text (STT) API

Using our SDKs

The SDK simplifies pre-recorded speech-to-text by abstracting upload, job creation, and result retrieval. Designed for developers, it offers:

• A transcribe() for an end-to-end flow
• Individual steps when you need control over each step.

Install the SDK

JavaScript

npm install @gladiaio/sdk

Transcribe in one call

End-to-end transcription — from upload to result in one call.

Pass in a local file, binary data, or a remote URL — and let the method handle the rest.

Python

from gladiaio_sdk import GladiaClient

gladia_client = GladiaClient(api_key="YOUR_GLADIA_API_KEY").prerecorded()

transcription = gladia_client.transcribe("YOUR_AUDIO_URL_OR_LOCAL_PATH")

With customizable features:

Python

from gladiaio_sdk import GladiaClient

gladia_client = GladiaClient(api_key="YOUR_GLADIA_API_KEY").prerecorded()

transcription = gladia_client.transcribe(
    "YOUR_AUDIO_URL_OR_LOCAL_PATH",
    {
        "language_config": {
            "languages": ["en", "fr"],
            "code_switching": True,
        },
        "custom_vocabulary": True,
        "custom_vocabulary_config": {
            "vocabulary": ["Gladia", "Solaria", "Salesforce"],
        },
    },
)

Want to go further? See Audio Intelligence for add-ons like:

• Speaker diarization: separate the speakers across the conversation
• Translation: translate the transcript into one of our 100 target languages.
• PII redaction: detect and anonymize sensitive entities (ex: GDPR-related)
• Sentiment analysis: extract the main sentiment and up to 25 emotion

Individual steps

The building blocks behind transcribe() — upload audio, create a job, then retrieve the result when you need finer control over the flow.

Upload your audio

Upload a local file and pass the returned audio_url to the next step.

Python

from gladiaio_sdk import GladiaClient

gladia_client = GladiaClient(api_key="YOUR_GLADIA_API_KEY").prerecorded()

upload_response = gladia_client.upload_file("YOUR_LOCAL_PATH")

Example response:

{
  "audio_url": "https://api.gladia.io/file/636c70f6-92c1-4026-a8b6-0dfe3ecf826f",
  "audio_metadata": {
    "id": "636c70f6-92c1-4026-a8b6-0dfe3ecf826f",
    "filename": "your_audio_file.mp3",
    "extension": "mp3",
    "size": 99515383,
    "audio_duration": 4146.468542,
    "number_of_channels": 2
  }
}

Create a transcription job

Pass the audio_url from the previous step along with your transcription options.

Python

from gladiaio_sdk import GladiaClient

gladia_client = GladiaClient(api_key="YOUR_GLADIA_API_KEY").prerecorded()

job = gladia_client.create(
    {
    "audio_url": "YOUR_AUDIO_URL",
    "language_config": {
    "languages": ["en", "fr"],
    "code_switching": True,
  },
  "custom_vocabulary": True,
  "custom_vocabulary_config": {
    "vocabulary": ["Gladia", "Solaria", "Salesforce"],
      },
    }
)

Get the transcription result

You can get your transcription results in 3 different ways:

Polling

Python

from gladiaio_sdk import GladiaClient

gladia_client = GladiaClient(api_key="YOUR_GLADIA_API_KEY").prerecorded()

# Use job.id from gladia_client.create(...)
result = gladia_client.poll("YOUR_TRANSCRIPTION_JOB_ID")

print(result.result.transcription.full_transcript)

You can use create_and_poll() in Python or createAndPollUntyped() in JavaScript to create and poll in one call with the same job payload.

The methods implemented in the sdk are automatically polling until success or errors. To get the result with the cURL, you’ll just have to GET continuously on the given result_url until the status of your transcription is done.

You can get more information on the different transcriptions status by checking directly the API Reference.

Webhook

You can configure webhooks at https://app.gladia.io/webhooks to be notified when your transcriptions are done.

Once a transcription is done, a POST request will be made to the endpoint you configured. The request body is a JSON object containing the transcription id that you can use to retrieve your result with our API.
For the full body definition, check our API definition.

Callback URL

Callback are HTTP calls that you can use to get notified when your transcripts are ready.

Instead of polling and keeping your server busy and maintaining work, you can use the callback feature to receive the result to a specified endpoint:

{
  "audio_url": "YOUR_AUDIO_URL",
  "callback": true,
  "callback_config": {
    "url": "https://yourserverurl.com/your/callback/endpoint/",
    "method": "POST"
  }
}

Once the transcription is done, a request will be made to the url you provided in callback_config.url using the HTTP method you provided in callback_config.method. Allowed methods are POST and PUT with the default being POST.

The request body is a JSON object containing the transcription id and an event property that tells you if it’s a success or an error.

For file size, duration, and concurrency limits, see Supported files & duration and Concurrency and rate limits.

Using the API

Individual steps

Upload audio, create a transcription job, then poll until the job is done (or use webhooks or a callback URL).

Upload your audio

Call the upload endpoint with multipart form data. Use the returned audio_url when creating a transcription job.

cURL

curl --request POST \
  --url https://api.gladia.io/v2/upload \
  --header 'Content-Type: multipart/form-data' \
  --header 'x-gladia-key: YOUR_GLADIA_API_KEY' \
  --form audio=@/path/to/your/audio/your_audio_file.mp3

Example response:

{
  "audio_url": "https://api.gladia.io/file/636c70f6-92c1-4026-a8b6-0dfe3ecf826f",
  "audio_metadata": {
    "id": "636c70f6-92c1-4026-a8b6-0dfe3ecf826f",
    "filename": "your_audio_file.mp3",
    "extension": "mp3",
    "size": 99515383,
    "audio_duration": 4146.468542,
    "number_of_channels": 2
  }
}

Create a transcription job

POST to /v2/pre-recorded with your audio_url and options.

JavaScript

const response = await fetch("https://api.gladia.io/v2/pre-recorded", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-gladia-key": "<YOUR_GLADIA_API_KEY>",
  },
  body: JSON.stringify({
    audio_url: "YOUR_AUDIO_URL",
    language_config: {
      languages: [],
      code_switching: false,
    },
    diarization: true,
    diarization_config: {
      number_of_speakers: 3,
      min_speakers: 1,
      max_speakers: 5,
    },
    translation: true,
    translation_config: {
      model: "base",
      target_languages: ["fr", "en"],
      context_adaptation: true,
      context: "Business meeting discussing quarterly results",
      informal: false,
    },
    subtitles: true,
    subtitles_config: {
      formats: ["srt", "vtt"],
    },
  }),
});
if (!response.ok) {
  console.error(
    `${response.status}: ${(await response.text()) || response.statusText}`
  );
  process.exit(response.status);
}

const { id, result_url } = await response.json();

Poll for the transcription result

Poll GET /v2/pre-recorded/:id (or the result_url from the create response) until the job status is done.

JavaScript

const response = await fetch(
  `https://api.gladia.io/v2/pre-recorded/${jobId}`,
  {
    method: "GET",
    headers: {
      "x-gladia-key": "<YOUR_GLADIA_API_KEY>",
    },
  }
);
if (!response.ok) {
  console.error(
    `${response.status}: ${(await response.text()) || response.statusText}`
  );
  return;
}

const result = await response.json();
console.log(result);

Instead of polling, configure webhooks or set callback and callback_config on the job — see the init reference. The Using our SDKs tab also documents polling helpers, webhooks, and callbacks together.

Want to know more about a specific feature? Check out our Features chapter for more details.

Full code sample

You can find complete code samples in our Github repository: