# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Sp Global Transcription API
  version: 1.0.0
extends: openapi/sp-global-transcription-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 7
- target: $.paths['/api/v1/transcription'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a v1 transcription job's result
      effect: read
      questions:
      - Is my v1 transcription job still pending or finished?
      - Can I get a v1 transcription result as WebVTT captions?
      instructions:
      - text: Get the result of v1 transcription job {unique_id}.
        slots:
          unique_id: path.unique_id
      - text: Check the status of the older v1 transcription {unique_id}.
        slots:
          unique_id: path.unique_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/transcription'].post
  update:
    x-apievangelist-phrasing:
      intent: Upload a file to the v1 transcription service
      effect: write
      questions:
      - How do I upload an MP3 directly to the v1 transcription endpoint?
      - Which audio content types does the v1 transcription upload accept?
      instructions:
      - text: Start a v1 transcription job by uploading {file}.
        slots:
          file: requestBody.file
      - text: Transcribe audio file {file} using the older v1 upload endpoint.
        slots:
          file: requestBody.file
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/transcription'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a v1 transcription job's data
      effect: destructive
      questions:
      - Can I delete all stored data for a v1 transcription job?
      - How do I remove an old v1 transcription once I'm done?
      instructions:
      - text: Delete v1 transcription job {unique_id}.
        slots:
          unique_id: path.unique_id
      - text: Erase all data stored for v1 job {unique_id}.
        slots:
          unique_id: path.unique_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/transcription'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a transcription of audio or video
      effect: write
      questions:
      - Can I transcribe a recording hosted at a URL and get a callback when done?
      - Is human-assisted transcription available instead of machine only?
      - What's the maximum file size for a new transcription request?
      instructions:
      - text: Transcribe the media at {media_url}.
        slots:
          media_url: requestBody.media_url
      - text: Start a {transcriber} transcription of {media_url} and notify {callback_uri} when finished.
        slots:
          transcriber: requestBody.transcriber
          media_url: requestBody.media_url
          callback_uri: requestBody.callback_uri
      - text: Transcribe uploaded media {media} in language {media_language}.
        slots:
          media: requestBody.media
          media_language: requestBody.media_language
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/transcription/{transcription_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Download a finished transcript
      effect: read
      questions:
      - Where do I download the transcript once my transcription completes?
      - Can I fetch the resulting transcript by its transcription ID?
      instructions:
      - text: Download transcription {transcription_id}.
        slots:
          transcription_id: path.transcription_id
      - text: Get the transcript text for request {transcription_id}.
        slots:
          transcription_id: path.transcription_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/transcription/{transcription_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete all data for a transcription
      effect: destructive
      questions:
      - Can I make sure a transcription's data is wiped from the system?
      - How do I delete a transcription request and its transcript?
      instructions:
      - text: Delete transcription {transcription_id}.
        slots:
          transcription_id: path.transcription_id
      - text: Wipe all stored data for transcription {transcription_id}.
        slots:
          transcription_id: path.transcription_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/transcription/{transcription_id}'].head
  update:
    x-apievangelist-phrasing:
      intent: Check if a transcript is ready to download
      effect: read
      questions:
      - Is my transcript ready to download yet?
      - Can I check availability of a transcription without downloading it?
      instructions:
      - text: Check whether transcription {transcription_id} is ready.
        slots:
          transcription_id: path.transcription_id
      - text: See if transcript {transcription_id} is available for download.
        slots:
          transcription_id: path.transcription_id
      method: generated
      generated: '2026-10-01'