SpeechToText

Transcribe audio

Inworld STT API reference: send a complete audio file in one request and get one transcription back.

POST/stt/v1/transcribe

cURL

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>"
    }
  }'

Python

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())

JavaScript

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);

cURL (raw audio)

# multipart/form-data: the transcribeConfig part first, then the audio file.
# No base64, so the request is about a third smaller.
curl --request POST \
  --url https://api.inworld.ai/stt/v1/transcribe \
  --header "Authorization: Basic $INWORLD_API_KEY" \
  --form 'transcribeConfig={"modelId":"inworld/inworld-stt-1","audioEncoding":"LINEAR16","language":"en-US","sampleRateHertz":16000,"numberOfChannels":1};type=application/json' \
  --form "file=@audio.wav"

Python (raw audio)

import json
import requests

url = "https://api.inworld.ai/stt/v1/transcribe"
api_key = "$INWORLD_API_KEY"

config = {
    "modelId": "inworld/inworld-stt-1",
    "audioEncoding": "LINEAR16",
    "language": "en-US",
    "sampleRateHertz": 16000,
    "numberOfChannels": 1,
}

with open("audio.wav", "rb") as f:
    # requests sends the parts in this order: config first, then the file.
    response = requests.post(
        url,
        headers={"Authorization": f"Basic {api_key}"},
        files=[
            ("transcribeConfig", (None, json.dumps(config), "application/json")),
            ("file", ("audio.wav", f, "audio/wav")),
        ],
    )

print(response.json())

</RequestExample>

Sending raw audio

Besides JSON with base64 audio, this endpoint accepts a multipart/form-data body: a transcribeConfig part holding the same config as JSON, then a file part holding the audio bytes as they are. Base64 makes a request about a third larger than the file, so multipart is the smaller upload. The response is the same either way.

Send transcribeConfig before file. The form is read as it arrives, so a config placed after the audio is refused.
The request, config and audio together, can be up to 16 MiB. For longer recordings use asynchronous transcription, which takes multipart uploads up to 512 MB.

200

{
  "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/json

transcribeConfigoneOfrequired

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.

MP4: The audio track of an MP4 video file. The video is discarded and only

the audio is transcribed.

This names a container rather than a codec, unlike the values above: an MP4 may carry AAC, AC-3, E-AC-3, ALAC, Opus, MP3 or PCM, and the codec is read from the file. .m4v and .mov are the same container and are covered by this value. Not supported for streaming transcription.

MXF: The audio track of an MXF file, the SMPTE container used for broadcast

delivery and by professional cameras. Audio is normally PCM. Not supported for streaming transcription.

WEBM: The audio track of a WebM file, which browsers produce when recording

through MediaRecorder. Carries Opus or Vorbis, so this names the container and the codec is read from the file. Not supported for streaming transcription.

Available options:AUDIO_ENCODING_UNSPECIFIEDAUTO_DETECTLINEAR16MP3OGG_OPUSFLACMP4MXFWEBM

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

Provider-specific inactivity setting. Not applied by inworld/inworld-stt-1; implement application idle-stop timers on the client.

endOfTurnConfidenceThresholdnumber

Confidence threshold for end-of-turn prediction. Higher values reduce false-positives. Range: [0.0, 1.0]. Default: 0.4. 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. Maximum 100 prompts per request. Allowed characters: letters and digits in any script, spaces, and the punctuation . , ' ( ) : ! ? ; - (straight apostrophes and hyphens only). Any other character (such as &, @, #, , curly quotes, or en/em dashes) rejects the entire request with INVALIDARGUMENT (code 3), naming the offending character. Short, targeted lists work best: the more prompts you send, the weaker the bias on each, and a long list is likely to be ignored.

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.

Response

200 - application/json

transcriptionobject

Represents the result of a speech-to-text transcription. May be an interim (partial) result or a final result depending on the is_final field.

Show child attributes

transcriptstring

Full transcribed text for this segment.

isFinalboolean

Indicates whether this is a finalized result or an interim (partial) result that may be updated as more audio is processed.

wordTimestampsobject[]

Per-word timing and confidence data. Only populated when includeWordTimestamps is enabled in the request config.

Show child attributes

wordstring

The transcribed word.

confidencenumber

Recognition confidence score for this word, ranging from 0.0 to 1.0. Not currently populated: the synchronous and streaming endpoints return 0, and asynchronous results omit the field.

startTimeMsinteger

Offset from the beginning of the audio to the start of this word, in milliseconds.

endTimeMsinteger

Offset from the beginning of the audio to the end of this word, in milliseconds.

speakerinteger

Speaker identifier for this word when diarization is enabled. Integers are assigned per stream in order of first appearance. May be absent on some words even when diarization is enabled — treat unlabeled words as unattributed. See the Speaker Diarization guide.

voiceProfileobject

Speaker characteristics returned when Voice Profile is enabled and analysis is available. Each category contains classification labels and confidence scores.

Show child attributes

ageobject[]

Show child attributes

labelstring

The predicted class name.

confidencenumber