SpeechToText
Transcribe audio
Send the whole audio in a single request, and receive a single transcription.
/stt/v1/transcribe<RequestExample>
curl --request POST \
--url https://api.inworld.ai/stt/v1/transcribe \
--header "Authorization: Basic $INWORLD_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"transcribeConfig": {
"modelId": "inworld/inworld-stt-1",
"audioEncoding": "LINEAR16",
"language": "en-US",
"sampleRateHertz": 16000,
"numberOfChannels": 1
},
"audioData": {
"content": "<YOUR_AUDIO>"
}
}'import requests
import base64
url = "https://api.inworld.ai/stt/v1/transcribe"
api_key = "$INWORLD_API_KEY"
with open("audio.wav", "rb") as f:
audio_base64 = base64.b64encode(f.read()).decode("utf-8")
response = requests.post(
url,
headers={
"Authorization": f"Basic {api_key}",
"Content-Type": "application/json",
},
json={
"transcribeConfig": {
"modelId": "inworld/inworld-stt-1",
"audioEncoding": "LINEAR16",
"language": "en-US",
"sampleRateHertz": 16000,
"numberOfChannels": 1,
},
"audioData": {
"content": audio_base64,
},
},
)
print(response.json())const fs = require("fs");
const apiKey = "$INWORLD_API_KEY";
const audioBase64 = fs.readFileSync("audio.wav").toString("base64");
const response = await fetch("https://api.inworld.ai/stt/v1/transcribe", {
method: "POST",
headers: {
"Authorization": `Basic ${apiKey}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
transcribeConfig: {
modelId: "inworld/inworld-stt-1",
audioEncoding: "LINEAR16",
language: "en-US",
sampleRateHertz: 16000,
numberOfChannels: 1,
},
audioData: {
content: audioBase64,
},
}),
});
const data = await response.json();
console.log(data);</RequestExample>
<ResponseExample>
{
"transcription": {
"transcript": "Hey, I just wanted to check in on the delivery status for my order.",
"isFinal": true,
"wordTimestamps": []
},
"usage": null
}</ResponseExample>
Authorizations
Authorizationstringrequired
Your authentication credentials. For Basic authentication, please populate Basic $INWORLD_API_KEY. You can create a key in one command with the Inworld CLI: inworld workspace add-key.
Body
application/jsontranscribeConfigobjectrequired
Configuration for transcribing audio. Contains model selection, audio format settings, and optional feature configurations. Model-specific configuration is optional — set inworldSttV1Config or omit it.
Show child attributes
modelIdstringrequired
The identifier of the model to use for transcription. Format: "{provider}/{model-name}".
Available models:
inworld/inworld-stt-1— Inworld first-party (Sync + WebSocket)
See STT Introduction for the full model catalogue.
audioEncodingenum<string>requireddefault: "AUDIO_ENCODING_UNSPECIFIED"
Supported audio encoding formats.
- AUDIOENCODINGUNSPECIFIED: Not specified. Will return [google.rpc.Code.INVALID_ARGUMENT].
- AUTO_DETECT: Automatically detect audio encoding from the audio header.
- LINEAR16: Uncompressed 16-bit signed little-endian samples (Linear PCM).
- MP3: MP3 audio. Compressed audio format.
Not supported for streaming transcription.
- OGG_OPUS: Opus encoded audio wrapped in an OGG container. Playable natively on Android
and in browsers (Chrome, Firefox). Higher quality than MP3 at similar bitrate. Not supported for streaming transcription.
- FLAC: FLAC encoded audio. Lossless audio format.
Not supported for streaming transcription.
Available options:AUDIO_ENCODING_UNSPECIFIEDAUTO_DETECTLINEAR16MP3OGG_OPUSFLAC
languagestring
Language hint in ISO 639 format (e.g., "en", "ja"). Biases the model toward the specified language during automatic language detection. BCP-47 codes (e.g., "en-US") are also accepted and converted to the base language code. The hint additionally constrains the output script for English, Chinese, Cantonese, Japanese, Korean, Russian, and Hindi (e.g. selecting en keeps output in Latin script). See Language Support for the full list of supported languages.
sampleRateHertzinteger
Sample rate of the audio data in Hertz. Required when the sample rate cannot be inferred from the audio header (e.g., raw PCM streams). If not set - default sample rate 16000 will be used.
numberOfChannelsinteger
Number of channels in the audio data. Required when the number of channels cannot be inferred from the audio header (e.g., raw PCM streams). If not set - default number of channels 1 will be used.
inactivityTimeoutSecondsinteger
Inactivity timeout in seconds. If the client is silent for this duration, the transcription will be stopped.
endOfTurnConfidenceThresholdnumber
Confidence threshold for end-of-turn prediction. Higher values reduce false-positives. Range: [0.0, 1.0]. Default: 0.5. Applies to streaming; see the Turn Detection guide.
promptsstring[]
Custom vocabulary / key terms. An array of context strings (names, jargon, acronyms) that bias the model toward recognizing these terms. This is a soft bias that helps with ambiguous or uncommon words; it is not a hard keyword lock and does not force exact output. Use letters, digits, spaces, and basic punctuation; other characters (such as #, /, @, or |) are rejected by the gateway with INVALID_ARGUMENT (code 3).
includeWordTimestampsboolean
If true, includes per-word timing information in the response.
enableSpeakerDiarizationboolean
Labels transcribed words with a per-stream speaker identifier. Applies to the WebSocket streaming endpoint. Experimental for inworld/inworld-stt-1 — speaker attribution quality is still improving and speakers may occasionally be misattributed. Set it together with includeWordTimestamps; speaker labels are returned on wordTimestamps[].speaker, and some words may arrive without a label (treat those as unattributed). See the Speaker Diarization guide.
voiceProfileConfigobject
Configuration for voice profile detection.
Show child attributes
enableVoiceProfilebooleanrequired
Enables voice profile feature for this request or stream.
topNinteger
Number of top labels from each class to return. Default: 10.
audioDataobjectrequired
Container for raw audio data bytes.
Show child attributes
contentstringrequired
The raw audio bytes in the encoding specified by TranscribeConfig.audio_encoding.