API Evangelist conversational phrasing for X API v2 Media API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for X API v2 Media API
  version: 1.0.0
extends: openapi/x-media-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: 11
- target: $.paths['/2/media'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up several media items by key
      effect: read
      questions:
      - Can I get details for a batch of media keys in one call?
      - What type, size and URL info comes back for multiple media keys?
      instructions:
      - text: Get media details for keys {media_keys}.
        slots:
          media_keys: query.media_keys
      - text: 'Look up these media items together: {media_keys}.'
        slots:
          media_keys: query.media_keys
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/media/analytics'].get
  update:
    x-apievangelist-phrasing:
      intent: Get analytics for media items
      effect: read
      questions:
      - How are my uploaded videos performing over a date range?
      - Can I get media analytics broken down by hour or day?
      instructions:
      - text: Show analytics for media {media_keys} from {start_time} to {end_time}.
        slots:
          media_keys: query.media_keys
          start_time: query.start_time
          end_time: query.end_time
      - text: Get {granularity} media analytics for {media_keys} between {start_time} and {end_time}.
        slots:
          granularity: query.granularity
          media_keys: query.media_keys
          start_time: query.start_time
          end_time: query.end_time
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/media/metadata'].post
  update:
    x-apievangelist-phrasing:
      intent: Add metadata to uploaded media
      effect: write
      questions:
      - Can I attach extra metadata to an image after uploading it?
      - What call sets metadata on an existing media ID?
      instructions:
      - text: Add metadata {metadata} to media {id}.
        slots:
          metadata: requestBody.metadata
          id: requestBody.id
      - text: Attach metadata to uploaded media {id}.
        slots:
          id: requestBody.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/media/subtitles'].post
  update:
    x-apievangelist-phrasing:
      intent: Add subtitles to a video
      effect: write
      questions:
      - Can I attach subtitle files to a video I uploaded?
      - What's needed to add captions to a video's media ID?
      instructions:
      - text: Add subtitles {subtitles} to video {id}.
        slots:
          subtitles: requestBody.subtitles
          id: requestBody.id
      - text: Attach captions {subtitles} to {media_category} media {id}.
        slots:
          subtitles: requestBody.subtitles
          media_category: requestBody.media_category
          id: requestBody.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/media/subtitles'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove subtitles from a video
      effect: destructive
      questions:
      - How do I delete a subtitle track in a particular language from a video?
      - Can I remove captions I previously added to media?
      instructions:
      - text: Delete the {language_code} subtitles from {media_category} media {id}.
        slots:
          language_code: requestBody.language_code
          media_category: requestBody.media_category
          id: requestBody.id
      - text: Remove {language_code} captions on video {id} ({media_category}).
        slots:
          language_code: requestBody.language_code
          id: requestBody.id
          media_category: requestBody.media_category
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/media/upload'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a media upload's processing status
      effect: read
      questions:
      - Is my uploaded video still processing or ready to post?
      - How can I poll the status of a chunked media upload?
      instructions:
      - text: Check the upload status of media {media_id}.
        slots:
          media_id: query.media_id
      - text: Poll processing progress for upload {media_id}.
        slots:
          media_id: query.media_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/media/upload'].post
  update:
    x-apievangelist-phrasing:
      intent: Upload a media file in one request
      effect: write
      questions:
      - What's the simplest way to upload an image for a post in a single request?
      - Can I share an uploaded media file with other user accounts?
      instructions:
      - text: Upload {media} as {media_category} and give me its media key.
        slots:
          media: requestBody.media
          media_category: requestBody.media_category
      - text: Upload {media} as {media_category} and also grant access to {additional_owners}.
        slots:
          media: requestBody.media
          media_category: requestBody.media_category
          additional_owners: requestBody.additional_owners
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/media/upload/initialize'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a chunked media upload
      effect: write
      questions:
      - Where does a chunked upload for a large video begin?
      - What size and type details go into initializing a media upload?
      instructions:
      - text: Initialize a chunked upload of {total_bytes} bytes of type {media_type}.
        slots:
          total_bytes: requestBody.total_bytes
          media_type: requestBody.media_type
      - text: Start a {media_category} chunked upload for a {total_bytes}-byte file.
        slots:
          media_category: requestBody.media_category
          total_bytes: requestBody.total_bytes
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/media/upload/{id}/append'].post
  update:
    x-apievangelist-phrasing:
      intent: Append a chunk to a media upload
      effect: write
      questions:
      - Which segment index goes with each chunk of a media upload?
      - Can I send a large video to an upload session in pieces?
      instructions:
      - text: Append chunk {segment_index} ({media}) to media upload {id}.
        slots:
          segment_index: requestBody.segment_index
          media: requestBody.media
          id: path.id
      - text: Send segment {segment_index} of the file {media} into upload session {id}.
        slots:
          segment_index: requestBody.segment_index
          media: requestBody.media
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/media/upload/{id}/finalize'].post
  update:
    x-apievangelist-phrasing:
      intent: Finalize a chunked media upload
      effect: write
      questions:
      - What do I call after all chunks of a media upload are sent?
      - Does finalizing an upload make the media usable in posts?
      instructions:
      - text: Finalize media upload {id}.
        slots:
          id: path.id
      - text: Complete the chunked upload session {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/2/media/{media_key}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one media item by key
      effect: read
      questions:
      - Can I look up a single media item from its media key?
      - Which fields can I request for one piece of media?
      instructions:
      - text: Get media {media_key}.
        slots:
          media_key: path.media_key
      - text: Show media item {media_key} with fields {fields}.
        slots:
          media_key: path.media_key
          fields: query.media.fields
      method: generated
      generated: '2026-09-26'