Migrate an OpenAI Transcription Client to Speechall

November 3, 2026

Migrate an OpenAI transcription integration to Speechall

If your application already calls client.audio.transcriptions.create, Speechall’s OpenAI-compatible endpoint gives you a way to reuse that upload flow while selecting models through Speechall. The migration starts with three configuration changes: a Speechall API key, a compatibility base URL, and a model identifier in provider.model form.

This tutorial covers recorded audio uploads in Python and TypeScript. The examples follow Speechall’s published OpenAPI schema; they are illustrative integration examples, not measured transcription results or a claim that every OpenAI SDK feature works unchanged.

What changes in the request?

The SDK adds /audio/transcriptions to the base URL. Using only https://api.speechall.com/v1 would miss the compatibility prefix. Including /audio/transcriptions in the base URL would duplicate the SDK’s resource path.

Model names also need attention: use openai.whisper-1, rather than the bare whisper-1 name from a direct OpenAI integration. Other providers have their own Speechall model IDs. Reusing an SDK does not mean all models offer identical languages, timestamps, prompts, or subtitle output.

Check the current model catalog

Before migrating production traffic, retrieve the catalog using your Speechall key:

export SPEECHALL_API_KEY="your-speechall-api-key"
curl "https://api.speechall.com/v1/speech-to-text-models" 
  -H "Authorization: Bearer $SPEECHALL_API_KEY"

Choose a returned id, check is_available, and inspect the model’s supported languages and relevant capabilities. The model schema includes supports_srt, supports_vtt, max_file_size_bytes, and max_duration_seconds. Limits can vary by model or provider; null or missing limits do not imply unlimited uploads. Example limits embedded in a schema are not service-wide guarantees.

The compatibility upload schema lists FLAC, MP3, MP4, MPEG, MPGA, M4A, OGG, WAV, and WebM. Check that both your container and the selected model suit your recording. For an unclear limit or format requirement, ask support before processing a large batch.

Python: retain the audio transcription call

Install the OpenAI Python SDK in your application environment:

pip install openai

Keep the key in an environment variable and configure a client on your server:

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("recording.wav", "rb") as audio:
    transcript = client.audio.transcriptions.create(
        model="openai.whisper-1",
        file=audio,
        response_format="json",
    )

print(transcript.text)

The file handle sends the audio contents. The default JSON response has a text property, which makes it a useful first migration target. Add optional parameters only after confirming that the chosen model supports them. If you know the input language, the transcription schema accepts an ISO-639-1 code such as language="en".

TypeScript: upload a file from Node.js

Install the OpenAI JavaScript SDK in your Node.js project:

npm install openai

Use this code in a server-side TypeScript entry point configured for your project’s module system:

import fs from 'node:fs';
import OpenAI from 'openai';

const apiKey = process.env.SPEECHALL_API_KEY;
if (!apiKey) {
    throw new Error('Set SPEECHALL_API_KEY before running this script');
}

const client = new OpenAI({
    apiKey,
    baseURL: 'https://api.speechall.com/v1/openai-compatible',
});

async function main() {
    const transcript = await client.audio.transcriptions.create({
        model: 'openai.whisper-1',
        file: fs.createReadStream('recording.wav'),
        response_format: 'json',
    });

    console.log(transcript.text);
}

main().catch((error: unknown) => {
    console.error(error);
    process.exitCode = 1;
});

The JavaScript SDK spells the option baseURL; the Python SDK uses base_url. Keep the API key on your server. A browser bundle would expose it to users. If you prefer a Speechall-specific client, see the official TypeScript SDK guide.

Verify the HTTP contract with curl

A multipart request makes the destination and field names explicit:

curl "https://api.speechall.com/v1/openai-compatible/audio/transcriptions" 
  -H "Authorization: Bearer $SPEECHALL_API_KEY" 
  -F "[email protected]" 
  -F "model=openai.whisper-1" 
  -F "response_format=json"

Let curl or your SDK supply the multipart content type and boundary. Setting a generic Content-Type: multipart/form-data header yourself can omit the boundary required to parse the upload.

The native Speechall /transcribe endpoint uses a different contract: raw audio in the body, with options such as model and output_format in the query string. Do not copy that endpoint’s parameter placement into a compatibility request. The speech-to-text documentation compares upload methods, including /transcribe-remote for reachable audio URLs.

Preserve the response features your application needs

Start with a small representative recording and response_format="json". Then review each feature your existing integration uses:

• Plain text or subtitles: the schema lists text, srt, and vtt alongside json and verbose_json. Treat text and subtitle outputs as text bodies, and check the model’s subtitle support.
• Timestamps: transcription accepts timestamp_granularities[] containing word, segment, or both, with response_format="verbose_json". Confirm support and inspect returned fields before relying on them downstream.
• Prompting and temperature: both are documented optional fields, but their usefulness and support depend on the selected model. The transcription prompt should match the audio language.
• Translation: client.audio.translations.create uses the sibling /audio/translations endpoint and translates supported audio into English. Select a translation-capable model. Its schema does not list transcription’s language or timestamp_granularities[] fields.
• Live audio: multipart transcription is a recorded-file workflow. Follow the separate WebSocket streaming guide for streaming integration.

The published compatibility request schemas reject additional properties in their contract. Do not assume newer OpenAI-specific parameters, events, or response fields are available just because your installed SDK exposes them.

Validate before moving production traffic

Use recordings that cover your actual languages, noise conditions, audio duration, and specialist vocabulary. Check transcript quality, punctuation, required timestamps, subtitle formatting, and total request latency. Compare models on the same recordings; this tutorial does not establish a universal accuracy or speed ranking.

Review failures as well as successful transcripts. The endpoint documents authentication, validation, rate-limit, and server error responses in the API reference. Verify your SDK’s behavior for those responses. Use bounded retries where appropriate, and account for the possibility that retrying an upload submits it again; the published request schema does not define an idempotency field.

Record the model ID and SDK version you validate. When changing providers later, repeat the checks for features your application depends on. A shared request interface reduces integration work, while model selection still requires testing with your audio.

Frequently asked questions

Can I switch to Speechall by changing only the API key?

Change the key, the SDK base URL, and the model ID. Use https://api.speechall.com/v1/openai-compatible and a Speechall identifier such as openai.whisper-1, then verify any optional fields and response handling.

Is there a universal 25 MB upload limit?

The schema does not define one universal limit for every Speechall model. Check the catalog’s max_file_size_bytes and max_duration_seconds for the model you choose. Ask support when a limit is absent or unclear.

Can I use any OpenAI speech model name?

Use an available model ID returned by Speechall’s catalog. Do not assume a model available through OpenAI’s API is also available through Speechall, or that its bare model name is accepted.

Does the compatibility endpoint support diarization?

The published multipart transcription request schema does not list a diarization parameter. For speaker labeling requirements, inspect the model catalog and the native endpoint’s documented options rather than assuming an OpenAI SDK option will enable it.

Where should I start?

Create a Speechall API key, follow the Getting Started guide, and migrate one representative recording using the JSON examples above. Check the model catalog before scaling your workload.