Audio transcription

Request a transcript when you need the spoken words rather than a summary. Specify whether to preserve the original language, include repetitions, and mark words that cannot be heard clearly. Review the result against the recording before relying on exact wording.

Transcribe a local recording

Install perceptron>=0.4.0, set PERCEPTRON_API_KEY, and place a short WAV recording at ./recording.wav. This example asks for a verbatim transcript in the original language:

import os

from perceptron import Client, audio

client = Client(
    provider="perceptron",
    api_key=os.environ["PERCEPTRON_API_KEY"],
)
response = client.chat.completions.create(
    model="perceptron-mk1.5",
    messages=[{
        "role": "user",
        "content": [
            audio("recording.wav"),
            {"type": "text", "text": (
                "Transcribe the speech verbatim in its original language. "
                "Preserve spoken repetitions and do not summarize or translate. "
                "Mark words you cannot hear clearly as [unclear] instead of guessing. "
                "If there is no intelligible speech, say so. Return only the transcript."
            )},
        ],
    }],
    reasoning_effort="none",
    max_completion_tokens=4096,
)
choice = response.choices[0]
if choice.finish_reason != "stop" or choice.message.tool_calls:
    raise RuntimeError(f"Expected a completed transcript, got: {choice.finish_reason}")
print(choice.message.content or "")

The transcript is returned in choices[0].message.content. A length finish reason means the output budget was exhausted; treat that transcript as incomplete. A stop finish reason indicates completion, not verified transcription accuracy. The audio() helper detects the local recording’s format and sends it inline. For other supported encodings, remote recordings, or uploaded files, use the audio input forms.

Specify the transcript you need

Goal	Example instruction
Preserve spoken wording	“Transcribe verbatim, including repetitions. Mark unclear words as [unclear].”
Produce readable text	“Transcribe the speech with punctuation. Remove filler words without changing the meaning.”
Separate transcript and translation	“First transcribe in the original language, then provide an English translation under a separate heading.”
Label speaker changes	“Use Speaker 1, Speaker 2, and so on when voices can be distinguished. Mark uncertain speaker changes rather than guessing.”

These are prompt instructions, not guarantees of word accuracy or speaker separation. Speaker labels describe turns within the recording; they do not establish a person’s identity or a stable identity across recordings. Check labels and quotations against the audio when they matter to your application.

Budget for the full transcript

A recording can fit the audio input limit while its transcript exceeds the requested output budget. Allow enough completion tokens for the spoken text, within the model’s context and output limits. The example uses reasoning_effort="none" and a 4,096-token output budget; adjust that budget for your recording. For a longer recording, split the audio into shorter excerpts before sending requests and retain their start times in your application. If you overlap excerpts to preserve context around a boundary, check for duplicated transcript text when joining results. Audio over the per-item limit is rejected rather than automatically truncated. Use audio clipping to ask for an interval containing a phrase or audible event. A clip is a temporal annotation; it does not provide automatic word-by-word alignment for a transcript. Use audio Q&A when you only need a specific answer from the recording.

Get Started

Capabilities

Developer Guides

Scaling & deployment

Best practices

Transcribe a local recording

Specify the transcript you need

Budget for the full transcript

​Transcribe a local recording

​Specify the transcript you need

​Budget for the full transcript

Transcribe a local recording

Specify the transcript you need

Budget for the full transcript