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

> 使用 Instagram API 发布内容的选项

<Info>
  如果你在连接 Instagram 时遇到问题，请参见 [故障排除
  指南](/help-center/technical-support/facebook_or_instagram_linking_issues)。
</Info>

<Info>
  如果你的媒体托管在你控制的服务器或 CDN 上，请确保 Meta 的发布
  爬虫可以获取它。如果你看到 Ayrshare 错误代码 440（"社交网络无法从此 URL 下载媒体"）或错误代码 138 且详情中包含 "Restricted by robots.txt"，请参见 [Meta 媒体爬虫被阻止](/help-center/technical-support/meta_media_crawler_blocked)。
</Info>

<div class="video-container">
  <iframe width="380" height="200" src="https://www.youtube.com/embed/3F7mbVN0qrw" title="Posting to Instagram API" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" />
</div>

Instagram API 有以下要求和限制。

<ul class="custom-bullets">
  <li>
    与 Facebook 主页关联的商业或创作者 Instagram 账户 - [请参见
    此处](/dashboard/connect-social-accounts/instagram)。
  </li>

  <li>24 小时内仅允许 50 个 Instagram 帖子。参见下方的 `usedQuota`</li>

  <li>
    `post` 文本最多可以包含 *5 个话题标签*（例如 #wildtimes）和 *3 个用户名提及*
    （例如 @natgeo）。
  </li>

  <li>@mention 的 Instagram 用户会收到通知。</li>
  <li>帖子最多 2,200 个字符。</li>

  <li>
    支持多图/视频帖子，并作为轮播发送。最多可以发送 10 个视频和
    图片。
  </li>

  <li>
    Instagram 不支持通过 API 删除。删除必须在 Instagram
    应用中手动进行。
  </li>

  <li>
    如果你的 Reel 视频不是以已知的视频扩展名（如 mp4）结尾，请使用 `isVideo`
    参数。详情请参见 [/post 端点](/apis/post/post)。
  </li>

  <li>
    Instagram 还支持发送无帖子文本的媒体。如果你不希望包含帖子文本，
    请发送空字符串 `post: ""`。
  </li>

  <li>更多信息请参见 [Instagram 媒体指南](/media-guidelines/instagram) 和 [Instagram 授权](/dashboard/connect-social-accounts/instagram)。</li>
</ul>

## 发布到 Instagram

发布带有图片和话题标签的基本 Instagram 帖子的 JSON：

```json Instagram Post theme={"system"}
{
  "post": "The best IG ever #best #awesome https://www.instagram.com",
  "mediaUrls": ["https://img.ayrshare.com/012/gb.jpg"],
  "platforms": ["instagram"]
}
```

话题标签在 Instagram 帖子中可点击，但链接不可点击。

<Note>
  图片和视频的宽高比以及视频的时长对于成功发布到 Instagram 非常重要。如果不满足要求，帖子将被拒绝。

  [请参见图片和视频指南的 Instagram 部分](/media-guidelines/instagram)。
</Note>

## Instagram 商业或创作者账户

你的 Instagram 账户必须是商业或创作者账户，并且与 Facebook 主页相关联。设置是免费且简单的。

有关详细说明，请参见此处：

<Card title="Instagram 关联" icon="link" href="/dashboard/connect-social-accounts/instagram" horizontal />

## 图片和视频轮播

你可以将多张图片或 Reel 视频作为轮播发布到 Instagram；一个轮播最多可以使用 10 张图片或视频（合计）。
只需将额外的图片或视频添加到 `mediaUrls` 数组，轮播将自动创建。

```json Instagram Carousel Post theme={"system"}
{
  // Max 10 images or videos
  "mediaUrls": ["https://url.com/image.jpg", "https://url.com/video.mp4"]
}
```

<Note>
  视频 URL 必须以已知的扩展名（如 `mp4`）结尾。Instagram 轮播不支持 `isVideo` 参数
  。
</Note>

## Instagram Reels

在 Instagram 中，视频帖子被称为 Reel。
你可以使用以下可选的 `instagramOptions` 选项将视频发布到 Instagram Reels API。

```json Instagram Reels Options theme={"system"}
{
  "instagramOptions": {
    "shareReelsFeed": true,
    "audioName": "The Weeknd - Blinding Lights",
    "thumbNail": "https://img.ayrshare.com/012/gb.jpg", // if used, thumbNailOffset will be ignored.
    "thumbNailOffset": 30000
  }
}
```

<ul class="custom-bullets">
  <li>
    有关视频要求的详情，请参见 [Reels API 视频要求](/media-guidelines/instagram#reels)。
  </li>

  <li>
    `shareReelsFeed`：布尔值，设为 `true` 表示 Reel \_可以\_出现在
    **Feed** 和 **Reels** 标签中，设为 `false` 表示 Reel \_只能\_出现在 **Reels**
    标签中。该值是对 Instagram 你希望 Reel 出现位置的提示，但两个
    值都不能确定 Reel \_实际\_是否出现在 **Reels** 或 **Feed** 标签中，因为
    Reel 可能不满足合格要求或可能不会被 Instagram 的算法选中。
  </li>

  <li>
    `audioName`：Reels 媒体的音频音乐的字符串名称。只能重命名一次，
    或者在创建 reel 时或之后从音频页面。例如，`"The Weeknd - Blinding
            Lights"`。
  </li>

  <li>
    `thumbNail`：Reel 封面图片（缩略图）的字符串 URL。有关 thumbNail 的
    详情，请参见此处 [/apis/post/social-networks/instagram#reels-thumbnails](/apis/post/social-networks/instagram#reels-thumbnails)。
  </li>

  <li>
    `thumbNailOffset`：缩略图帧的偏移量（毫秒）。有关
    thumbNailOffset 的详情，请参见此处 [/apis/post/social-networks/instagram#reels-thumbnails](/apis/post/social-networks/instagram#reels-thumbnails)。
  </li>
</ul>

请参见 [Reels API 视频要求](/media-guidelines/instagram#reels) 或 [使用 Instagram Reels API 的示例](https://www.ayrshare.com/blog/instagram-reels-api-how-to-post-videos-to-reels-using-a-social-media-api/)。

你还可以设置 [Reels 封面 URL](/apis/post/social-networks/instagram#reels-thumbnails) 和 [位置和用户标签](/apis/post/social-networks/instagram#user-tags-and-locations)。

## 试用 Reels

试用 Reel 是仅在首次发布时向非关注者发布的 Reel，允许你在 Reel 到达现有关注者之前测试它在新观众中的表现。在 `instagramOptions` 中设置 `trialParams.graduationStrategy` 以将 Reel 作为试用发布。

```json Instagram Trial Reel theme={"system"}
{
  "post": "Testing this with a fresh audience first",
  "mediaUrls": ["https://img.ayrshare.com/random/portrait1.mp4"],
  "platforms": ["instagram"],
  "instagramOptions": {
    "trialParams": {
      "graduationStrategy": "MANUAL"
    }
  }
}
```

`graduationStrategy` 控制试用 reel 之后如何 "毕业" — 即也对你的关注者可见。当提供 `trialParams` 时它是必填的，必须是以下之一：

<ul class="custom-bullets">
  <li>
    <code>"MANUAL"</code> — 帖子保持为试用 reel，直到你从 Instagram
    应用内手动将其毕业。
  </li>

  <li>
    <code>"SS\_PERFORMANCE"</code> — Meta 根据对非关注者的早期表现自动将 Reel
    毕业。
  </li>
</ul>

<Note>
  毕业本身（将已发布的试用 reel 推广给关注者）目前未通过
  Meta 的 API 公开，必须在 Instagram 应用中手动执行。一旦 Meta 公开毕业端点，Ayrshare 将添加它。
</Note>

### 试用 Reel 限制

在以下任何条件不满足时，试用 Reel 请求将在 Ayrshare 边缘 — Meta 调用之前 — 被拒绝：

<ul class="custom-bullets">
  <li>正好一个以 <code>.mp4</code> 或 <code>.mov</code> 结尾的媒体 URL（不区分大小写）。不支持轮播。</li>
  <li><code>instagramOptions.stories</code> 不能为 <code>true</code>。Stories 不能是试用 reels。</li>
  <li><code>graduationStrategy</code> 必须存在且必须正好为 <code>"MANUAL"</code> 或 <code>"SS\_PERFORMANCE"</code>（区分大小写）。</li>
</ul>

失败会返回三种 Ayrshare 错误代码之一 — 有关完整负载，请参见 [Instagram 试用 Reel 错误](/errors/errors-ayrshare#instagram-specific-error-codes)（<code>447</code>、<code>448</code>、<code>449</code>）。

## Instagram Stories

你可以使用以下 `instagramOptions` 将单张图片或视频作为 Instagram Story 发布。Instagram stories 在 24 小时后消失。

```json Stories Post theme={"system"}
{
  "post": "The description of the video",
  "mediaUrls": ["https://img.ayrshare.com/random/portrait1.mp4"],
  "instagramOptions": {
    "stories": true
  }
}
```

请参见 [Stories API 要求](/media-guidelines/instagram#stories)。

<ul class="custom-bullets">
  <li>
    Instagram Stories 不支持帖子文本 - 在 `post` 字段中提供的任何文本，
    包括提及，都会被忽略。
  </li>

  <li>Stories 在 24 小时后过期。</li>

  <li>
    Instagram 目前仅支持在 Instagram 商业账户上发布 Story，不支持
    创作者账户。
  </li>

  <li>Instagram Stories 不支持协作者。</li>
  <li>Instagram 不支持发布贴纸（例如，链接、投票、位置）。</li>
</ul>

## Reels 缩略图

你可以选择 Reel 的一帧作为缩略图图片，或从外部 URL 选择你自己的封面图片（缩略图）。

```json Instagram Thumbnail theme={"system"}
{
  "instagramOptions": {
    // milliseconds
    "thumbNailOffset": 30000,
    // If both thumbNail and thumbNailOffset includes, thumbNail will be used.
    "thumbNail": "https://img.ayrshare.com/012/gb.jpg"
  }
}
```

偏移量是视频 Reel 的缩略图帧在毫秒中的位置。默认值为 `0`，即 Reel 的第一帧。

如果你同时指定了缩略图 URL 和缩略图偏移量，缩略图偏移量将被忽略。

Reel 缩略图必须遵循 [Reels 缩略图要求](/media-guidelines/instagram#reels-thumbnails)。
带重定向的签名 URL 不能保证与封面 URL 兼容。
我们建议使用非签名 URL 或使用 [/media 端点](/apis/media/overview)。

## 替代文本

为图片添加 Instagram 替代文本（也称为 alt text）。
Instagram 替代文本是一项无障碍功能，用于提供附加的用户信息并支持屏幕阅读器。

<ul class="custom-bullets">
  <li>替代文本每张图片最多支持 1,000 个字符。</li>
  <li>Instagram 不支持 Reels 或 Stories 的替代文本。</li>
</ul>

在 `instagramOptions` 对象中使用 `altText`。

```json Instagram Alt Text theme={"system"}
{
  "instagramOptions": {
    // Array of Alt Texts
    "altText": ["This is my best pic", "😃 here is the next one"]
  }
}
```

每条替代文本必须对应 `mediaUrls` 数组中的一张图片或一个视频。
替代文本将按顺序应用于每张图片。

## 用户标签和位置

<Info>
  当你在帖子中使用 Instagram 用户的用户名时，该用户会收到通知。请谨慎
  避免发送垃圾内容或反复用他们的用户名发帖。如果这样做，Instagram 可能会暂停或
  停用你的账户。
</Info>

可以使用 `instagramOptions` 参数为图片或 Reel 添加 Instagram 用户标签，为图片、视频或 Reel 添加位置标签。

### 位置

位置由 `locationId` 指定，它是 Facebook 主页 ID 或 Facebook 主页名称。例如，[Guggenheim Museum](https://www.facebook.com/guggenheimmuseum) 的 Facebook 主页 ID 是 `7640348500` 或 Facebook 主页名称 `"@guggenheimmuseum"`。主页必须与实际位置关联。

```json Instagram Location theme={"system"}
// Using the Facebook Page Id - must be associated with a location
{
    "instagramOptions": {
        "locationId": 7640348500 // Guggenheim Museum Page Id
    }
}

// Using the Facebook Page name - must be associated with a location
{
    "instagramOptions": {
        "locationId": "@guggenheimmuseum" // Guggenheim Museum Page name. Must begin with @
    }
}
```

你可以使用 [brand 端点](/apis/brand/overview) 查找 `locationId`（主页 ID）。请注意，该主页必须列出位置，否则 locationId 将返回错误。

<Note>轮播中的图片或视频不支持。</Note>

### 用户标签

Instagram 标签允许你在帖子中标记其他 Instagram 用户。
用户由 `userTags` 指定，它包含一个对象数组，每个对象有 Instagram 用户名和 x/y 坐标（仅图片）。可以为单张图片或 Reels 添加用户标签，但不能为常规视频、多张图片或 Stories 添加。

<ul class="custom-bullets">
  <li>用户名必须是公开的 Instagram 账户。不要包含用户名前面的 @。</li>

  <li>
    `x` 和 `y` 值必须是 `float` 数字，从图片左上角开始，
    范围为 `0.0`–`1.0`。仅单张图片。不要与 Reels 一起使用，否则会出错。
  </li>
</ul>

```json Instagram User Tags theme={"system"}
{
  "instagramOptions": {
    "userTags": [
      {
        "username": "ayrshare", // Required: Instagram username
        "x": 0.5, // Required for Images, cannot be used with Reels
        "y": 1.0 // Required for Images, cannot be used with Reels
      },
      {
        "username": "johnboy", // Required: Instagram username
        "x": 0.1, // Required for Images, cannot be used with Reels
        "y": 0.9 // Required for Images, cannot be used with Reels
      }
    ]
  }
}
```

## Instagram 提及

通过在帖子文本中添加 @handle 来提及其他 Instagram 用户。

例如，你可以在帖子文本中提及 @ayrshare 用户名：

```json Instagram Mentions theme={"system"}
{
  "post": "The best social media API @Ayrshare ever!", // empty string is allowed
  "mediaUrls": ["https://images.com/image.jpg"],
  "platforms": ["instagram"]
}
```

<Warning>
  被 `@mentioned` 的用户将收到提及通知。请查看提及功能的
  [重要规则](/testing/post-verification#mentions)。
</Warning>

## 协作

Instagram 协作允许你通过 [将他人标记为协作者](https://www.facebook.com/help/instagram/291200585956732) 与其他 Instagram 账户共同编写内容。
这允许你将其他 Instagram 用户指定为帖子的创作者。
被标记后，这些用户会在移动应用中收到协作邀请。
如果他们接受，帖子还会出现在他们的动态中并对他们的关注者可见，从而扩大帖子的影响力和互动潜力。

### 协作者

公开的原始作者可以将另一个公开账户标记为 Instagram 协作者。
另一个账户将收到一条消息，允许他们接受或拒绝请求。
如果另一个账户接受，帖子还将显示在他们的个人资料上，并分发到 Instagram 动态中他们的关注者。
帖子的标题将同时归属于两个账户。

你可以为 Reel、图片或轮播添加协作者。

通过 Instagram API 不允许标记私人协作者。虽然
这样的功能在 Instagram 应用内存在，但平台及其 API
通常不[功能对等](/help-center/product/are_social_networks_native_apps_and_the_apis_at_parity)。

<Warning>Instagram Stories 不支持协作者。</Warning>

<Warning>
  <ul class="custom-bullets">
    <li>**只邀请你预期会 `accept` 你邀请的协作者**。</li>

    <li>
      如果 [协作者
      响应](/apis/post/social-networks/instagram#get-collaborator-request-status) 为
      `declined` 协作请求，**在联系他们了解拒绝原因之前，请勿重新邀请他们**。
    </li>

    <li>
      同一或多个用户的反复拒绝将使你的 Instagram 和 Ayrshare 账户
      面临取消的风险。
    </li>

    <li>原始作者可以随时添加或删除协作者。</li>
  </ul>
</Warning>

使用公开 Instagram 用户名数组邀请\_最多三名\_协作者。

```json Instagram Collaborators theme={"system"}
{
  "instagramOptions": {
    "collaborators": ["ayrshare", "therock", "taylorswift"] // Up to three
  }
}
```

这三名协作者将在其 Instagram 移动应用中收到消息邀请，并可以接受或拒绝邀请，然后你可以[检查被邀请用户请求状态](/apis/post/social-networks/instagram#get-collaborator-request-status)。
请仅邀请你知道会接受你请求的协作者，否则你的 Instagram 账户可能会受到负面影响。

<Warning>
  关于被邀请协作者的说明：除了少数例外，只能通过 API 由
  发布媒体的用户访问关于共同编写媒体的数据；协作者无法通过
  API 访问此数据。
</Warning>

### 获取协作者请求状态

在邀请 Instagram 协作者后，你可以使用 [获取协作者请求状态 API](/apis/utils/instagram-get-collaborator) 检查请求的状态。

## 自动调整图片大小

<Note>需要 Max Pack</Note>

使用 `autoResize` 参数自动将图片调整为 1080 x 1080 像素，以适用于 Instagram。请注意，这会调整所有包含平台的图片大小，因此我们建议为 Instagram 进行一次调用，并为其他平台使用另一个 /post 调用。

```json Instagram Auto Image Resize theme={"system"}
{
  "post": "Let it go!",
  "platforms": ["instagram"],
  "mediaUrls": ["https://images.ayrshare.com/imgs/GhostBusters.jpg"],
  "instagramOptions": {
    "autoResize": true, // Max Pack
    "locationId": 7640348500,
    "userTags": [
      {
        "username": "ayrshare",
        "x": 0.5,
        "y": 0.5
      },
      {
        "username": "ayrshare",
        "x": 0.3,
        "y": 0.2
      }
    ]
  }
}
```

## 已使用配额

Instagram 响应将包括滚动 24 小时期间 Instagram 帖子数量的当前 `usedQuota`。Instagram 在滚动 24 小时期间仅允许 50 个 Instagram 帖子。

```json Instagram Used Quota theme={"system"}
{
    "status": "success",
    "errors": [],
    "postIds": [
        {
            "status": "success",
            "id": "17823977408036085",
            "postUrl": "https://www.instagram.com/p/CeBrkQuN1Kv/",
            "usedQuota": 15,
            "platform": "instagram"
        }
    ],
    "id": "l4FaPHSXWJNdmMfm3dIE",
    "refId": "65806e8d9efd78a58c05566a887043329dcdc76b",
    "post": "Luckily for Alice, the little magic bottle had now had its full effect."
}
```

如果达到配额，将返回错误消息。

## 内容问题

Ayrshare 包含内置的媒体保护，可以在发布过程中检测并解决某些媒体传送问题。当帖子成功但检测到并解决了内容问题时，响应包括一个可选的 `contentIssues` 对象。这允许你主动识别和修复你的媒体托管问题。

`contentIssues` 对象仅在检测到并解决问题时存在 — 正常成功的帖子不包含它。

| 字段                      | 类型               | 描述                                                                                                                                                       |
| ----------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `originMediaHostFailed` | boolean          | 社交网络无法从提供的 URL 检索媒体。Ayrshare 的自动化媒体保护解决了该问题并成功完成了帖子。考虑检查你的媒体托管配置 — 有关常见原因，请参见 [Meta 媒体爬虫被阻止](/help-center/technical-support/meta_media_crawler_blocked)。 |
| `details`               | array of strings | 每个检测到的问题的人类可读描述。                                                                                                                                         |

```json Content Issues Response Example theme={"system"}
{
    "status": "success",
    "errors": [],
    "postIds": [
        {
            "status": "success",
            "id": "17878176260289172",
            "postUrl": "https://www.instagram.com/p/CP1dI9Hp_WO/",
            "usedQuota": 12,
            "platform": "instagram",
            "contentIssues": {
                "originMediaHostFailed": true,
                "details": [
                    "Media URL could not be retrieved by the social network. Successfully posted using Ayrshare automated media protection."
                ]
            }
        }
    ],
    "id": "abc123",
    "refId": "65806e8d9efd78a58c05566a887043329dcdc76b",
    "post": "Your post text here"
}
```

<Tip>
  如果你在响应中看到 `originMediaHostFailed`，你的媒体托管可能存在问题，导致社交网络无法访问你的媒体。有关详细的故障排除步骤，请参见 [Meta 媒体爬虫被阻止](/help-center/technical-support/meta_media_crawler_blocked)。
</Tip>

## 错误详情

<Info>
  当 Instagram 媒体发布失败时，错误对象现在会在 `details` 字段中显示 Meta 的底层错误文本，同时提供 Ayrshare 的 `code` 和 `message`。这让你可以区分不同的根本原因（例如，宽高比拒绝与媒体下载失败），而无需联系支持。
</Info>

```json Instagram Publish Error theme={"system"}
{
    "status": "error",
    "errors": [
        {
            "action": "post",
            "status": "error",
            "platform": "instagram",
            "code": 156,
            "message": "An error occurred while posting to Instagram.",
            "details": "The submitted image was not found. The aspect ratio is not supported. Please see https://developers.facebook.com/docs/instagram-api for more information."
        }
    ]
}
```

`message` 是 Ayrshare 稳定的、人类可读的摘要，而 `details` 回显 Meta 为失败的发布返回的原始文本。

## 为 Instagram 帖子添加换行或富文本

Instagram 换行可以通过特殊的 [换行字符](/apis/post/post#line-breaks) 添加到帖子中。

富文本（如粗体或斜体字）可以通过一些 [html 元素](/apis/post/overview#rich-text-posts) 添加到 Instagram 帖子。

## 字符限制

更多信息请参见 [Instagram 字符限制](/help-center/technical-support/character_limits#instagram-character-limits)。

## 其他端点

<Card title="获取协作者请求状态" icon="code" href="/apis/utils/instagram-get-collaborator" horizontal />