# OpenAI (/en/ai/models/tts/openai)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

OpenAI provides natural-sounding text-to-speech with customizable voice instructions and multiple voice options.

<CalloutContainer type="info">
  <CalloutTitle>
    Info
  </CalloutTitle>

  <CalloutDescription>
    This integration is fully supported for use with Conversational AI Engine. While it has completed functional validation, it is newer to the platform, and additional provider-specific edge cases may be identified as usage scales across a broader range of applications and workloads.
  </CalloutDescription>
</CalloutContainer>

### Sample configuration [#sample-configuration]

The following examples show how to configure OpenAI TTS when starting a conversational AI agent.

<Tabs defaultValue="python" groupId="ai-sdk-language">
  <TabsList>
    <TabsTrigger value="python">
      Python SDK
    </TabsTrigger>

    <TabsTrigger value="typescript">
      TypeScript SDK
    </TabsTrigger>

    <TabsTrigger value="go">
      Go SDK
    </TabsTrigger>

    <TabsTrigger value="rest-api">
      REST API
    </TabsTrigger>
  </TabsList>

  <TabsContent value="python">
    ```python
    from agora_agent import Agent
    from agora_agent.agentkit.vendors import OpenAITTS

    # client is your configured Agora client
    agent = (
        Agent(client)
        .with_stt(...)  # configure your STT vendor
        .with_llm(...)  # configure your LLM vendor
        .with_tts(OpenAITTS(
            api_key='your-openai-key',  # omit api_key and base_url to use Agora-managed mode
            base_url='https://api.openai.com/v1',
            model='gpt-4o-mini-tts',
            voice='coral',
            instructions='Please use standard American English, natural tone, moderate pace, and steady intonation',
            speed=1,
        ))
    )
    ```
  </TabsContent>

  <TabsContent value="typescript">
    ```typescript
    import { Agent, OpenAITTS } from 'agora-agents';

    // client is your configured Agora client
    const agent = new Agent({ client })
      .withStt(/* configure your STT vendor */)
      .withLlm(/* configure your LLM vendor */)
      .withTts(new OpenAITTS({
        apiKey: 'your-openai-key',  // omit apiKey and baseUrl to use Agora-managed mode
        baseUrl: 'https://api.openai.com/v1',
        model: 'gpt-4o-mini-tts',
        voice: 'coral',
        instructions: 'Please use standard American English, natural tone, moderate pace, and steady intonation',
        speed: 1,
      }));
    ```
  </TabsContent>

  <TabsContent value="go">
    ```go
    import "github.com/AgoraIO/agora-agents-go/v2/agentkit/vendors"

    // client is your configured Agora client
    agent := agentkit.NewAgent(client).WithStt(/* configure your STT vendor */).
      WithLlm(/* configure your LLM vendor */).
      WithTts(
        vendors.NewOpenAITTS(vendors.OpenAITTSOptions{
            APIKey:       "your-openai-key", // omit APIKey and BaseURL to use Agora-managed mode
            BaseURL:      "https://api.openai.com/v1",
            Model:        "gpt-4o-mini-tts",
            Voice:        "coral",
            Instructions: "Please use standard American English, natural tone, moderate pace, and steady intonation",
            Speed:        agora.Float64(1),
        }),
    )
    ```
  </TabsContent>

  <TabsContent value="rest-api">
    * **Managed mode**

      To use OpenAI TTS with Agora-managed credentials, set `credential_mode` to `"managed"` in the `tts` block. When using managed mode, `params.api_key` is not required. You can still use the `tts` field to configure additional settings such as `voice` and `instructions`. For more information, see [Use managed mode](/en/ai/build/custom-model-integration/managed-mode).

      ```json
      "tts": {
        "credential_mode": "managed",
        "vendor": "openai",
        "params": {
          "base_url": "https://api.openai.com/v1",
          "model": "tts-1",
          "voice": "coral",
          "instructions": "Please use standard American English, natural tone, moderate pace, and steady intonation",
          "speed": 1
        }
      }
      ```

    * **BYOK**

      ```json
      "tts": {
        "vendor": "openai",
        "params": {
          "base_url": "https://api.openai.com/v1",
          "api_key": "<your_openai_key>",
          "model": "gpt-4o-mini-tts",
          "voice": "coral",
          "instructions": "Please use standard American English, natural tone, moderate pace, and steady intonation",
          "speed": 1
        }
      }
      ```
  </TabsContent>
</Tabs>

<CalloutContainer type="warning">
  <CalloutTitle>
    Caution
  </CalloutTitle>

  <CalloutDescription>
    The parameters listed on this page are validated for use with Conversational AI Engine. Required parameters must be provided as documented. Any additional parameters are passed through directly to the underlying vendor without validation. For advanced configuration options, available voices, and detailed parameter descriptions, see the [OpenAI TTS documentation](https://platform.openai.com/docs/guides/text-to-speech).
  </CalloutDescription>
</CalloutContainer>

### Key parameters [#key-parameters]

The following parameters are required when using your own API key (BYOK). When using managed mode, `api_key` is not required. For more information, see [Use managed mode](/en/ai/build/custom-model-integration/managed-mode).

<ParameterList title="params">
  <Parameter name="base_url" type="string" required="true">
    The endpoint URL for the OpenAI TTS service. Required when using your own API key (BYOK). See [How to use data residency](https://platform.openai.com/docs/guides/your-data#how-to-use-data-residency).
  </Parameter>

  <Parameter name="api_key" type="string" required="false">
    The API key used for authentication. Required when using your own API key (BYOK). Get your API key from the [OpenAI Console](https://platform.openai.com/api-keys).
  </Parameter>

  <Parameter name="model" type="string" required="true">
    Identifier of the model to be used. Required when using your own API key (BYOK).
  </Parameter>

  <Parameter name="voice" type="string" required="true">
    The voice identifier for speech synthesis.
  </Parameter>

  <Parameter name="instructions" type="string" required="false">
    Custom instructions for voice style, accent, pace, and tone. Helps fine-tune the speech characteristics.
  </Parameter>

  <Parameter name="speed" type="number" defaultValue="1.0" required="false">
    Speaking rate multiplier. Values between `0.25` and `4.0`, where `1.0` is normal speed.
  </Parameter>
</ParameterList>

<CalloutContainer type="info">
  <CalloutTitle>
    Info
  </CalloutTitle>

  <CalloutDescription>
    OpenAI TTS models do not support changing the sample rate. The audio output is fixed at 24,000 Hz.
  </CalloutDescription>
</CalloutContainer>