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

## Header Parameters

<HeaderAPI />

## Path Parameters

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

## 错误代码

| 代码  | 含义                                                           |
| --- | ------------------------------------------------------------ |
| 156 | 该配置未关联 Instagram。                                            |
| 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 />