Speech-to-Text API: uploads and OpenAI compatibility
Speechall accepts local audio uploads and publicly reachable audio URLs through its speech-to-text API. Choose an endpoint based on how your application supplies audio. All paths below use the base URL https://api.speechall.com/v1 and require Authorization: Bearer YOUR_SPEECHALL_API_KEY.
Choose an upload method
| Method | Endpoint | Request body | Options |
|---|---|---|---|
| Direct upload | POST /transcribe | Raw audio bytes | Query parameters, including model and output_format |
| OpenAI-compatible transcription | POST /openai-compatible/audio/transcriptions | Multipart file upload | Form fields, including model and response_format |
| OpenAI-compatible translation | POST /openai-compatible/audio/translations | Multipart file upload | Form fields; translates supported audio into English |
| Remote file | POST /transcribe-remote | JSON with file_url | JSON properties |
Direct upload is convenient when your application already has an audio byte stream. Multipart upload fits existing OpenAI audio SDK integrations. Remote transcription lets Speechall fetch a file from an HTTP/S URL reachable by its servers. Latency depends on file transfer, model, provider, and recording length; compare your own workload before choosing a method for performance reasons.
See Getting Started for a direct upload example and the API reference for the complete request schemas. For live audio, use the separate WebSocket streaming guide.
Use an OpenAI SDK with Speechall
Set the OpenAI SDK’s base URL to https://api.speechall.com/v1/openai-compatible, supply a Speechall API key, and use a Speechall model ID such as openai.whisper-1. The SDK appends /audio/transcriptions; do not include that suffix in its base URL. This is an audio transcription compatibility endpoint, not an LLM chat API. Choose a supported Speechall model from the model catalog and check its available parameters before migrating.
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("audio.wav", "rb") as audio:
result = client.audio.transcriptions.create(
model="deepgram.nova-3",
file=audio,
response_format="text",
)
print(result) This example uses the third-party OpenAI Python SDK (pip install openai). Run it on your server with an API key stored in an environment variable. It illustrates the documented request contract; it is not a published benchmark or a guarantee of compatibility with every SDK version.
The API quickstart covers API keys, credits, model discovery, and raw file uploads. For microphone or live call audio, follow the WebSocket streaming guide with a streaming-capable model.
For a full migration checklist and a Node.js example, read Migrating the OpenAI transcription API to Speechall.
Models, options, and response formats
Request the current catalog before selecting a model:
curl "https://api.speechall.com/v1/speech-to-text-models"
-H "Authorization: Bearer $SPEECHALL_API_KEY" Use the returned id in provider.model form. A bare OpenAI model name such as whisper-1 is not the Speechall identifier. Check availability, supported languages, output support, and limits for your chosen model rather than assuming that all providers offer the same features.
The compatibility transcription schema accepts file, model, language, prompt, response_format, temperature, and timestamp_granularities[]. file and model are required. Use an ISO-639-1 language code such as en when specifying the input language. Optional prompts and other model-specific features depend on the selected model.
The documented response formats are json (the default), text, verbose_json, srt, and vtt. JSON includes a text property; plain text and subtitle formats return text bodies. For transcription timestamps, select verbose_json and request word, segment, or both through timestamp_granularities[], subject to model support. Check subtitle capabilities in the catalog before requesting SRT or VTT. For curl examples and how to check model support, see Subtitles (SRT and VTT).
Translation uses /audio/translations under the same compatibility base URL and outputs English. Select a translation-capable model; the translation schema accepts prompt, response_format, and temperature, but does not list language or timestamp_granularities[].
Audio formats and limits
The compatibility upload schema lists FLAC, MP3, MP4, MPEG, MPGA, M4A, OGG, WAV, and WebM. Send the actual file content as multipart data, not a filename string or URL. Let your SDK or multipart client set the Content-Type boundary.
There is no single upload-size or duration limit specified for every model. Inspect the catalog’s max_file_size_bytes and max_duration_seconds when provided. A missing or null value does not establish an unlimited allowance. If the limit is unclear for your workload, contact support before sending large files. Do not interpret example values in the OpenAPI document as universal limits.
Remote audio and private storage
POST /transcribe-remote requires a URL that Speechall’s servers can fetch. Check accessibility and URL lifetime before submitting a request. Do not assume an internal VPC address, browser login session, or application-specific authentication header will be available to the fetcher. Contact support to discuss private-storage requirements; the public schema does not establish a private-network integration.
Frequently asked questions
Can I keep using the OpenAI Python or JavaScript SDK?
The compatibility endpoint uses the OpenAI audio request structure. Update the key, base URL, and model ID, then verify the response formats and optional fields your application uses. See the Python and TypeScript migration tutorial.
Is OpenAI compatibility the same as feature parity?
Compatibility describes the documented audio endpoints and request formats. Provider features vary, and parameters outside the published schema should not be assumed to work. Use the API reference and model catalog to review your requirements.
Can I send a remote URL in the multipart file field?
The multipart file field requires audio content. Use /transcribe-remote with file_url for a reachable remote file.
Where do I create an API key?
Create a key in the Speechall console, keep it on your server, and follow the Getting Started guide. You can also explore the official TypeScript SDK.