> ## 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 音訊中繼資料

> 以 id 查詢單一 Instagram 音訊曲目的詳細資料

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} />

以 `audioId` 擷取單一音訊曲目的詳細資料。可用來確認先前儲存的 id 是否仍然有效，或在發布前顯示曲目的標題與封面圖。

<InstagramAudioNotice />

## 標頭參數

<HeaderAPI />

## 路徑參數

<ParamField path="audioId" type="string" required>
  曲目 id，由[音訊搜尋](/docs/apis/media/search-instagram-audio)回傳。Instagram
  無法識別的 id 會回傳 `code: 517`。
</ParamField>

## 回應欄位

曲目的欄位會以扁平方式直接回傳在回應物件上，而非巢狀結構。Instagram 不會為每首曲目回傳所有欄位，因此除 `audioId` 以外的所有欄位都應視為選填。

<ResponseField name="status" type="string">找到曲目時為 `success`。</ResponseField>
<ResponseField name="audioId" type="string">曲目 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">
  該曲目是否可用於廣告。
</ResponseField>

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

  ```json 400: Track unavailable theme={"system"}
  {
    "status": "error",
    "code": 517,
    "action": "post",
    "message": "The selected audio track is unavailable. It may be an invalid audio id, restricted in your region, or not licensed for this use. Please choose a different track using the Instagram audio search endpoint and try again.",
    "platform": "instagram"
  }
  ```
</ResponseExample>

<Note>
  **可用性因地區而異。** 對於不存在的 id、在帳號所在地區未獲授權的 id，
  以及未獲此用途授權的 id，Meta 都會回傳相同的錯誤。三種情況都回報
  `517`，因此同一首曲目可能對某個帳號有效，對另一個帳號卻正當地失敗。
  請以查詢確認 id，而不要假設先前儲存的 id 仍然可用。
</Note>

## 錯誤

| Code | 意義                                                            |
| ---- | ------------------------------------------------------------- |
| 156  | Instagram 尚未連結至此 Profile。                                     |
| 161  | Instagram 的授權已過期或被撤銷。請重新連結帳號。                                 |
| 239  | Instagram 因帳號層級的原因拒絕了請求。                                      |
| 258  | Instagram 回傳了格式錯誤的回應或未對應的失敗。                                  |
| 425  | 此連結缺少必要的 Instagram 權限。請重新連結並授予所有權限。                           |
| 435  | 已達 Instagram 的速率限制。請稍候再重試。                                    |
| 514  | Instagram 是以 Instagram Login 連結的。Audio API 需要 Facebook Login。 |
| 516  | `audioId` 缺少或為空。                                              |
| 517  | Instagram 無法識別此 id，或此帳號無法使用該曲目。                               |

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

## 後續步驟

<Card title="搜尋曲目" icon="magnifying-glass" href="/docs/apis/media/search-instagram-audio" horizontal />

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