Generate SRT and VTT subtitles with the Speechall API

To get a subtitle file, send your audio to POST https://api.speechall.com/v1/transcribe with output_format=srt (SubRip) or output_format=vtt (WebVTT). The response body is the subtitle file as plain text, so you can write it straight to disk. There is no JSON to convert first.

Subtitle output depends on the model. Some models support SRT, VTT, both or neither. The same request works across providers: change the model value and keep everything else.

Models that return SRT or VTT

Models with at least one subtitle format are listed first.

Request an SRT file with curl

The native /transcribe endpoint takes the raw audio bytes as the request body and the options as query parameters. Subtitles are selected with output_format.

curl -X POST "https://api.speechall.com/v1/transcribe?model=deepgram.nova-3&language=en&output_format=srt" 
  -H "Authorization: Bearer $SPEECHALL_API_KEY" 
  -H "Content-Type: audio/wav" 
  --data-binary @interview.wav 
  -o interview.srt

The saved file is standard SubRip: numbered cues, each with a start and end time and the text spoken in that interval. For example (illustrative text, not output from a specific model):

1
00:00:00,000 --> 00:00:03,200
Thanks for joining. Let's start with your background.

2
00:00:03,600 --> 00:00:07,900
Sure. I've worked on speech recognition for about six years.

-o interview.srt saves the response body. Open the file to check it. If the request fails, the body is a JSON error message instead of subtitles, so check the HTTP status (for example with curl --fail-with-body) before you use the file. Set Content-Type to match your audio (audio/mpeg for MP3, audio/flac for FLAC). The model ID deepgram.nova-3 only illustrates the provider.model format; confirm that your chosen model supports SRT first (see below).

Request a VTT file

Change output_format to vtt and the file extension to .vtt. Everything else stays the same.

curl -X POST "https://api.speechall.com/v1/transcribe?model=deepgram.nova-3&language=en&output_format=vtt" 
  -H "Authorization: Bearer $SPEECHALL_API_KEY" 
  -H "Content-Type: audio/wav" 
  --data-binary @interview.wav 
  -o interview.vtt

SRT and VTT are separate capabilities in the catalog. A model can support one and not the other.

Videos

The native endpoint accepts audio (audio/*). The OpenAI-compatible endpoint lists MP4 and WebM among its accepted upload formats, and the Speechall CLI accepts a video file such as webinar.mp4 directly. If you call /transcribe with a video file and want to send only the audio track, you can extract it first. This step is optional preprocessing and not a Speechall requirement:

# Optional: extract a mono 16 kHz WAV audio track with ffmpeg
ffmpeg -i video.mp4 -vn -ac 1 -ar 16000 audio.wav

Then send audio.wav as in the examples above.

Use the OpenAI SDK

The OpenAI-compatible endpoint uses response_format instead of output_format, and accepts srt and vtt there. Point the OpenAI Python SDK (pip install openai) at Speechall:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["SPEECHALL_API_KEY"],
    base_url="https://api.speechall.com/v1/openai-compatible",
)

with open("interview.wav", "rb") as audio:
    subtitles = client.audio.transcriptions.create(
        model="deepgram.nova-3",
        file=audio,
        response_format="srt",
    )

with open("interview.srt", "w", encoding="utf-8") as out:
    out.write(subtitles)

For srt, vtt and text the OpenAI Python SDK returns the body as a string. See Speech-to-Text for the base URL, model IDs and supported fields. The native endpoint’s output_format parameter and this endpoint’s response_format parameter are different names for the same choice, so do not mix them.

Check which models support subtitles

The table above is read from the live catalog. On the models page, use the SRT Support and VTT Support filters, or read the Subtitle Formats column. Each model’s own page shows whether SRT and VTT are supported.

In code, GET /v1/speech-to-text-models returns the catalog as JSON. Every model entry has the boolean fields supports_srt and supports_vtt. This example lists the IDs of models that support SRT with jq:

curl -s "https://api.speechall.com/v1/speech-to-text-models" 
  -H "Authorization: Bearer $SPEECHALL_API_KEY" 
  | jq -r '.[] | select(.supports_srt) | .id'

Use select(.supports_vtt) for VTT. The catalog changes over time, so query it instead of copying a model list.

Switch providers by changing the model ID

The request contains no provider-specific fields for subtitles. To compare how two providers handle the same audio, run the same command twice with different model values:

for MODEL in deepgram.nova-3 openai.whisper-1; do
  curl -X POST "https://api.speechall.com/v1/transcribe?model=$MODEL&language=en&output_format=srt" 
    -H "Authorization: Bearer $SPEECHALL_API_KEY" 
    -H "Content-Type: audio/wav" 
    --data-binary @interview.wav 
    -o "interview.$MODEL.srt"
done

Run this only with models whose catalog entry shows SRT support. Cue timing and line breaks come from the selected model and provider, so review the output on your own recordings before you pick one. Provider-specific options such as diarization or custom vocabulary vary by model and do not carry over automatically.

Create subtitles from the command line

The Speechall CLI writes the transcript to standard output, so redirect it to a file:

speechall webinar.mp4 --output-format srt > webinar.srt
speechall webinar.mp4 --output-format vtt > webinar.vtt

Next steps

• Speech-to-Text: upload methods, OpenAI SDK usage and audio formats.
• Model catalog: filter by SRT and VTT support.
• Speechall CLI: generate subtitle files from a terminal.
• Getting Started: create an API key and send your first request.