feat(api): add prompt-based voice creation (#1205)

## Summary

Create custom voices from text descriptions and read their original
prompts.

## Changes

- Add prompt-based voice creation with optional script hints and model
selection.
- Expose the original prompt on voice responses when available.

Co-authored-by: marcuswood-oai <323319819+marcuswood-oai@users.noreply.github.com>

Author: marcuswood-oai

.castiron.stats.yml

@@ -1,8 +1,8 @@
 schema_version: 1
-generation_id: e71f55aa-cd36-4bcf-97b3-55096536ddeb
-openapi_spec_hash: 9f25e689946a326df6a67ecaccc90e48
-openapi_transformed_spec_hash: 7acc5250f436f644f74dd5f5c348741d
-config_hash: dda57991526f80e9f99d8f9621460eaa
-codegen_sha: 38f50c350df42e0de48ffd3b3111de9bc51dd733
-codegen_hash: 23c69e401abac115c537fc9ea4dc066687d188231c9eb4196e402273db798fb7
-public_codegen_sha: 680fa4655b6d09b9838ca751b503b521c9398e61
+generation_id: 8419511e-de94-4184-8866-c88383c29cc6
+openapi_spec_hash: 7ca9a258daebb3d2c04cf85a4c394f5a
+openapi_transformed_spec_hash: b23980060fc5ae2b16711bed7eadd3f3
+config_hash: 8f3e767a17693de466483ca638e0305f
+codegen_sha: acf19120b7fabd21b945246c46f26b8c7e132ff2
+codegen_hash: bd6e918e20d78d1ee682b4f0f00367d58ee6927ab27a2275a323c857f44f79e2
+public_codegen_sha: 37ee738014b603a10004bcfa66101c928f96c476

api_reference/openapi.transformed.yml

@@ -1691,11 +1691,11 @@ paths:
       - Audio
       summary: Create voice
       description: |
-        Create a custom voice you can use for audio output (for example, in Text-to-Speech and the Realtime API). This requires an audio sample and a previously uploaded consent recording.
+        Creates a voice from a text prompt or from a consent recording and an audio sample.
 
-        Send `name`, `audio_sample`, and the `consent` recording ID as multipart form data. The optional `type` defaults to `audio_sample`.
+        For prompt-based creation, send `type: "prompt"` with a `name` and `prompt` as JSON or multipart form data. For creation from an audio sample, send `type: "audio_sample"` with a `name`, `audio_sample`, and `consent` recording ID as multipart form data. The type defaults to `audio_sample` when omitted.
 
-        Returns the saved voice's metadata. See the [custom voices guide](https://developers.openai.com/api/docs/guides/text-to-speech#custom-voices) for requirements and best practices. Custom voices are limited to eligible customers.
+        Returns the saved voice's metadata. Voices created from text prompts are supported only in Live, not in Realtime or the speech endpoint. The response does not include preview audio.
       requestBody:
         required: true
         content:
@@ -1710,7 +1710,7 @@ paths:
               schema:
                 $ref: '#/components/schemas/VoiceResource'
         '400':
-          description: Invalid voice request, consent recording, or audio sample.
+          description: Invalid voice request, prompt, script hint, model, consent recording, or audio sample.
           content:
             application/json:
               schema:
@@ -1735,9 +1735,13 @@ paths:
               curl https://api.openai.com/v1/audio/voices \
                 -X POST \
                 -H "Authorization: Bearer $OPENAI_API_KEY" \
-                -F "name=My new voice" \
-                -F "consent=cons_1234" \
-                -F "audio_sample=@audio_sample.wav;type=audio/x-wav"
+                -H "Content-Type: application/json" \
+                -d '{
+                  "type": "prompt",
+                  "name": "Warm narrator",
+                  "prompt": "A warm, calm narrator with a clear, measured delivery.",
+                  "model": "auto"
+                }'
   /batches:
     post:
       summary: Create batch
@@ -41530,7 +41534,7 @@ components:
                   `alloy`, `ash`, `ballad`, `coral`, `echo`, `fable`, `nova`, `onyx`,
                   `sage`, `shimmer`, `marin`, and `cedar`. You may also provide a
                   custom voice object with an `id`, for example `{ "id": "voice_1234" }`.
-                  Custom voices must be created from audio samples.
+                  Custom voices must be created from audio samples. Voices created from text prompts are supported only in Live.
               format:
                 type: string
                 enum:
@@ -44371,7 +44375,7 @@ components:
           description: Control the voice of your generated audio with additional instructions. Does not work with `tts-1` or `tts-1-hd`.
           maxLength: 4096
         voice:
-          description: 'The voice to use when generating the audio. Supported built-in voices are `alloy`, `ash`, `ballad`, `coral`, `echo`, `fable`, `onyx`, `nova`, `sage`, `shimmer`, `verse`, `marin`, and `cedar`. You may also provide a custom voice object with an `id`, for example `{ "id": "voice_1234" }`. Previews of the voices are available in the [Text to speech guide](https://developers.openai.com/api/docs/guides/text-to-speech#voice-options). Custom voices must be created from audio samples.'
+          description: 'The voice to use when generating the audio. Supported built-in voices are `alloy`, `ash`, `ballad`, `coral`, `echo`, `fable`, `onyx`, `nova`, `sage`, `shimmer`, `verse`, `marin`, and `cedar`. You may also provide a custom voice object with an `id`, for example `{ "id": "voice_1234" }`. Previews of the voices are available in the [Text to speech guide](https://developers.openai.com/api/docs/guides/text-to-speech#voice-options). Custom voices must be created from audio samples. Voices created from text prompts are supported only in Live.'
           title: Voice
           anyOf:
           - anyOf:
@@ -45263,9 +45267,11 @@ components:
         propertyName: type
         mapping:
           audio_sample: '#/components/schemas/CreateVoiceFromConsentRequest'
+          prompt: '#/components/schemas/CreateVoicePromptRequest'
       x-oai-default-discriminator-value: audio_sample
       anyOf:
       - $ref: '#/components/schemas/CreateVoiceFromConsentRequest'
+      - $ref: '#/components/schemas/CreateVoicePromptRequest'
     CustomToolCall:
       type: object
       title: Custom tool call
@@ -54892,7 +54898,7 @@ components:
             `marin`, and `cedar`. You may also provide a custom voice object with an
             `id`, for example `{ "id": "voice_1234" }`. Voice cannot be changed during
             the session once the model has responded with audio at least once.
-            Custom voices must be created from audio samples.
+            Custom voices must be created from audio samples. Voices created from text prompts are supported only in Live.
         output_audio_format:
           type: string
           enum:
@@ -58236,7 +58242,7 @@ components:
                     `marin`, and `cedar`. You may also provide a custom voice object with
                     an `id`, for example `{ "id": "voice_1234" }`. Voice cannot be changed
                     during the session once the model has responded with audio at least once.
-                    Custom voices must be created from audio samples.
+                    Custom voices must be created from audio samples. Voices created from text prompts are supported only in Live.
                     We recommend `marin` and `cedar` for best quality.
         tools:
           type: array
@@ -60809,7 +60815,7 @@ components:
             `marin`, and `cedar`. You may also provide a custom voice object with an
             `id`, for example `{ "id": "voice_1234" }`. Voice cannot be changed during
             the session once the model has responded with audio at least once.
-            Custom voices must be created from audio samples.
+            Custom voices must be created from audio samples. Voices created from text prompts are supported only in Live.
         input_audio_format:
           type: string
           description: |
@@ -61089,7 +61095,7 @@ components:
                     `marin`, and `cedar`. You may also provide a custom voice object with
                     an `id`, for example `{ "id": "voice_1234" }`. Voice cannot be changed
                     during the session once the model has responded with audio at least once.
-                    Custom voices must be created from audio samples.
+                    Custom voices must be created from audio samples. Voices created from text prompts are supported only in Live.
                     We recommend `marin` and `cedar` for best quality.
                 speed:
                   type: number
@@ -71723,7 +71729,7 @@ components:
     VoiceResource:
       type: object
       title: Voice
-      description: A custom voice that can be used for audio output.
+      description: A custom voice that can be used for audio output. Voices created from text prompts are supported only in Live.
       additionalProperties: false
       properties:
         object:
@@ -71740,6 +71746,10 @@ components:
           type: string
           enum:
           - audio_sample
+          - prompt
+        prompt:
+          type: string
+          description: The original text prompt used to create the voice. Present for prompt-generated voices with a stored prompt; omitted for audio-sample voices and older voices without a stored prompt.
         name:
           type: string
           description: The name of the voice.
@@ -106332,6 +106342,45 @@ components:
       - $ref: '#/components/schemas/BetaResponseCustomToolCallInputDoneEvent'
       discriminator:
         propertyName: type
+    CreateVoicePromptRequest:
+      type: object
+      title: Prompt
+      description: Creates a synthetic voice from a text description. Supports application/json or multipart/form-data.
+      additionalProperties: false
+      properties:
+        type:
+          type: string
+          enum:
+          - prompt
+          description: Set to `prompt` to create a voice from a text description.
+        name:
+          type: string
+          minLength: 1
+          maxLength: 256
+          description: The name of the new voice.
+        prompt:
+          type: string
+          minLength: 1
+          maxLength: 2000
+          description: A description of the desired voice. Must not contain only whitespace.
+        script_hint:
+          type: string
+          minLength: 1
+          maxLength: 2000
+          description: Optional text for the voice to speak during creation. If omitted, a script is generated from the prompt. Must not be blank after trimming whitespace; scripts that are too short are rejected.
+        model:
+          anyOf:
+          - type: string
+          - type: string
+            enum:
+            - auto
+            - 2026-10-08
+          default: auto
+          description: The voice creation model to use. Defaults to `auto`.
+      required:
+      - type
+      - name
+      - prompt
     OAuthErrorCode:
       anyOf:
       - enum:

openai-java-core/src/main/kotlin/com/openai/models/audio/speech/SpeechCreateParams.kt

@@ -68,7 +68,8 @@ private constructor(
      * `cedar`. You may also provide a custom voice object with an `id`, for example `{ "id":
      * "voice_1234" }`. Previews of the voices are available in the
      * [Text to speech guide](https://developers.openai.com/api/docs/guides/text-to-speech#voice-options).
-     * Custom voices must be created from audio samples.
+     * Custom voices must be created from audio samples. Voices created from text prompts are
+     * supported only in Live.
      *
      * @throws OpenAIInvalidDataException if the JSON field has an unexpected type or is
      *   unexpectedly missing or null (e.g. if the server responded with an unexpected value).
@@ -252,7 +253,8 @@ private constructor(
          * and `cedar`. You may also provide a custom voice object with an `id`, for example `{
          * "id": "voice_1234" }`. Previews of the voices are available in the
          * [Text to speech guide](https://developers.openai.com/api/docs/guides/text-to-speech#voice-options).
-         * Custom voices must be created from audio samples.
+         * Custom voices must be created from audio samples. Voices created from text prompts are
+         * supported only in Live.
          */
         fun voice(voice: Voice) = apply { body.voice(voice) }
 
@@ -548,7 +550,8 @@ private constructor(
          * and `cedar`. You may also provide a custom voice object with an `id`, for example `{
          * "id": "voice_1234" }`. Previews of the voices are available in the
          * [Text to speech guide](https://developers.openai.com/api/docs/guides/text-to-speech#voice-options).
-         * Custom voices must be created from audio samples.
+         * Custom voices must be created from audio samples. Voices created from text prompts are
+         * supported only in Live.
          *
          * @throws OpenAIInvalidDataException if the JSON field has an unexpected type or is
          *   unexpectedly missing or null (e.g. if the server responded with an unexpected value).
@@ -745,7 +748,8 @@ private constructor(
              * `id`, for example `{ "id": "voice_1234" }`. Previews of the voices are available in
              * the
              * [Text to speech guide](https://developers.openai.com/api/docs/guides/text-to-speech#voice-options).
-             * Custom voices must be created from audio samples.
+             * Custom voices must be created from audio samples. Voices created from text prompts
+             * are supported only in Live.
              */
             fun voice(voice: Voice) = voice(JsonField.of(voice))
 
@@ -971,7 +975,8 @@ private constructor(
      * `cedar`. You may also provide a custom voice object with an `id`, for example `{ "id":
      * "voice_1234" }`. Previews of the voices are available in the
      * [Text to speech guide](https://developers.openai.com/api/docs/guides/text-to-speech#voice-options).
-     * Custom voices must be created from audio samples.
+     * Custom voices must be created from audio samples. Voices created from text prompts are
+     * supported only in Live.
      */
     @JsonDeserialize(using = Voice.Deserializer::class)
     @JsonSerialize(using = Voice.Serializer::class)
@@ -991,7 +996,8 @@ private constructor(
          * and `cedar`. You may also provide a custom voice object with an `id`, for example `{
          * "id": "voice_1234" }`. Previews of the voices are available in the
          * [Text to speech guide](https://developers.openai.com/api/docs/guides/text-to-speech#voice-options).
-         * Custom voices must be created from audio samples.
+         * Custom voices must be created from audio samples. Voices created from text prompts are
+         * supported only in Live.
          */
         fun unionMember1(): Optional<UnionMember1> = Optional.ofNullable(unionMember1)
 
@@ -1012,7 +1018,8 @@ private constructor(
          * and `cedar`. You may also provide a custom voice object with an `id`, for example `{
          * "id": "voice_1234" }`. Previews of the voices are available in the
          * [Text to speech guide](https://developers.openai.com/api/docs/guides/text-to-speech#voice-options).
-         * Custom voices must be created from audio samples.
+         * Custom voices must be created from audio samples. Voices created from text prompts are
+         * supported only in Live.
          */
         fun asUnionMember1(): UnionMember1 = unionMember1.getOrThrow("unionMember1")
 
@@ -1152,7 +1159,8 @@ private constructor(
              * `id`, for example `{ "id": "voice_1234" }`. Previews of the voices are available in
              * the
              * [Text to speech guide](https://developers.openai.com/api/docs/guides/text-to-speech#voice-options).
-             * Custom voices must be created from audio samples.
+             * Custom voices must be created from audio samples. Voices created from text prompts
+             * are supported only in Live.
              */
             @JvmStatic
             fun ofUnionMember1(unionMember1: UnionMember1) = Voice(unionMember1 = unionMember1)
@@ -1173,7 +1181,8 @@ private constructor(
              * `id`, for example `{ "id": "voice_1234" }`. Previews of the voices are available in
              * the
              * [Text to speech guide](https://developers.openai.com/api/docs/guides/text-to-speech#voice-options).
-             * Custom voices must be created from audio samples.
+             * Custom voices must be created from audio samples. Voices created from text prompts
+             * are supported only in Live.
              */
             fun visitUnionMember1(unionMember1: UnionMember1): T
 
@@ -1251,7 +1260,8 @@ private constructor(
          * and `cedar`. You may also provide a custom voice object with an `id`, for example `{
          * "id": "voice_1234" }`. Previews of the voices are available in the
          * [Text to speech guide](https://developers.openai.com/api/docs/guides/text-to-speech#voice-options).
-         * Custom voices must be created from audio samples.
+         * Custom voices must be created from audio samples. Voices created from text prompts are
+         * supported only in Live.
          */
         class UnionMember1 @JsonCreator private constructor(private val value: JsonField<String>) :
             Enum {