# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Transcriptfetch Transcripts API
  version: 1.0.0
extends: openapi/transcriptfetch-transcripts-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: 12
- target: $.paths['/api/v1/transcripts/video'].post
  update:
    x-apievangelist-phrasing:
      intent: Get a transcript for one video (v1)
      effect: write
      questions:
      - How do I get the transcript of a YouTube video with the v1 endpoint?
      - Can the v1 transcript call use only existing captions and skip audio transcription?
      - Can I get the v1 transcript as plain text instead of timestamped segments?
      instructions:
      - text: Fetch the transcript for {video} using the v1 transcript endpoint.
        slots:
          video: requestBody.video
      - text: Get the v1 transcript of {video} in {mode} mode.
        slots:
          video: requestBody.video
          mode: requestBody.mode
      - text: Transcribe {video} through v1 and POST the result to {callback_url} when audio transcription finishes.
        slots:
          video: requestBody.video
          callback_url: requestBody.callback_url
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/transcripts/channel'].post
  update:
    x-apievangelist-phrasing:
      intent: List a YouTube channel's videos (v1)
      effect: read
      questions:
      - What are the newest uploads on a YouTube channel, using the v1 channel listing?
      - Can I poll a channel on v1 for only videos newer than the last one I saw?
      instructions:
      - text: List the latest {limit} videos from YouTube channel {channel} via v1.
        slots:
          limit: requestBody.limit
          channel: requestBody.channel
      - text: Show uploads on channel {channel} newer than video {since_video_id} with the v1 endpoint.
        slots:
          channel: requestBody.channel
          since_video_id: requestBody.since_video_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/transcripts/playlist'].post
  update:
    x-apievangelist-phrasing:
      intent: List a YouTube playlist's videos (v1)
      effect: read
      questions:
      - Which videos are in a YouTube playlist, using the older v1 playlist endpoint?
      - How can I page through a long playlist on v1 with a cursor?
      instructions:
      - text: List the videos in playlist {playlist} using v1.
        slots:
          playlist: requestBody.playlist
      - text: Get the next page of v1 playlist {playlist} from cursor {cursor}.
        slots:
          playlist: requestBody.playlist
          cursor: requestBody.cursor
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/transcripts/search'].post
  update:
    x-apievangelist-phrasing:
      intent: Search YouTube videos by keyword (v1)
      effect: read
      questions:
      - Can I search YouTube by keyword with the v1 search endpoint?
      - What metadata comes back from a v1 YouTube keyword search?
      instructions:
      - text: Search YouTube for {query} using the v1 search endpoint.
        slots:
          query: requestBody.query
      - text: Return the top {limit} YouTube results for {query} via v1.
        slots:
          limit: requestBody.limit
          query: requestBody.query
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/transcripts/jobs/{jobId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check an audio-transcription job (v1)
      effect: read
      questions:
      - Is my v1 audio transcription job still processing or completed?
      - Does polling a v1 transcription job cost credits?
      instructions:
      - text: Check the status of v1 transcription job {jobId}.
        slots:
          jobId: path.jobId
      - text: Poll v1 job {jobId} and give me the transcript once it has completed.
        slots:
          jobId: path.jobId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v1/transcripts/batch'].post
  update:
    x-apievangelist-phrasing:
      intent: Fetch many transcripts at once (v1)
      effect: write
      questions:
      - How many videos can I transcribe in a single v1 batch request on my plan?
      - Am I charged for videos that fail in a v1 batch?
      instructions:
      - text: 'Fetch transcripts for these videos in one v1 batch: {video_ids}.'
        slots:
          video_ids: requestBody.video_ids
      - text: Run a v1 batch for {video_ids} using {mode} mode.
        slots:
          video_ids: requestBody.video_ids
          mode: requestBody.mode
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/transcripts/video'].post
  update:
    x-apievangelist-phrasing:
      intent: Get a transcript for a video or podcast (v2)
      effect: write
      questions:
      - How do I transcribe a Spotify or Apple Podcasts episode with v2?
      - Will a v2 podcast transcript tell me which speaker is talking?
      - Can I get a TikTok or Instagram video transcript with timestamps using the current API?
      instructions:
      - text: Get the v2 transcript for {video}.
        slots:
          video: requestBody.video
      - text: Transcribe podcast episode {video} with v2, returning timestamps set to {timestamps}.
        slots:
          video: requestBody.video
          timestamps: requestBody.timestamps
      - text: Fetch the v2 transcript of {video} in {mode} mode and deliver it to {callback_url}.
        slots:
          video: requestBody.video
          mode: requestBody.mode
          callback_url: requestBody.callback_url
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/transcripts/channel'].post
  update:
    x-apievangelist-phrasing:
      intent: List a channel, profile, show or feed's items (v2)
      effect: read
      questions:
      - Can I list the latest episodes of a podcast show or RSS feed with v2?
      - What are the recent posts on a TikTok or Instagram profile?
      - Is a v2 channel poll free when nothing new has been published?
      instructions:
      - text: List the newest {limit} items from {channel} using v2.
        slots:
          limit: requestBody.limit
          channel: requestBody.channel
      - text: Show only items on {channel} newer than {since_video_id} via the v2 channel endpoint.
        slots:
          channel: requestBody.channel
          since_video_id: requestBody.since_video_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/transcripts/playlist'].post
  update:
    x-apievangelist-phrasing:
      intent: List a playlist's videos or episodes (v2)
      effect: read
      questions:
      - Can I list the tracks or episodes in a Spotify playlist?
      - Which platforms does the v2 playlist listing support?
      instructions:
      - text: List everything in playlist {playlist} with v2.
        slots:
          playlist: requestBody.playlist
      - text: Get {limit} more items from v2 playlist {playlist} starting at cursor {cursor}.
        slots:
          limit: requestBody.limit
          playlist: requestBody.playlist
          cursor: requestBody.cursor
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/transcripts/search'].post
  update:
    x-apievangelist-phrasing:
      intent: Search videos or podcast episodes (v2)
      effect: read
      questions:
      - Can I search TikTok, Instagram or podcasts by keyword instead of only YouTube?
      - Which platforms can the v2 search cover?
      instructions:
      - text: Search {platform} for {query} using v2.
        slots:
          platform: requestBody.platform
          query: requestBody.query
      - text: Find podcast episodes about {query} with the v2 search.
        slots:
          query: requestBody.query
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/transcripts/jobs/{jobId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check an audio-transcription job (v2)
      effect: read
      questions:
      - Has my v2 transcription job finished or failed?
      - Why would a v2 job lookup return 404?
      instructions:
      - text: Get the status of v2 transcription job {jobId}.
        slots:
          jobId: path.jobId
      - text: Fetch the finished transcript from v2 job {jobId}.
        slots:
          jobId: path.jobId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/transcripts/batch'].post
  update:
    x-apievangelist-phrasing:
      intent: Fetch many transcripts at once (v2)
      effect: write
      questions:
      - What is the v2 batch size limit on Mega and Scale plans?
      - What happens to v2 batch entries that have no caption track?
      instructions:
      - text: Get transcripts for {video_ids} in a single v2 batch.
        slots:
          video_ids: requestBody.video_ids
      - text: Batch-fetch {video_ids} through v2 in {mode} mode.
        slots:
          video_ids: requestBody.video_ids
          mode: requestBody.mode
      method: generated
      generated: '2026-10-01'