API Evangelist conversational phrasing for OpenAI Audio API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for OpenAI Audio API
  version: 1.0.0
extends: openapi/openai-audio-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 9
- target: $.paths['/audio/speech'].post
  update:
    x-apievangelist-phrasing:
      intent: Turn text into spoken audio
      effect: write
      questions:
      - How do I convert a paragraph of text into an MP3 voiceover?
      - Can I control the speaking speed and tone of generated speech?
      - Which voices can read my text aloud, and can the audio be streamed?
      instructions:
      - text: Read {input} aloud using voice {voice} with model {model}.
        slots:
          input: requestBody.input
          voice: requestBody.voice
          model: requestBody.model
      - text: Generate a {response_format} speech file of {input} in voice {voice} using {model}.
        slots:
          response_format: requestBody.response_format
          input: requestBody.input
          voice: requestBody.voice
          model: requestBody.model
      - text: Narrate {input} with {model} in voice {voice} at speed {speed}, speaking {instructions}.
        slots:
          input: requestBody.input
          model: requestBody.model
          voice: requestBody.voice
          speed: requestBody.speed
          instructions: requestBody.instructions
      method: generated
      generated: '2026-09-26'
- target: $.paths['/audio/transcriptions'].post
  update:
    x-apievangelist-phrasing:
      intent: Transcribe an audio recording
      effect: write
      questions:
      - What's the way to turn a meeting recording into text in its original language?
      - Can I get word-level timestamps or speaker labels in a transcript?
      - Can I hint the spoken language to improve transcription accuracy?
      instructions:
      - text: Transcribe audio file {file} with model {model}.
        slots:
          file: requestBody.file
          model: requestBody.model
      - text: Transcribe {file} using {model}, telling it the speech is in {language}.
        slots:
          file: requestBody.file
          model: requestBody.model
          language: requestBody.language
      - text: Produce a {response_format} transcript of {file} with {model}.
        slots:
          response_format: requestBody.response_format
          file: requestBody.file
          model: requestBody.model
      method: generated
      generated: '2026-09-26'
- target: $.paths['/audio/translations'].post
  update:
    x-apievangelist-phrasing:
      intent: Translate spoken audio into English text
      effect: write
      questions:
      - Can I take a Spanish audio clip and get an English transcript back?
      - Is there a way to translate foreign-language speech straight into English text?
      instructions:
      - text: Translate the speech in {file} into English using {model}.
        slots:
          file: requestBody.file
          model: requestBody.model
      - text: Give me an English translation of recording {file} with model {model} as {response_format}.
        slots:
          file: requestBody.file
          model: requestBody.model
          response_format: requestBody.response_format
      method: generated
      generated: '2026-09-26'
- target: $.paths['/audio/voice_consents'].get
  update:
    x-apievangelist-phrasing:
      intent: List voice consent recordings
      effect: read
      questions:
      - Which voice consent recordings has my organization uploaded for custom voices?
      - Can I page through all our custom-voice consent recordings?
      instructions:
      - text: List our voice consent recordings.
      - text: Show the first {limit} voice consent recordings.
        slots:
          limit: query.limit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/audio/voice_consents'].post
  update:
    x-apievangelist-phrasing:
      intent: Upload a voice consent recording
      effect: write
      questions:
      - What do I need to upload before I'm allowed to create a custom voice?
      - How do I submit a speaker's consent recording for voice cloning?
      instructions:
      - text: Upload consent recording {recording} named {name} in {language}.
        slots:
          recording: requestBody.recording
          name: requestBody.name
          language: requestBody.language
      - text: Register a voice consent called {name} from recording {recording}, spoken in {language}.
        slots:
          name: requestBody.name
          recording: requestBody.recording
          language: requestBody.language
      method: generated
      generated: '2026-09-26'
- target: $.paths['/audio/voice_consents/{consent_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve a voice consent recording
      effect: read
      questions:
      - What metadata is stored for one of our voice consent recordings?
      - Can I look up a single consent recording by its ID?
      instructions:
      - text: Get voice consent {consent_id}.
        slots:
          consent_id: path.consent_id
      - text: Show the metadata of consent recording {consent_id}.
        slots:
          consent_id: path.consent_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/audio/voice_consents/{consent_id}'].post
  update:
    x-apievangelist-phrasing:
      intent: Rename a voice consent recording
      effect: write
      questions:
      - Can I rename a consent recording without re-uploading the audio?
      - Does updating a voice consent replace its audio?
      instructions:
      - text: Rename voice consent {consent_id} to {name}.
        slots:
          consent_id: path.consent_id
          name: requestBody.name
      - text: Change the name on consent recording {consent_id} to {name}.
        slots:
          consent_id: path.consent_id
          name: requestBody.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/audio/voice_consents/{consent_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a voice consent recording
      effect: destructive
      questions:
      - How do I remove a speaker's consent recording if they withdraw permission?
      - Can I delete a voice consent recording we uploaded?
      instructions:
      - text: Delete voice consent {consent_id}.
        slots:
          consent_id: path.consent_id
      - text: Remove the consent recording {consent_id} permanently.
        slots:
          consent_id: path.consent_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/audio/voices'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a custom voice
      effect: write
      questions:
      - How do I create a custom voice to use in text-to-speech?
      - What does a custom voice need besides an audio sample?
      instructions:
      - text: Create a custom voice named {name} from sample {audio_sample} using consent {consent}.
        slots:
          name: requestBody.name
          audio_sample: requestBody.audio_sample
          consent: requestBody.consent
      - text: Build voice {name} from audio sample {audio_sample} backed by consent recording {consent}.
        slots:
          name: requestBody.name
          audio_sample: requestBody.audio_sample
          consent: requestBody.consent
      method: generated
      generated: '2026-09-26'