Configuration & Factory Functions
Relevant source files
The following files were used as context for generating this wiki page:
Configuration and factory functions in the Speech SDK provide a flexible mechanism for instantiating and customizing Text-to-Speech (TTS) providers. While the SDK supports a convenient string-based initialization (e.g., "openai/tts-1"), factory functions allow developers to override default settings such as API keys, base URLs, and custom fetch implementations. This architecture ensures that the SDK can operate across different environments, including Node.js, Edge runtimes, and the browser.
Sources: AGENTS.md:12-14, README.md:10-15, skills/speech-sdk/SKILL.md:21-25
Provider Initialization Logic
The SDK employs a "Provider Pattern" where each TTS service (OpenAI, ElevenLabs, etc.) implements a common interface. Users can initialize these providers in two ways: using a string identifier or using a specialized factory function. When a string like "elevenlabs/eleven_v3" is used, the SDK automatically resolves the API key from environment variables. Factory functions, conversely, return a ResolvedModel object containing the configured provider instance and the chosen model ID.
Sources: AGENTS.md:27-30, README.md:154-165
The Factory Function Pattern
Each provider export includes a factory function (e.g., createOpenAI, createGoogle, createFishAudio). These functions accept a configuration object and return a "Model Selector" function. This selector is then passed to the core generateSpeech or streamSpeech functions.
The diagram shows the flow from initial configuration to the resolution of a model used by the SDK core.
Sources: src/providers/google/index.ts:318-326, src/providers/fish-audio/index.ts:161-169
Configuration Options
Providers are configured via a standard set of options defined in their respective configuration interfaces. Most providers share a common structure for these options.
| Parameter | Type | Description |
|---|---|---|
apiKey | string | The API key for the provider. If omitted, the SDK attempts to resolve it from environment variables (e.g., GOOGLE_API_KEY). |
baseURL | string | Overrides the default API endpoint. Useful for proxies or local testing. |
fetch | typeof fetch | A custom fetch implementation. Enables use in environments without a global fetch or for adding middleware/logging. |
Sources: src/providers/google/index.ts:24-28, src/providers/fish-audio/index.ts:15-19, README.md:154-165
Base URL Overrides
Providers have hardcoded default base URLs that can be overridden. For example:
- Google Gemini:
https://generativelanguage.googleapis.com/v1beta - Fish Audio:
https://api.fish.audio - Cartesia:
https://api.cartesia.ai
Sources: src/providers/google/index.ts:108, src/providers/fish-audio/index.ts:38, src/tests/cartesia-speech-model.test.ts:15-18
Request Customization
Beyond provider-level configuration, individual requests can be customized using providerOptions, headers, and execution controls like abortSignal.
Provider Options
The providerOptions field allows passing untransformed parameters directly to the underlying provider API. This is used for provider-specific features like temperature, speed, or specific output_format settings.
// Example of passing provider-specific options
await generateSpeech({
model: createOpenAI()('tts-1'),
text: 'Hello!',
voice: 'alloy',
providerOptions: { response_format: 'opus', speed: 1.2 }
});
Sources: README.md:175-178, src/tests/cartesia-speech-model.test.ts:208-223
Headers and Abort Signals
Every provider implementation supports custom HTTP headers and the standard AbortSignal for request cancellation. Headers passed here are merged with the SDK's internal headers, such as the X-User-Agent.
The sequence shows how an AbortSignal propagates from the application through the SDK to the network request.
Sources: src/providers/google/index.ts:128-135, src/tests/google-speech-model.test.ts:40-42, README.md:215-225
Error Handling and Retries
Factory functions also influence how errors are handled. The SDK uses p-retry for handling 5xx status codes and network errors, performing a default of 2 retries with exponential backoff. This behavior can be adjusted per-request via the maxRetries parameter.
| Error Class | Triggering Condition |
|---|---|
ApiError | Provider returns a non-2xx response. |
NoSpeechGeneratedError | Empty provider response or empty input text. |
StreamingNotSupportedError | streamSpeech() called on a model without streaming features. |
Sources: AGENTS.md:15-18, README.md:215-225, skills/speech-sdk/SKILL.md:118-125
Summary
Configuration and factory functions are essential for production-grade integrations of the Speech SDK. By providing a structured way to inject custom credentials, endpoint URLs, and fetch implementations, the SDK maintains its universal applicability while allowing for deep customization of the underlying HTTP traffic and provider-specific features.