> ## Documentation Index
> Fetch the complete documentation index at: https://docs.witting.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenAI Setup

> Configure OpenAI API access for real-time voice AI

Vocalis uses the OpenAI Realtime API to power the Actor's voice. This is what makes the AI sound natural and conversational — speech goes directly in and out without a text intermediary.

## Prerequisites

* An OpenAI account with API access ([platform.openai.com](https://platform.openai.com))
* Access to the Realtime API (may require a usage tier upgrade)

## Step 1: Create an API key

<Steps>
  <Step title="Go to API keys">
    Log in to [platform.openai.com](https://platform.openai.com) and navigate to **API keys**.
  </Step>

  <Step title="Create a new key">
    Click **Create new secret key**.

    * **Name**: `vocalis-production` (or similar)
    * **Permissions**: Ensure it has access to the Realtime API models
  </Step>

  <Step title="Copy the key">
    Copy the key immediately — you won't be able to see it again.
  </Step>
</Steps>

<Warning>
  Store your API key securely. Do not share it or commit it to version control.
</Warning>

## Step 2: Verify Realtime API access

The Realtime API is required for Vocalis to function. To verify you have access:

1. Check your [OpenAI usage tier](https://platform.openai.com/account/limits). The Realtime API may require Tier 1 or above.
2. Ensure your account has billing set up with sufficient credits.

## Step 3: Connect to Vocalis

<Steps>
  <Step title="Open Vocalis settings">
    Log in to [vocalis.witting.ai](https://vocalis.witting.ai) and go to **Settings** → **Integrations**.
  </Step>

  <Step title="Enter your API key">
    In the **OpenAI** section, paste your API key.
  </Step>

  <Step title="Select a default model">
    Choose the default model for your Actors. Vocalis supports OpenAI Realtime models — select the latest available option.
  </Step>

  <Step title="Save and test">
    Click **Save**. Use the **Test Connection** button to verify the key works.
  </Step>
</Steps>

## Voice options

When configuring an Actor, you can select from the available OpenAI voices. Each voice has a different tone and character:

| Voice     | Description              |
| --------- | ------------------------ |
| `alloy`   | Neutral, balanced        |
| `echo`    | Warm, conversational     |
| `fable`   | Expressive, storytelling |
| `onyx`    | Deep, authoritative      |
| `nova`    | Friendly, upbeat         |
| `shimmer` | Clear, professional      |

<Tip>
  Test different voices with your system prompt to find the best match for your Actor's persona. A technical recruiter might suit `nova` or `alloy`, while an executive reference check might work better with `onyx`.
</Tip>

## Usage and costs

Realtime API usage is billed by OpenAI based on audio duration. Monitor your usage at [platform.openai.com/usage](https://platform.openai.com/usage).

Typical interview costs depend on call duration:

* A 15-minute phone screen uses approximately 15 minutes of audio input + output
* Set OpenAI usage limits to avoid unexpected charges

## Troubleshooting

| Issue                 | Solution                                                                   |
| --------------------- | -------------------------------------------------------------------------- |
| "Invalid API key"     | Regenerate the key and re-enter it. Ensure no whitespace was copied.       |
| "Model not available" | Check your OpenAI usage tier. The Realtime API may require a tier upgrade. |
| Voice sounds robotic  | Ensure you're using a Realtime API model, not a standard completion model. |

## Next steps

<Columns cols={2}>
  <Card title="Create Your First Actor" icon="robot" href="/vocalis/getting-started/create-first-actor">
    Configure an Actor with your preferred voice.
  </Card>

  <Card title="Quick Start" icon="rocket" href="/vocalis/getting-started/quick-start">
    Run your first interview.
  </Card>
</Columns>