OpenAI transcriptions do not support reserved request field

Error message

OpenAI transcriptions do not support reserved request field `{key}`

What it means

OpenAI transcription requests get their body from the collected parts (audio bytes, model, prompt), so BAML reserves the `messages` and `stream` request fields — letting users override them would corrupt or conflict with the constructed multipart body. reject_reserved_request_fields bails if either key appears in the client properties.

Source

Thrown at engine/baml-runtime/src/internal/llm_client/primitive/openai/types.rs:155

            }
        }
        ChatMessagePart::Media(media) => {
            if media.media_type != BamlMediaType::Audio {
                bail!("OpenAI transcriptions only support audio media parts")
            }
            audio_parts.push(media.clone());
        }
        ChatMessagePart::WithMeta(inner, _) => {
            collect_transcription_prompt_parts(inner, audio_parts, text_parts)?;
        }
    }
    Ok(())
}

fn reject_reserved_request_fields(properties: &BamlMap<String, Value>) -> Result<()> {
    for key in ["messages", "stream"] {
        if properties.contains_key(key) {
            bail!("OpenAI transcriptions do not support reserved request field `{key}`")
        }
    }
    Ok(())
}

fn required_string_field(properties: &BamlMap<String, Value>, field: &str) -> Result<String> {
    let value = properties
        .get(field)
        .with_context(|| format!("OpenAI transcriptions require string field `{field}`"))?;

    match value {
        Value::String(value) => Ok(value.clone()),
        _ => bail!("OpenAI transcription field `{field}` must be a string"),
    }
}

fn optional_string_field(
    properties: &BamlMap<String, Value>,

View on GitHub (pinned to bd85ce9dee)

Solutions

Remove `messages` and `stream` keys from the transcription client's options.
Keep transcription client options limited to transcription-relevant fields (model, prompt, language, temperature, etc.).
If you need streaming chat, use a separate chat client rather than the transcription client.

Example fix

// before
client<Transcribe> { provider openai options { model "whisper-1" stream true } }
// after
client<Transcribe> { provider openai options { model "whisper-1" } }

Defensive patterns

Strategy: validation

Validate before calling

// Reject reserved fields in transcription client options before use
const RESERVED = ["messages", "stream"];
for (const key of RESERVED) {
  if (key in clientOptions) throw new Error(`Remove reserved field '${key}' from transcription options`);
}

Prevention

Never copy chat-client options (messages/stream) into transcription client blocks.
Keep transcription options to: model, prompt, language, temperature, response_format.
Lint clients.baml for reserved keys in clients whose model is a transcription model.

When it happens

Trigger: Setting `messages` or `stream` in the options block of a transcription-configured OpenAI client (copied from a chat client config), which is checked at the start of build_transcription_parts.

Common situations: Copying a chat-completions client block and changing only the model to whisper-1, leaving `stream true` or a `messages` override in place; adding passthrough options wholesale from another client.

Related errors

AI-assisted analysis of BoundaryML/baml@bd85ce9dee (2026-09-12). Data as JSON: /api/errors/eb0f5d376b704aff. Report an issue: GitHub.