Repository Public
1# Custom voices23> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.45Custom voices enable you to create a unique voice for your agent or application. These voices can be used for audio output with the [Text to Speech API](https://developers.openai.com/api/reference/resources/audio/subresources/speech/methods/create), the [Realtime API](https://developers.openai.com/api/reference/resources/realtime), or the [Chat Completions API with audio output](https://developers.openai.com/api/docs/guides/audio-chat-completions).67To create a custom voice, you’ll provide a short sample audio reference that the model will seek to replicate.891011 {"Custom voices are limited to eligible customers. Contact our "}12 [{"sales team"}](https://openai.com/contact-sales/)13 {14 " to learn more. Once enabled for your organization, you’ll have access to the "15 }16 [{"Voices"}](https://platform.openai.com/audio/voices)17 {" tab under Audio."}18 192021## Creating a voice2223Currently, voices must be created through an API request. See the API reference for the full set of API operations.2425Creating a voice requires two separate audio recordings:26271. **Consent recording:** This recording captures the voice actor providing consent to create a likeness of their voice. The actor must read one of the consent phrases provided below.282. **Sample recording:** The actual audio sample that the model will try to adhere to. The voice must match the consent recording.2930**Tips for creating a high-quality voice**3132The quality of your custom voice is highly dependent on the quality of the sample you provide. Optimizing the recording quality can make a big difference.3334- Record in a quiet space with minimal echo.35- Use a professional XLR microphone.36- Stay about 7–8 inches from the mic with a pop filter in between, and keep that distance consistent.37- The model copies exactly what you give it—tone, cadence, energy, pauses, habits—so record the exact voice you want. Be consistent in energy, style, and accent throughout.38- Small variations in the audio sample can result in quality differences with the generated voice. Try multiple examples to find the best fit.3940**Requirements and limitations**4142- At most 20 voices can be created per organization.43- The audio samples must be 30 seconds or less.44- The audio samples must be one of the following types: `mpeg`, `wav`, `ogg`, `aac`, `flac`, `webm`, or `mp4`.4546Refer to the Text-to-Speech Supplemental Agreement for additional terms of use.4748**Creating a voice consent**4950The consent audio recording must only include one of the following phrases. Any divergence from the script will lead to a failure.515253| Language | Phrase |54| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |55| `de` | Ich bin der Eigentümer dieser Stimme und bin damit einverstanden, dass OpenAI diese Stimme zur Erstellung eines synthetischen Stimmmodells verwendet. |56| `en` | I am the owner of this voice and I consent to OpenAI using this voice to create a synthetic voice model. |57| `es` | Soy el propietario de esta voz y doy mi consentimiento para que OpenAI la utilice para crear un modelo de voz sintética. |58| `fr` | Je suis le propriétaire de cette voix et j'autorise OpenAI à utiliser cette voix pour créer un modèle de voix synthétique. |59| `hi` | मैं इस आवाज का मालिक हूं और मैं सिंथेटिक आवाज मॉडल बनाने के लिए OpenAI को इस आवाज का उपयोग करने की सहमति देता हूं |60| `id` | Saya adalah pemilik suara ini dan saya memberikan persetujuan kepada OpenAI untuk menggunakan suara ini guna membuat model suara sintetis. |61| `it` | Sono il proprietario di questa voce e acconsento che OpenAI la utilizzi per creare un modello di voce sintetica. |62| `ja` | 私はこの音声の所有者であり、OpenAIがこの音声を使用して音声合成 モデルを作成することを承認します。 |63| `ko` | 나는 이 음성의 소유자이며 OpenAI가 이 음성을 사용하여 음성 합성 모델을 생성할 것을 허용합니다. |64| `nl` | Ik ben de eigenaar van deze stem en ik geef OpenAI toestemming om deze stem te gebruiken om een synthetisch stemmodel te maken. |65| `pl` | Jestem właścicielem tego głosu i wyrażam zgodę na wykorzystanie go przez OpenAI w celu utworzenia syntetycznego modelu głosu. |66| `pt` | Eu sou o proprietário desta voz e autorizo o OpenAI a usá-la para criar um modelo de voz sintética. |67| `ru` | Я являюсь владельцем этого голоса и даю согласие OpenAI на использование этого голоса для создания модели синтетического голоса. |68| `uk` | Я є власником цього голосу і даю згоду OpenAI використовувати цей голос для створення синтетичної голосової моделі. |69| `vi` | Tôi là chủ sở hữu giọng nói này và tôi đồng ý cho OpenAI sử dụng giọng nói này để tạo mô hình giọng nói tổng hợp. |70| `zh` | 我是此声音的拥有者并授权OpenAI使用此声音创建语音合成模型 |7172Then upload the recording via the API. A successful upload will return the consent recording ID that you’ll reference later. Note the consent can be used for multiple different voice creations if the same voice actor is making multiple attempts.7374```bash75curl https://api.openai.com/v1/audio/voice_consents \76 -X POST \77 -H "Authorization: Bearer $OPENAI_API_KEY" \78 -F "name=test_consent" \79 -F "language=en" \80 -F "recording=@$HOME/tmp/voice_consent/consent_recording.wav;type=audio/x-wav"81```828384**Creating a voice**8586Next, you’ll create the actual voice by referencing the consent recording ID, and providing the voice sample.8788```bash89curl https://api.openai.com/v1/audio/voices \90 -X POST \91 -H "Authorization: Bearer $OPENAI_API_KEY" \92 -F "name=test_voice" \93 -F "audio_sample=@$HOME/tmp/voice_consent/audio_sample_recording.wav;type=audio/x-wav" \94 -F "consent=cons_123abc"95```969798If successful, the created voice will be listed under the [Audio tab](https://platform.openai.com/audio/voices).99100## Using a voice during speech generation101102Speech generation will work as usual. Specify the ID of the voice in the `voice` parameter when [creating speech](https://developers.openai.com/api/reference/resources/audio/subresources/speech/methods/create), or when initiating a [realtime session](https://developers.openai.com/api/reference/resources/realtime/subresources/calls/methods/create#realtime_create_call-session-audio-output-voice).103104**Text to speech example**105106```bash107curl https://api.openai.com/v1/audio/speech \108 -X POST \109 -H "Authorization: Bearer $OPENAI_API_KEY" \110 -H "Content-Type: application/json" \111 -d '{112 "model": "gpt-4o-mini-tts",113 "voice": {114 "id": "voice_123abc"115 },116 "input": "Maple est le meilleur golden retriever du monde entier.",117 "language": "fr",118 "format": "wav"119 }' \120 --output sample.wav121```122123124**Realtime API example**125126For Ruby, replace `voice_123` with your custom voice ID before running the example.127128```javascript129const sessionConfig = JSON.stringify({130 session: {131 type: "realtime",132 model: "gpt-realtime-2",133 audio: {134 output: {135 voice: { id: "voice_123abc" },136 },137 },138 },139});140```141142```ruby143# Replace the illustrative IDs and URLs below with your own resource values.144require "json"145146session_config = JSON.generate(147 session: {148 type: "realtime",149 model: "gpt-realtime-2",150 audio: { output: { voice: { id: "voice_123" } } }151 }152)153puts(session_config)154```155156157## Use a custom voice with GPT-Live158159Use a project-scoped API key approved for both GPT-Live and custom voice160creation. Reading consent phrases and using a custom voice require161`api.voices.read`; creating consents and voices requires `api.voices.write` and162custom-voice API access. Use the same project for every request and keep the API163key on a trusted server.164165### Prepare the recordings166167List the current supported consent phrases before recording:168169```bash170curl https://api.openai.com/v1/audio/consent_phrases \171 -H "Authorization: Bearer $OPENAI_API_KEY"172```173174The consent recording and reference sample must come from the same person. The175sample needs at least five seconds of actual speech and at least 15 transcribed176text tokens; silence does not count. Use a 10–30-second177recording with several complete sentences. Each upload is limited to 10 MiB.178The service extracts the reference transcript from your recording.179180Browser recorders may label audio `audio/webm;codecs=opus`, which the upload181endpoint rejects. When constructing an upload, use the supported base MIME type182`audio/webm` while preserving the original audio bytes. Use the consent and voice183creation requests above, then save the returned voice ID.184185### Select the voice at session creation186187Pass a custom voice as an object, such as `{ "id": "voice_123" }`. Named voices188such as `"marin"` use strings.189190`gpt-live-1` supports custom voices with English accents. To use an accent, also191specify it in `session.instructions`, such as "Speak British English" or "Speak192Irish English." The example below uses British English; change the instruction193to match the accent you want for your custom voice.194195Include the following configuration in the initial session:196197```json198{199 "model": "gpt-live-1",200 "instructions": "You are a helpful voice assistant. Speak British English.",201 "audio": { "output": { "voice": { "id": "voice_123" } } }202}203```204205For [WebRTC](https://developers.openai.com/api/docs/guides/voice-webrtc?api=live), have your application server206place this configuration in the JSON `session` field alongside `transport`.207Authenticate requests to your server with application credentials, and keep the208OpenAI API key on the server.209210For [WebSockets](https://developers.openai.com/api/docs/guides/voice-websockets?api=live), put the configuration211in the first `session.start` event. Follow the connection guide for streaming212audio and closing the session.213214### Handle access and lifecycle failures215216- Choose the voice at session creation. Start a new session to use a different voice.217- A deleted or revoked voice, a consent from another project, or missing custom-voice access can appear as a `404`.218- Malformed audio, a mismatched speaker, or a non-project-scoped key is rejected.219220Confirm your project's permissions, recording minimums, and upload limits221before creating a voice. See [GPT-Live getting started](https://developers.openai.com/api/docs/guides/live)222for session setup requirements.