transcribe

Transcribe an audio or video file to VTT, SRT, plain text, or verbose JSON via OpenAI, an OpenAI-compatible endpoint, or Azure OpenAI.

Parameters

The audio file is read from disk before it is uploaded, capped at IRONFLOW_MAX_AUDIO_BYTES (default 25,000,000 bytes / 25 MB). A file over the cap fails the step before any network request is made; see CLI_REFERENCE.md for the environment variable.

Formats

format	Provider response_format sent	Output value
"vtt" (default)	vtt	Raw WebVTT text
"srt"	srt	Raw SubRip text
"text"	text	Raw plain text
"json"	verbose_json	Parsed JSON object

format = "json" does not request the provider's bare json mode — it requests verbose_json. The returned value is therefore a full object that typically includes text, segments (per-segment timing), duration, and the detected language, not just a transcript string. The exact fields present depend on what the provider returns; IronFlow parses the body as JSON and passes it through unchanged.

The requested format is always echoed back on {output_key}_format using its own label ("vtt", "srt", "text", or "json") — {output_key}_format reads "json" even though the wire request used verbose_json.

Environment Variable Fallbacks

Config Key	Environment Variable	Provider
api_key	OPENAI_API_KEY	openai / openai_compatible
base_url	OPENAI_BASE_URL	openai / openai_compatible
api_key	AZURE_OPENAI_API_KEY	azure
base_url	AZURE_OPENAI_ENDPOINT	azure
api_version	AZURE_OPENAI_API_VERSION	azure

api_key and base_url are read through a config-value-then-environment-variable fallback for every provider; azure additionally requires api_version through the same pattern. model, language, and prompt have no environment-variable fallback — they are config-only (with ${ctx.key} interpolation) to keep the environment contract limited to credentials and endpoints.

Azure

For provider = "azure", model is not a model identifier — it is the deployment name, and it is placed directly in the request URL path:

{base_url}/openai/deployments/{model}/audio/transcriptions?api-version={api_version}

Because Azure selects the model through the URL, the model field is also omitted from the uploaded form body for this provider (some deployments reject a redundant model field). Always set model explicitly to your deployment name when using Azure — the "whisper-1" default is very unlikely to match a real deployment name.

Azure authenticates with an api-key header instead of the Authorization: Bearer header used by openai/openai_compatible; this node handles that automatically based on provider.

Context Output

With the default output_key of "transcript", the keys are transcript, transcript_format, transcript_model, transcript_success, and — only when output_file is set — transcript_path.

Key	Type	Description
{output_key}	string or object	The transcript. For vtt/srt/text, the raw response body string. For json, the parsed verbose-JSON object (see Formats).
{output_key}_format	string	The requested format label: "vtt", "srt", "text", or "json".
{output_key}_model	string	The model value used for the request.
{output_key}_success	boolean	Always true. Any failure (missing credentials, transport error, non-2xx response, empty body, unparseable JSON) returns a node error instead.
{output_key}_path	string	Only present when output_file is set. The path the raw response body was written to.

Errors from this node never contain the API key: the provider's raw error text is scanned for the exact key value sent on the request and any occurrence is replaced with [REDACTED], in addition to the shared pattern-based credential redaction applied to transport and parse errors.

Examples

OpenAI, plain text

flow:step("transcribe", nodes.transcribe({
    path = "${ctx.audio_path}",
    format = "text",
    output_key = "transcript"
}))

flow:step("log_result", nodes.log({
    message = "Transcript: ${ctx.transcript}"
})):depends_on("transcribe")

Azure OpenAI

flow:step("transcribe", nodes.transcribe({
    provider = "azure",
    path = "${ctx.audio_path}",
    model = "my-whisper-deployment", -- deployment name, not a model ID
    api_version = "2024-06-01",
    output_key = "transcript"
}))

Verbose JSON (segments, duration, detected language)

flow:step("transcribe", nodes.transcribe({
    path = "${ctx.audio_path}",
    format = "json",
    output_key = "transcript"
}))

flow:step("log_result", nodes.log({
    message = "Detected language: ${ctx.transcript.language}, duration: ${ctx.transcript.duration}s"
})):depends_on("transcribe")

Writing the transcript to a file for a downstream extractor

flow:step("transcribe", nodes.transcribe({
    path = "${ctx.audio_path}",
    format = "vtt",
    output_key = "transcript",
    output_file = "${ctx.audio_path}.vtt",
    timeout = 300
})):retries(2, 2):timeout(300)

-- extract_vtt reads a file, which is why transcribe wrote one.
flow:step("cues", nodes.extract_vtt({
    path = "${ctx.transcript_path}",
    cues_key = "cues"
})):depends_on("transcribe")