# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: 'API Evangelist conversational phrasing for Microsoft Azure Custom Speech Transcriptions: API'
  version: 1.0.0
extends: openapi/microsoft-azure-custom-speech-transcriptions-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: 8
- target: $.paths['/transcriptions/locales'].get
  update:
    x-apievangelist-phrasing:
      intent: List locales supported for batch transcription
      effect: read
      questions:
      - Which languages can offline transcription handle?
      - Is a given locale supported for batch speech transcription?
      instructions:
      - text: List the locales supported for transcriptions.
      - text: Show which languages batch transcription supports.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/transcriptions'].get
  update:
    x-apievangelist-phrasing:
      intent: List my transcriptions
      effect: read
      questions:
      - What transcription jobs have I submitted on this subscription?
      - Can I page through my transcriptions with skip and take?
      instructions:
      - text: List my transcriptions.
      - text: Show {take} transcriptions starting after {skip}.
        slots:
          take: query.take
          skip: query.skip
      method: generated
      generated: '2026-09-26'
- target: $.paths['/transcriptions'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a batch transcription of recordings
      effect: write
      questions:
      - How do I transcribe a set of audio recordings stored at a URL?
      - Can I choose a custom model and locale for a new transcription?
      instructions:
      - text: Transcribe the recordings at {recordingsUrl} in {locale} and name it {name}.
        slots:
          recordingsUrl: requestBody.recordingsUrl
          locale: requestBody.locale
          name: requestBody.name
      - text: Create transcription {name} for {recordingsUrl} with locale {locale} and description {description}.
        slots:
          name: requestBody.name
          recordingsUrl: requestBody.recordingsUrl
          locale: requestBody.locale
          description: requestBody.description
      method: generated
      generated: '2026-09-26'
- target: $.paths['/transcriptions/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a transcription's status
      effect: read
      questions:
      - Has my transcription finished yet?
      - What's the status of one transcription by ID?
      instructions:
      - text: Get transcription {id}.
        slots:
          id: path.id
      - text: Check the status of transcription {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/transcriptions/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a transcription
      effect: destructive
      questions:
      - Can I delete a transcription task and its results?
      - How do I clean up old transcriptions?
      instructions:
      - text: Delete transcription {id}.
        slots:
          id: path.id
      - text: Remove the transcription task {id} permanently.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/transcriptions/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Rename or redescribe a transcription
      effect: write
      questions:
      - Can I rename a transcription after it's been created?
      - Which details of a transcription can I edit?
      instructions:
      - text: Rename transcription {id} to {name}.
        slots:
          id: path.id
          name: requestBody.name
      - text: Set transcription {id}'s name to {name} and description to {description}.
        slots:
          id: path.id
          name: requestBody.name
          description: requestBody.description
      method: generated
      generated: '2026-09-26'
- target: $.paths['/transcriptions/{id}/files'].get
  update:
    x-apievangelist-phrasing:
      intent: List a transcription's result files
      effect: read
      questions:
      - Where do I download the result files of a finished transcription?
      - Can I control how long the file download links stay valid?
      instructions:
      - text: List the result files of transcription {id}.
        slots:
          id: path.id
      - text: List files of transcription {id} with links valid for {sasValidityInSeconds} seconds.
        slots:
          id: path.id
          sasValidityInSeconds: query.sasValidityInSeconds
      method: generated
      generated: '2026-09-26'
- target: $.paths['/transcriptions/{id}/files/{fileId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one file from a transcription
      effect: read
      questions:
      - Can I fetch a single result file from a transcription by file ID?
      - How do I get the download link for one transcript file?
      instructions:
      - text: Get file {fileId} from transcription {id}.
        slots:
          fileId: path.fileId
          id: path.id
      - text: Get a {sasValidityInSeconds}-second download link for file {fileId} of transcription {id}.
        slots:
          sasValidityInSeconds: query.sasValidityInSeconds
          fileId: path.fileId
          id: path.id
      method: generated
      generated: '2026-09-26'