Hmbown/CodeWhale · error

Model '{model}' requires a voice design prompt. Pass --voice

Error message

Model '{model}' requires a voice design prompt. Pass --voice-prompt or --instruction.

What it means

Model-specific validation in `synthesize_speech`: when the (lowercased) model id contains `voicedesign`, the request must include an `instruction` — a user-message that describes the voice to design and is not spoken verbatim. Without it the MiMo voice-design flow has nothing to synthesize a voice from, so the client rejects the call locally.

Source

Thrown at crates/tui/src/client.rs:2368

        }

        let audio_format = normalize_audio_format(&request.audio_format);
        let model = wire_model_for_provider_route(self.api_provider, &self.base_url, &model);
        let model_lower = model.to_ascii_lowercase();
        let instruction = request
            .instruction
            .as_deref()
            .map(str::trim)
            .filter(|value| !value.is_empty());
        let voice = request
            .voice
            .as_deref()
            .map(str::trim)
            .filter(|value| !value.is_empty())
            .map(str::to_string);

        if model_lower.contains("voicedesign") && instruction.is_none() {
            anyhow::bail!(
                "Model '{model}' requires a voice design prompt. Pass --voice-prompt or --instruction."
            );
        }
        if model_lower.contains("voiceclone") && voice.is_none() {
            anyhow::bail!(
                "Model '{model}' requires cloned voice data. Pass --clone-voice <mp3|wav> or --voice <data-uri>."
            );
        }

        let mut audio = json!({
            "format": audio_format.clone(),
        });
        if let Some(voice) = voice.as_deref() {
            audio["voice"] = json!(voice);
        }

        let body = build_speech_synthesis_body(&model, &text, instruction, audio);

View on GitHub (pinned to 8880682c63)

Solutions

1. Add a voice design prompt: `--voice-prompt "warm middle-aged male, calm documentary tone"` (or the equivalent `--instruction`).
2. If you did not want voice design at all, switch to a plain TTS model id (one without `voicedesign`).
3. Ensure the instruction is non-blank — a whitespace-only value is filtered out and triggers this same error.

Example fix

# before
/speech --model mimo-voicedesign-v1 "hello world"
# after
/speech --model mimo-voicedesign-v1 --voice-prompt "warm narrator, calm tone" "hello world"

// Mirror the client's rule before sending.
fn voicedesign_needs_instruction(model: &str, instruction: Option<&str>) -> bool {
    model.to_ascii_lowercase().contains("voicedesign")
        && instruction.map(str::trim).filter(|s| !s.is_empty()).is_none()
}

enum SpeechModelKind { Plain, VoiceDesign, VoiceClone }
fn speech_model_kind(model: &str) -> SpeechModelKind {
    let m = model.to_ascii_lowercase();
    if m.contains("voicedesign") { SpeechModelKind::VoiceDesign }
    else if m.contains("voiceclone") { SpeechModelKind::VoiceClone }
    else { SpeechModelKind::Plain }
}

When it happens

Trigger: Calling speech synthesis with a model like `mimo-voicedesign-*` while omitting both `--voice-prompt` and `--instruction`; passing an instruction that is only whitespace (it is trimmed and filtered, so it counts as absent).

Common situations: Selecting the voice-design model by mistake when intending plain TTS; assuming the instruction is optional for all voice models; copy-pasting a command template that only worked for non-voicedesign models.

Related errors

• speech synthesis requires provider 'xiaomi-mimo' (current: {
• Model '{model}' requires cloned voice data. Pass --clone-voi
• Speech model cannot be empty
• Speech text cannot be empty
• Speech synthesis failed: HTTP {status}: {error_text}

AI-assisted analysis of Hmbown/CodeWhale@8880682c63 (2026-08-16). Data as JSON: /api/errors/3071249bca7be251. Report an issue: GitHub.