late-sdk 0.0.710 → 0.0.712

data/lib/zernio-sdk/models/instagram_platform_data_audio_configuration.rb

@@ -0,0 +1,242 @@
+=begin
+#Zernio API
+
+#API reference for Zernio. Authenticate with a Bearer API key. Base URL: https://zernio.com/api 
+
+The version of the OpenAPI document: 1.0.4
+Contact: support@zernio.com
+Generated by: https://openapi-generator.tech
+Generator version: 7.19.0
+
+=end
+
+require 'date'
+require 'time'
+
+module Zernio
+  # Attach a licensed music track or original sound from the Instagram audio catalog to a Reel. Reels only (single video post, not a story or image). Requires an Instagram account connected via Facebook Login; classic Instagram Login accounts get a 400 (instagram_audio_requires_facebook_login). Get audio IDs from GET /v1/accounts/{accountId}/instagram/audio. If the track becomes unavailable by publish time (removed, region-blocked, licensing change), the post fails with a user-error; it is not published without the audio.
+  class InstagramPlatformDataAudioConfiguration < ApiModelBase
+    # Audio asset ID from the audio search endpoint.
+    attr_accessor :audio_id
+
+    # Volume of the attached audio track, 0-100. Defaults to 100.
+    attr_accessor :audio_volume
+
+    # Volume of the video's own sound, 0-100. Defaults to 100. Set 0 to mute the original video audio.
+    attr_accessor :video_volume
+
+    # Attribute mapping from ruby-style variable name to JSON key.
+    def self.attribute_map
+      {
+        :'audio_id' => :'audioId',
+        :'audio_volume' => :'audioVolume',
+        :'video_volume' => :'videoVolume'
+      }
+    end
+
+    # Returns attribute mapping this model knows about
+    def self.acceptable_attribute_map
+      attribute_map
+    end
+
+    # Returns all the JSON keys this model knows about
+    def self.acceptable_attributes
+      acceptable_attribute_map.values
+    end
+
+    # Attribute type mapping.
+    def self.openapi_types
+      {
+        :'audio_id' => :'String',
+        :'audio_volume' => :'Integer',
+        :'video_volume' => :'Integer'
+      }
+    end
+
+    # List of attributes with nullable: true
+    def self.openapi_nullable
+      Set.new([
+      ])
+    end
+
+    # Initializes the object
+    # @param [Hash] attributes Model attributes in the form of hash
+    def initialize(attributes = {})
+      if (!attributes.is_a?(Hash))
+        fail ArgumentError, "The input argument (attributes) must be a hash in `Zernio::InstagramPlatformDataAudioConfiguration` initialize method"
+      end
+
+      # check to see if the attribute exists and convert string to symbol for hash key
+      acceptable_attribute_map = self.class.acceptable_attribute_map
+      attributes = attributes.each_with_object({}) { |(k, v), h|
+        if (!acceptable_attribute_map.key?(k.to_sym))
+          fail ArgumentError, "`#{k}` is not a valid attribute in `Zernio::InstagramPlatformDataAudioConfiguration`. Please check the name to make sure it's valid. List of attributes: " + acceptable_attribute_map.keys.inspect
+        end
+        h[k.to_sym] = v
+      }
+
+      if attributes.key?(:'audio_id')
+        self.audio_id = attributes[:'audio_id']
+      else
+        self.audio_id = nil
+      end
+
+      if attributes.key?(:'audio_volume')
+        self.audio_volume = attributes[:'audio_volume']
+      end
+
+      if attributes.key?(:'video_volume')
+        self.video_volume = attributes[:'video_volume']
+      end
+    end
+
+    # Show invalid properties with the reasons. Usually used together with valid?
+    # @return Array for valid properties with the reasons
+    def list_invalid_properties
+      warn '[DEPRECATED] the `list_invalid_properties` method is obsolete'
+      invalid_properties = Array.new
+      if @audio_id.nil?
+        invalid_properties.push('invalid value for "audio_id", audio_id cannot be nil.')
+      end
+
+      if !@audio_volume.nil? && @audio_volume > 100
+        invalid_properties.push('invalid value for "audio_volume", must be smaller than or equal to 100.')
+      end
+
+      if !@audio_volume.nil? && @audio_volume < 0
+        invalid_properties.push('invalid value for "audio_volume", must be greater than or equal to 0.')
+      end
+
+      if !@video_volume.nil? && @video_volume > 100
+        invalid_properties.push('invalid value for "video_volume", must be smaller than or equal to 100.')
+      end
+
+      if !@video_volume.nil? && @video_volume < 0
+        invalid_properties.push('invalid value for "video_volume", must be greater than or equal to 0.')
+      end
+
+      invalid_properties
+    end
+
+    # Check to see if the all the properties in the model are valid
+    # @return true if the model is valid
+    def valid?
+      warn '[DEPRECATED] the `valid?` method is obsolete'
+      return false if @audio_id.nil?
+      return false if !@audio_volume.nil? && @audio_volume > 100
+      return false if !@audio_volume.nil? && @audio_volume < 0
+      return false if !@video_volume.nil? && @video_volume > 100
+      return false if !@video_volume.nil? && @video_volume < 0
+      true
+    end
+
+    # Custom attribute writer method with validation
+    # @param [Object] audio_id Value to be assigned
+    def audio_id=(audio_id)
+      if audio_id.nil?
+        fail ArgumentError, 'audio_id cannot be nil'
+      end
+
+      @audio_id = audio_id
+    end
+
+    # Custom attribute writer method with validation
+    # @param [Object] audio_volume Value to be assigned
+    def audio_volume=(audio_volume)
+      if audio_volume.nil?
+        fail ArgumentError, 'audio_volume cannot be nil'
+      end
+
+      if audio_volume > 100
+        fail ArgumentError, 'invalid value for "audio_volume", must be smaller than or equal to 100.'
+      end
+
+      if audio_volume < 0
+        fail ArgumentError, 'invalid value for "audio_volume", must be greater than or equal to 0.'
+      end
+
+      @audio_volume = audio_volume
+    end
+
+    # Custom attribute writer method with validation
+    # @param [Object] video_volume Value to be assigned
+    def video_volume=(video_volume)
+      if video_volume.nil?
+        fail ArgumentError, 'video_volume cannot be nil'
+      end
+
+      if video_volume > 100
+        fail ArgumentError, 'invalid value for "video_volume", must be smaller than or equal to 100.'
+      end
+
+      if video_volume < 0
+        fail ArgumentError, 'invalid value for "video_volume", must be greater than or equal to 0.'
+      end
+
+      @video_volume = video_volume
+    end
+
+    # Checks equality by comparing each attribute.
+    # @param [Object] Object to be compared
+    def ==(o)
+      return true if self.equal?(o)
+      self.class == o.class &&
+          audio_id == o.audio_id &&
+          audio_volume == o.audio_volume &&
+          video_volume == o.video_volume
+    end
+
+    # @see the `==` method
+    # @param [Object] Object to be compared
+    def eql?(o)
+      self == o
+    end
+
+    # Calculates hash code according to all attributes.
+    # @return [Integer] Hash code
+    def hash
+      [audio_id, audio_volume, video_volume].hash
+    end
+
+    # Builds the object from hash
+    # @param [Hash] attributes Model attributes in the form of hash
+    # @return [Object] Returns the model itself
+    def self.build_from_hash(attributes)
+      return nil unless attributes.is_a?(Hash)
+      attributes = attributes.transform_keys(&:to_sym)
+      transformed_hash = {}
+      openapi_types.each_pair do |key, type|
+        if attributes.key?(attribute_map[key]) && attributes[attribute_map[key]].nil?
+          transformed_hash["#{key}"] = nil
+        elsif type =~ /\AArray<(.*)>/i
+          # check to ensure the input is an array given that the attribute
+          # is documented as an array but the input is not
+          if attributes[attribute_map[key]].is_a?(Array)
+            transformed_hash["#{key}"] = attributes[attribute_map[key]].map { |v| _deserialize($1, v) }
+          end
+        elsif !attributes[attribute_map[key]].nil?
+          transformed_hash["#{key}"] = _deserialize(type, attributes[attribute_map[key]])
+        end
+      end
+      new(transformed_hash)
+    end
+
+    # Returns the object in the form of hash
+    # @return [Hash] Returns the object in the form of hash
+    def to_hash
+      hash = {}
+      self.class.attribute_map.each_pair do |attr, param|
+        value = self.send(attr)
+        if value.nil?
+          is_nullable = self.class.openapi_nullable.include?(attr)
+          next if !is_nullable || (is_nullable && !instance_variable_defined?(:"@#{attr}"))
+        end
+
+        hash[param] = _to_hash(value)
+      end
+      hash
+    end
+
+  end
+
+end

data/lib/zernio-sdk/models/search_instagram_audio200_response.rb

@@ -0,0 +1,149 @@
+=begin
+#Zernio API
+
+#API reference for Zernio. Authenticate with a Bearer API key. Base URL: https://zernio.com/api 
+
+The version of the OpenAPI document: 1.0.4
+Contact: support@zernio.com
+Generated by: https://openapi-generator.tech
+Generator version: 7.19.0
+
+=end
+
+require 'date'
+require 'time'
+
+module Zernio
+  class SearchInstagramAudio200Response < ApiModelBase
+    attr_accessor :audio
+
+    # Attribute mapping from ruby-style variable name to JSON key.
+    def self.attribute_map
+      {
+        :'audio' => :'audio'
+      }
+    end
+
+    # Returns attribute mapping this model knows about
+    def self.acceptable_attribute_map
+      attribute_map
+    end
+
+    # Returns all the JSON keys this model knows about
+    def self.acceptable_attributes
+      acceptable_attribute_map.values
+    end
+
+    # Attribute type mapping.
+    def self.openapi_types
+      {
+        :'audio' => :'Array<InstagramAudioAsset>'
+      }
+    end
+
+    # List of attributes with nullable: true
+    def self.openapi_nullable
+      Set.new([
+      ])
+    end
+
+    # Initializes the object
+    # @param [Hash] attributes Model attributes in the form of hash
+    def initialize(attributes = {})
+      if (!attributes.is_a?(Hash))
+        fail ArgumentError, "The input argument (attributes) must be a hash in `Zernio::SearchInstagramAudio200Response` initialize method"
+      end
+
+      # check to see if the attribute exists and convert string to symbol for hash key
+      acceptable_attribute_map = self.class.acceptable_attribute_map
+      attributes = attributes.each_with_object({}) { |(k, v), h|
+        if (!acceptable_attribute_map.key?(k.to_sym))
+          fail ArgumentError, "`#{k}` is not a valid attribute in `Zernio::SearchInstagramAudio200Response`. Please check the name to make sure it's valid. List of attributes: " + acceptable_attribute_map.keys.inspect
+        end
+        h[k.to_sym] = v
+      }
+
+      if attributes.key?(:'audio')
+        if (value = attributes[:'audio']).is_a?(Array)
+          self.audio = value
+        end
+      end
+    end
+
+    # Show invalid properties with the reasons. Usually used together with valid?
+    # @return Array for valid properties with the reasons
+    def list_invalid_properties
+      warn '[DEPRECATED] the `list_invalid_properties` method is obsolete'
+      invalid_properties = Array.new
+      invalid_properties
+    end
+
+    # Check to see if the all the properties in the model are valid
+    # @return true if the model is valid
+    def valid?
+      warn '[DEPRECATED] the `valid?` method is obsolete'
+      true
+    end
+
+    # Checks equality by comparing each attribute.
+    # @param [Object] Object to be compared
+    def ==(o)
+      return true if self.equal?(o)
+      self.class == o.class &&
+          audio == o.audio
+    end
+
+    # @see the `==` method
+    # @param [Object] Object to be compared
+    def eql?(o)
+      self == o
+    end
+
+    # Calculates hash code according to all attributes.
+    # @return [Integer] Hash code
+    def hash
+      [audio].hash
+    end
+
+    # Builds the object from hash
+    # @param [Hash] attributes Model attributes in the form of hash
+    # @return [Object] Returns the model itself
+    def self.build_from_hash(attributes)
+      return nil unless attributes.is_a?(Hash)
+      attributes = attributes.transform_keys(&:to_sym)
+      transformed_hash = {}
+      openapi_types.each_pair do |key, type|
+        if attributes.key?(attribute_map[key]) && attributes[attribute_map[key]].nil?
+          transformed_hash["#{key}"] = nil
+        elsif type =~ /\AArray<(.*)>/i
+          # check to ensure the input is an array given that the attribute
+          # is documented as an array but the input is not
+          if attributes[attribute_map[key]].is_a?(Array)
+            transformed_hash["#{key}"] = attributes[attribute_map[key]].map { |v| _deserialize($1, v) }
+          end
+        elsif !attributes[attribute_map[key]].nil?
+          transformed_hash["#{key}"] = _deserialize(type, attributes[attribute_map[key]])
+        end
+      end
+      new(transformed_hash)
+    end
+
+    # Returns the object in the form of hash
+    # @return [Hash] Returns the object in the form of hash
+    def to_hash
+      hash = {}
+      self.class.attribute_map.each_pair do |attr, param|
+        value = self.send(attr)
+        if value.nil?
+          is_nullable = self.class.openapi_nullable.include?(attr)
+          next if !is_nullable || (is_nullable && !instance_variable_defined?(:"@#{attr}"))
+        end
+
+        hash[param] = _to_hash(value)
+      end
+      hash
+    end
+
+  end
+
+end

data/lib/zernio-sdk/version.rb

@@ -11,5 +11,5 @@ Generator version: 7.19.0
 =end
 
 module Zernio
-  VERSION = '0.0.710'
+  VERSION = '0.0.712'
 end

data/lib/zernio-sdk.rb

@@ -605,6 +605,7 @@ require 'zernio-sdk/models/get_inbox_volume200_response_summary'
 require 'zernio-sdk/models/get_inbox_volume200_response_timeseries_inner'
 require 'zernio-sdk/models/get_inbox_volume400_response'
 require 'zernio-sdk/models/get_instagram_account_insights404_response'
+require 'zernio-sdk/models/get_instagram_audio200_response'
 require 'zernio-sdk/models/get_instagram_follow_status200_response'
 require 'zernio-sdk/models/get_instagram_publishing_limit200_response'
 require 'zernio-sdk/models/get_instagram_story_insights200_response'
@@ -795,9 +796,11 @@ require 'zernio-sdk/models/instagram_account_insights_response_metrics_value'
 require 'zernio-sdk/models/instagram_account_insights_response_metrics_value_breakdowns_inner'
 require 'zernio-sdk/models/instagram_account_insights_response_metrics_value_values_inner'
 require 'zernio-sdk/models/instagram_account_insights_response_unavailable_metrics_inner'
+require 'zernio-sdk/models/instagram_audio_asset'
 require 'zernio-sdk/models/instagram_demographics_response'
 require 'zernio-sdk/models/instagram_demographics_response_demographics_value_inner'
 require 'zernio-sdk/models/instagram_platform_data'
+require 'zernio-sdk/models/instagram_platform_data_audio_configuration'
 require 'zernio-sdk/models/instagram_platform_data_trial_params'
 require 'zernio-sdk/models/instagram_platform_data_user_tags_inner'
 require 'zernio-sdk/models/like_inbox_comment200_response'
@@ -1152,6 +1155,7 @@ require 'zernio-sdk/models/search_inbox_conversations200_response_data_inner_mat
 require 'zernio-sdk/models/search_inbox_conversations200_response_meta'
 require 'zernio-sdk/models/search_inbox_conversations200_response_meta_accounts_skipped_inner'
 require 'zernio-sdk/models/search_inbox_conversations200_response_meta_failed_accounts_inner'
+require 'zernio-sdk/models/search_instagram_audio200_response'
 require 'zernio-sdk/models/search_reddit200_response'
 require 'zernio-sdk/models/search_tweets200_response'
 require 'zernio-sdk/models/search_tweets200_response_meta'

data/openapi.yaml

@@ -4873,8 +4873,29 @@ components:
                 example: 0
         audioName:
           type: string
-          description: Custom name for original audio in Reels. Replaces the default "Original Audio" label. Can only be set once.
+          description: 'Custom name for original audio in Reels. Replaces the default "Original Audio" label. Can only be set once. Unrelated to audioConfiguration, which attaches a catalog track.'
           example: "My Podcast Intro"
+        audioConfiguration:
+          type: object
+          description: 'Attach a licensed music track or original sound from the Instagram audio catalog to a Reel. Reels only (single video post, not a story or image). Requires an Instagram account connected via Facebook Login; classic Instagram Login accounts get a 400 (instagram_audio_requires_facebook_login). Get audio IDs from GET /v1/accounts/{accountId}/instagram/audio. If the track becomes unavailable by publish time (removed, region-blocked, licensing change), the post fails with a user-error; it is not published without the audio.'
+          required: [audioId]
+          properties:
+            audioId:
+              type: string
+              description: 'Audio asset ID from the audio search endpoint.'
+              example: "482851939985510"
+            audioVolume:
+              type: integer
+              minimum: 0
+              maximum: 100
+              description: 'Volume of the attached audio track, 0-100. Defaults to 100.'
+              example: 80
+            videoVolume:
+              type: integer
+              minimum: 0
+              maximum: 100
+              description: 'Volume of the video''s own sound, 0-100. Defaults to 100. Set 0 to mute the original video audio.'
+              example: 100
         thumbOffset:
           type: integer
           minimum: 0
@@ -4894,6 +4915,25 @@ components:
           description: When true, the post is labeled by Instagram as containing AI-generated media. Per Meta, this self-disclosure label is for AI-generated media, not AI-written captions. Applies to feed posts, Reels, Stories, and carousels.
       description: Feed aspect ratio 0.8-1.91, carousels up to 10 items, stories require media (no captions). User tag coordinates 0.0-1.0 from top-left. Images over 8 MB and videos over platform limits are auto-compressed.
 
+    InstagramAudioAsset:
+      type: object
+      description: 'One asset from the Instagram audio catalog. Licensed music carries artist/artwork fields; original sounds carry creator fields instead, so most fields are nullable.'
+      properties:
+        audioId:
+          type: string
+          description: 'Audio asset ID. Pass it as platformSpecificData.audioConfiguration.audioId when creating a Reel.'
+          example: "482851939985510"
+        title: { type: [string, "null"], description: 'Track or sound title.' }
+        audioType: { type: [string, "null"], enum: [music, original_sound, null], description: 'Catalog type of the asset.' }
+        durationInMs: { type: [integer, "null"], description: 'Asset duration in milliseconds.' }
+        displayArtist: { type: [string, "null"], description: 'Artist name (licensed music only).' }
+        coverArtworkThumbnailUrl: { type: [string, "null"], description: 'Cover artwork thumbnail (licensed music only).' }
+        downloadUrl: { type: [string, "null"], description: 'Temporary preview URL. Meta expires it after roughly 1.5 days; re-fetch the asset to refresh it.' }
+        igUsername: { type: [string, "null"], description: 'Creator username (original sounds only).' }
+        profilePictureUrl: { type: [string, "null"], description: 'Creator profile picture (original sounds only).' }
+        isAdsEligible: { type: [boolean, "null"], description: 'Whether the asset is eligible for ads use.' }
+        onPlatformAudioPreviewLink: { type: [string, "null"], description: 'Instagram web link to preview the audio.' }
+
     LinkedInPlatformData:
       type: object
       properties:
@@ -6870,20 +6910,20 @@ components:
           description: "Return on ad spend — derived as `purchaseValue / spend`. 0 when `spend` is 0. Equivalent to Meta's `purchase_roas` under default attribution. At ad-set and campaign levels this is recomputed from summed purchaseValue + spend (NOT averaged across children) so it's mathematically correct at every rollup level."
         videoPlayActions:
           type: integer
-          description: "Meta video ads only (0 for non-video ads and other platforms), like all video* fields below. Number of times the video started playing (Meta `video_play_actions`), summed over the date range and across children at ad-set/campaign level."
-        video30SecWatchedActions: { type: integer, description: "Views of at least 30 seconds (or to the end, for shorter videos). Meta `video_30_sec_watched_actions`." }
-        videoThruplayWatchedActions: { type: integer, description: "ThruPlays (watched to completion, or at least 15 seconds). Meta `video_thruplay_watched_actions`." }
-        videoP25WatchedActions: { type: integer, description: "Views reaching 25% of the video's length. With the other percentile fields, powers hook/hold/drop-off analysis (e.g. hook rate = videoP25WatchedActions / videoPlayActions). Meta `video_p25_watched_actions`." }
-        videoP50WatchedActions: { type: integer, description: "Views reaching 50% of the video's length. Meta `video_p50_watched_actions`." }
-        videoP75WatchedActions: { type: integer, description: "Views reaching 75% of the video's length. Meta `video_p75_watched_actions`." }
-        videoP95WatchedActions: { type: integer, description: "Views reaching 95% of the video's length. Meta `video_p95_watched_actions`." }
-        videoP100WatchedActions: { type: integer, description: "Views reaching 100% of the video's length. Meta `video_p100_watched_actions`." }
+          description: "Number of times the video started playing, summed over the date range and across children at ad-set/campaign level. 0 for non-video ads. Sources: Meta `video_play_actions`, TikTok `video_play_actions`."
+        video30SecWatchedActions: { type: integer, description: "Views of at least 30 seconds (or to the end, for shorter videos). Sources: Meta `video_30_sec_watched_actions` (Meta only)." }
+        videoThruplayWatchedActions: { type: integer, description: "ThruPlays (watched to completion, or at least 15 seconds). Sources: Meta `video_thruplay_watched_actions` (Meta only)." }
+        videoP25WatchedActions: { type: integer, description: "Views reaching 25% of the video's length. With the other percentile fields, powers hook/hold/drop-off analysis (e.g. hook rate = videoP25WatchedActions / videoPlayActions). Sources: Meta `video_p25_watched_actions`, TikTok `video_views_p25`." }
+        videoP50WatchedActions: { type: integer, description: "Views reaching 50% of the video's length. Sources: Meta `video_p50_watched_actions`, TikTok `video_views_p50`." }
+        videoP75WatchedActions: { type: integer, description: "Views reaching 75% of the video's length. Sources: Meta `video_p75_watched_actions`, TikTok `video_views_p75`." }
+        videoP95WatchedActions: { type: integer, description: "Views reaching 95% of the video's length. Sources: Meta `video_p95_watched_actions` (Meta only)." }
+        videoP100WatchedActions: { type: integer, description: "Views reaching 100% of the video's length. Sources: Meta `video_p100_watched_actions`, TikTok `video_views_p100`." }
         videoAvgTimeWatchedActions:
           type: number
-          description: "Average seconds watched per play (Meta `video_avg_time_watched_actions`). Aggregated over date ranges and across children as a play-weighted average (total watch time / total plays), never a plain average of averages."
+          description: "Average seconds watched per play. Aggregated over date ranges and across children as a play-weighted average (total watch time / total plays), never a plain average of averages. Sources: Meta `video_avg_time_watched_actions`, TikTok `average_video_play`."
         costPerThruplay:
           type: number
-          description: "Derived `spend / videoThruplayWatchedActions`, in ad-account native currency. Rounded to 4 decimals rather than the usual 2 because a ThruPlay routinely costs well under a cent. 0 when the ad has no ThruPlays."
+          description: "Derived `spend / videoThruplayWatchedActions`, in ad-account native currency. Rounded to 4 decimals rather than the usual 2 because a ThruPlay routinely costs well under a cent. 0 when the ad has no ThruPlays (ThruPlay is Meta-only)."
         funnel:
           $ref: '#/components/schemas/AdFunnelCounts'
         engagementBreakdown:
@@ -20591,6 +20631,96 @@ paths:
         '404': { description: Account not found }
         '502': { description: Instagram rejected the request }
 
+  /v1/accounts/{accountId}/instagram/audio:
+    get:
+      x-resource-group: "accounts"
+      operationId: searchInstagramAudio
+      tags: [Instagram]
+      summary: Search Instagram audio
+      description: |
+        Search Instagram's audio catalog (licensed music or original sounds),
+        or list what is currently trending by omitting `q`. Returns up to ~30
+        assets; Meta exposes no pagination on this edge.
+
+        Pass the returned `audioId` as
+        `platformSpecificData.audioConfiguration.audioId` when creating a Reel
+        to publish it with that track.
+
+        Requires an Instagram account connected via **Facebook Login**. Meta
+        hosts this catalog on graph.facebook.com only, so accounts connected
+        with classic Instagram Login receive a 400
+        (`instagram_audio_requires_facebook_login`) and must be reconnected
+        choosing the Facebook option.
+      parameters:
+        - name: accountId
+          in: path
+          required: true
+          description: The ID of the Instagram account
+          schema: { type: string }
+        - name: audioType
+          in: query
+          required: true
+          description: 'Catalog to search: licensed music or original sounds from Reels.'
+          schema: { type: string, enum: [music, original_sound] }
+        - name: q
+          in: query
+          required: false
+          description: 'Search keywords. Omit to get the current trending list.'
+          schema: { type: string, minLength: 1, maxLength: 200 }
+      responses:
+        '200':
+          description: Matching audio assets (may be empty)
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  audio:
+                    type: array
+                    items: { $ref: '#/components/schemas/InstagramAudioAsset' }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { description: Account not found }
+        '502': { description: Instagram rejected the request }
+
+  /v1/accounts/{accountId}/instagram/audio/{audioId}:
+    get:
+      x-resource-group: "accounts"
+      operationId: getInstagramAudio
+      tags: [Instagram]
+      summary: Get Instagram audio metadata
+      description: |
+        Fetch one audio asset's metadata by ID. Use it to re-validate a stored
+        `audioId` before a scheduled Reel publishes, or to refresh the preview
+        `downloadUrl` (Meta expires preview URLs after roughly 1.5 days).
+
+        Same connection requirement as the search endpoint: Facebook-Login
+        Instagram accounts only.
+      parameters:
+        - name: accountId
+          in: path
+          required: true
+          description: The ID of the Instagram account
+          schema: { type: string }
+        - name: audioId
+          in: path
+          required: true
+          description: Instagram audio asset ID
+          schema: { type: string, pattern: '^\d{1,30}$' }
+      responses:
+        '200':
+          description: The audio asset
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  audio: { $ref: '#/components/schemas/InstagramAudioAsset' }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '401': { $ref: '#/components/responses/Unauthorized' }
+        '404': { description: Account not found }
+        '502': { description: Instagram rejected the request }
+
   /v1/accounts/{accountId}/instagram/stories/{storyId}/insights:
     get:
       x-resource-group: "analytics"

data/spec/api/instagram_api_spec.rb

@@ -32,6 +32,19 @@ describe 'InstagramApi' do
     end
   end
 
+  # unit tests for get_instagram_audio
+  # Get Instagram audio metadata
+  # Fetch one audio asset's metadata by ID. Use it to re-validate a stored `audioId` before a scheduled Reel publishes, or to refresh the preview `downloadUrl` (Meta expires preview URLs after roughly 1.5 days).  Same connection requirement as the search endpoint: Facebook-Login Instagram accounts only. 
+  # @param account_id The ID of the Instagram account
+  # @param audio_id Instagram audio asset ID
+  # @param [Hash] opts the optional parameters
+  # @return [GetInstagramAudio200Response]
+  describe 'get_instagram_audio test' do
+    it 'should work' do
+      # assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
+    end
+  end
+
   # unit tests for get_instagram_publishing_limit
   # Get Instagram publishing limit
   # Returns the account's remaining content-publishing quota for Instagram's rolling 24-hour window, so you can pace publishing and warn before the cap is reached.  `quotaUsage` counts containers published since the start of the window. Always compare against the returned `quotaTotal` rather than hardcoding a number: Meta's prose documentation and the live API disagree on the value, and the live value is authoritative. 
@@ -69,4 +82,18 @@ describe 'InstagramApi' do
     end
   end
 
+  # unit tests for search_instagram_audio
+  # Search Instagram audio
+  # Search Instagram's audio catalog (licensed music or original sounds), or list what is currently trending by omitting `q`. Returns up to ~30 assets; Meta exposes no pagination on this edge.  Pass the returned `audioId` as `platformSpecificData.audioConfiguration.audioId` when creating a Reel to publish it with that track.  Requires an Instagram account connected via **Facebook Login**. Meta hosts this catalog on graph.facebook.com only, so accounts connected with classic Instagram Login receive a 400 (`instagram_audio_requires_facebook_login`) and must be reconnected choosing the Facebook option. 
+  # @param account_id The ID of the Instagram account
+  # @param audio_type Catalog to search: licensed music or original sounds from Reels.
+  # @param [Hash] opts the optional parameters
+  # @option opts [String] :q Search keywords. Omit to get the current trending list.
+  # @return [SearchInstagramAudio200Response]
+  describe 'search_instagram_audio test' do
+    it 'should work' do
+      # assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
+    end
+  end
+
 end