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.