> ## Documentation Index
> Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 搜尋 Instagram 音訊

> 搜尋 Instagram 的授權音訊目錄，尋找可附加到 Reel 的曲目

export const InstagramAudioNotice = () => <Warning>
  <strong>Requires Instagram linked through Facebook Login.</strong> Instagram's Audio API is only available to accounts connected via <strong>Facebook Login</strong>, which needs a Facebook Page connected to the Instagram account. Accounts connected with <strong>Instagram Login</strong> (the Ayrshare default) cannot search, look up, or attach audio, and every audio request returns <code>code: 514</code>.
  <br /><br />
  This is a Meta restriction, not an Ayrshare one. Meta's documentation states the Audio API "is only available on the Instagram API with Facebook Login. It is not supported on the Instagram API with Instagram Login." No permission or plan upgrade changes it.
  <br /><br />
  <strong>Three things are required:</strong>
  <br />
  1. An Instagram <strong>Business</strong> or <strong>Creator</strong> account<br />
  2. A <strong>Facebook Page connected</strong> to that Instagram account<br />
  3. Instagram linked to Ayrshare with <strong>Instagram Login disabled</strong>, so the Facebook Login flow is used
  <br /><br />
  See the <a href="/docs/dashboard/connect-social-accounts/instagram#music-attach-eligibility-facebook-login-required">step-by-step setup guide</a>.
</Warning>;

export const PlansAvailable = ({plans = [], maxPackRequired}) => {
  let displayPlans = plans;
  if (plans && plans.length === 1) {
    const lowerCasePlan = plans[0].toLowerCase();
    if (lowerCasePlan === "business") {
      displayPlans = ["Launch", "Business", "Enterprise"];
    } else if (lowerCasePlan === "premium") {
      displayPlans = ["Premium", "Launch", "Business", "Enterprise"];
    }
  }
  return <Note>
Available on {displayPlans.length === 1 ? "the " : ""}
{displayPlans.join(", ").replace(/\b\w/g, l => l.toUpperCase())}{" "}
{displayPlans.length > 1 ? "plans" : "plan"}.

{maxPackRequired && <span onClick={() => window.open('https://www.ayrshare.com/docs/additional/maxpack', '_self')} className="flex items-center mt-2 cursor-pointer">
 <span className="px-1.5 py-0.5 rounded text-sm" style={{
    backgroundColor: '#C264B6',
    color: 'white',
    fontSize: '12px'
  }}>
   Max Pack required
 </span>
</span>}
</Note>;
};

export const HeaderAPI = ({noProfileKey, profileKeyRequired}) => <>
    <ParamField header="Authorization" type="string" required>
      <a href="/docs/apis/overview#authorization">API Key</a> of the Primary Profile.
      <br />
      <br />
      Format: <code>Authorization: Bearer API_KEY</code>
    </ParamField>
    {!noProfileKey && (profileKeyRequired ? <ParamField header="Profile-Key" type="string" required>
          <a href="/docs/apis/overview#profile-key-format">Profile Key</a> of a User Profile.
          <br />
          <br />
          Format: <code>Profile-Key: PROFILE_KEY</code>
        </ParamField> : <ParamField header="Profile-Key" type="string">
          <a href="/docs/apis/overview#profile-key-format">Profile Key</a> of a User Profile.
          <br />
          <br />
          Format: <code>Profile-Key: PROFILE_KEY</code>
        </ParamField>)}
  </>;

<PlansAvailable plans={["premium"]} maxPackRequired={false} />

以關鍵字搜尋 Instagram 的音訊目錄。將回傳的 `audioId` 搭配 [`instagramOptions.audioConfiguration`](/docs/apis/post/social-networks/instagram#adding-music-to-a-reel) 使用，即可在發布 Reel 時附加該曲目。

<InstagramAudioNotice />

## 標頭參數

<HeaderAPI />

## 查詢參數

<ParamField query="query" type="string" required>
  要搜尋的關鍵字，例如藝人或曲目名稱。空值或僅含空白字元的值會回傳
  `code: 101`。
</ParamField>

<ParamField query="audioType" type="string" default="music">
  要搜尋的目錄。`music` 代表授權的商業曲目，`original_sound` 代表取自
  其他創作者 Reels 的音訊。其他任何值會回傳 `code: 101`。
</ParamField>

<ParamField query="limit" type="integer">
  要回傳的曲目數量上限，介於 `1` 到 `100` 之間。非整數或超出範圍的值會回傳
  `code: 101`。省略時，套用 Instagram 自身的預設值。
</ParamField>

## 回應欄位

Instagram 不會為每首曲目回傳所有欄位，因此除 `audioId` 以外的所有曲目欄位都應視為選填。

<ResponseField name="status" type="string">
  搜尋完成時為 `success`。即使目錄中沒有符合項目，仍屬於成功。
</ResponseField>

<ResponseField name="query" type="string">
  所搜尋的關鍵字，原樣回傳。
</ResponseField>

<ResponseField name="audio" type="array">
  符合的曲目。空陣列代表搜尋已執行但沒有任何符合項目。

  <Expandable title="曲目欄位">
    <ResponseField name="audioId" type="string">
      發布 Reel 時作為 `audioConfiguration.audioId` 傳入的 id。
    </ResponseField>

    <ResponseField name="title" type="string">曲目標題。</ResponseField>
    <ResponseField name="displayArtist" type="string">Instagram 所顯示的藝人名稱。</ResponseField>
    <ResponseField name="durationMs" type="integer">曲目長度（毫秒）。</ResponseField>
    <ResponseField name="thumbnailUrl" type="string">封面圖縮圖 URL。</ResponseField>
    <ResponseField name="audioType" type="string">`music` 或 `original_sound`。</ResponseField>

    <ResponseField name="isAdsEligible" type="boolean">
      該曲目是否可用於廣告。授權音樂即使可用於自然觸及的 Reel，也經常
      無法用於廣告。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200: Success theme={"system"}
  {
    "status": "success",
    "query": "summer",
    "audio": [
      {
        "audioId": "17901234567890123",
        "title": "Summer Nights",
        "displayArtist": "The Example Band",
        "durationMs": 32000,
        "thumbnailUrl": "https://scontent.example.com/cover.jpg",
        "audioType": "music",
        "isAdsEligible": true
      }
    ]
  }
  ```

  ```json 200: No matches theme={"system"}
  {
    "status": "success",
    "query": "asdfghjkl",
    "audio": []
  }
  ```

  ```json 400: Instagram Login account theme={"system"}
  {
    "status": "error",
    "code": 514,
    "action": "post",
    "message": "Adding music to a Reel requires an Instagram account connected via Facebook Login. This profile is connected with Instagram Login, which Meta does not permit for music attach, search, or lookup. Please relink Instagram using Facebook Login and grant the instagram_content_publish permission, then try again.",
    "platform": "instagram"
  }
  ```
</ResponseExample>

## 錯誤

| Code | 意義                                                            |
| ---- | ------------------------------------------------------------- |
| 101  | `query` 缺少或為空、`audioType` 無法識別，或 `limit` 超出 1 到 100 的範圍。      |
| 156  | Instagram 尚未連結至此 Profile。                                     |
| 161  | Instagram 的授權已過期或被撤銷。請重新連結帳號。                                 |
| 239  | Instagram 因帳號層級的原因拒絕了請求，包括曲目無法使用。在搜尋端點上會回報 239，而非查詢端點回傳的 517。 |
| 258  | Instagram 回傳了格式錯誤的回應或未對應的失敗。                                  |
| 425  | 此連結缺少必要的 Instagram 權限。請重新連結並授予所有權限。                           |
| 435  | 已達 Instagram 的速率限制。請稍候再重試。                                    |
| 514  | Instagram 是以 Instagram Login 連結的。Audio API 需要 Facebook Login。 |

錯誤碼 514 到 518 的說明請參閱 [Instagram Reels 音訊錯誤](/docs/errors/errors-ayrshare#instagram-reels-audio-errors)；其餘錯誤碼請參閱 [Ayrshare 錯誤參考](/docs/errors/errors-ayrshare)。

## 後續步驟

<Card title="將曲目附加到 Reel" icon="music" href="/docs/apis/post/social-networks/instagram#adding-music-to-a-reel" horizontal />

<Card title="查詢單一曲目" icon="magnifying-glass" href="/docs/apis/media/get-instagram-audio" horizontal />