Migration and troubleshooting

Migration checklist

Install the matching provider extra.
Keep both the TeenageWorks and provider credentials configured.
Apply the patch once during application startup.
Keep using the existing provider client.
Test every sync, async, streaming, or socket path used by the application.

Tested versions

Provider	Versions
OpenAI	`3.3.1`, `3.3.0`, `3.2.0`
ElevenLabs	`2.64.0`, `2.63.0`, `2.62.0`

Unknown versions raise UnsupportedProviderVersionError. Use allow_untested_version=True only for controlled testing; it emits UntestedProviderVersionWarning.

Common failures

Symptom	Check
Call still reaches the provider	Patch timing, routed model ID, and installed provider version
Rerouted speech fails authentication	`TEENAGEWORKS_API_KEY` or `TW_API_KEY`
Voice sounds different	Use a returned `voice_...` ID instead of a provider voice name
A parameter has no effect	Read `TeenageWorksUnsupportedParameterWarning`
Format error	Request PCM, MP3, or WAV
Timestamp error	Use ordinary conversion or streaming
Socket closes during setup	Check key, voice, format, sample rate, and initialization fields

Pin a tested provider version before production. Provider endpoints and non-TTS resources remain unchanged.