instagram

Instagram API（Graph API）

通过直接执行 curl 命令使用 Instagram Graph API，读取和发布 Instagram 内容。

官方文档：https://developers.facebook.com/docs/instagram-api

---

适用场景

在需要以下操作时使用此技能：

• 获取账户的最新媒体（照片 / 视频 / Reels）
• 获取特定媒体项目的详细信息（说明文字、类型、链接、时间等）
• 按主题标签搜索最新媒体
• 通过 API 发布图片帖子（附带说明文字）

---

前提条件

1. 你必须拥有一个已关联到 Facebook Page 的 Instagram Business / Creator 账户
2. 在 Facebook Developers 中创建应用，并启用 Instagram Basic Display / Instagram Graph API 权限
3. 获取：

• INSTAGRAM_ACCESS_TOKEN：长期有效的用户访问令牌
• INSTAGRAM_BUSINESS_ACCOUNT_ID：你的 Instagram Business 账户 ID

设置环境变量，例如：

export INSTAGRAM_ACCESS_TOKEN="EAAG..."
export INSTAGRAM_BUSINESS_ACCOUNT_ID="1784140xxxxxxx"

这些示例使用 Graph API 版本 v21.0。如有需要，可以替换为最新版本。

所需权限（范围）

根据你使用的端点，确保应用已申请并获批至少以下权限：

• instagram_basic
• pages_show_list
• instagram_content_publish（用于发布媒体）
• instagram_manage_insights 及相关权限（用于洞察数据 / 某些主题标签使用场景）

---

重要： 在将 $VAR 传递给另一个命令的管道命令中使用 $VAR 时，请使用 bash -c '...' 包装包含 $VAR 的命令。由于 Claude Code 的一个 bug，直接使用管道时环境变量会被静默清除。

bash -c 'curl -s "https://api.example.com" -H "Authorization: Bearer $API_KEY"' | jq '.'

使用方法

以下示例均假设你已设置：

INSTAGRAM_ACCESS_TOKEN
INSTAGRAM_BUSINESS_ACCOUNT_ID

1. 获取账户的最新媒体

获取账户的最新媒体（照片 / 视频 / Reels）：

bash -c 'curl -s -X GET "https://graph.facebook.com/v21.0/${INSTAGRAM_BUSINESS_ACCOUNT_ID}/media?fields=id,caption,media_type,media_url,permalink,timestamp" --header "Authorization: Bearer ${INSTAGRAM_ACCESS_TOKEN}"'

说明：

• 返回的 JSON 中，每个项目都代表一个媒体对象
• 常见字段：
  • id：媒体 ID（稍后用于获取详情 / 洞察数据）
  • caption：说明文字
  • media_type：IMAGE / VIDEO / CAROUSEL_ALBUM
  • media_url：媒体的直接 URL
  • permalink：Instagram 永久链接
  • timestamp：创建时间

---

2. 获取单个媒体的详情

如果你已有媒体 id，可以获取更完整的信息。将 <your-media-id> 替换为上方第 1 节“获取用户媒体”响应中的 id 字段：

bash -c 'curl -s -X GET "https://graph.facebook.com/v21.0/<your-media-id>?fields=id,caption,media_type,media_url,permalink,thumbnail_url,timestamp,username" --header "Authorization: Bearer ${INSTAGRAM_ACCESS_TOKEN}"'

---

3. 按主题标签搜索媒体

注意：主题标签搜索需要符合 Facebook/Instagram 规定的业务使用场景和权限。请参阅官方文档。

通常需要两个步骤：

3.1 获取主题标签 ID

将 <hashtag-name> 替换为你要搜索的任意主题标签名称（不带 # 符号），例如“travel”“food”“photography”：

bash -c 'curl -s -X GET "https://graph.facebook.com/v21.0/ig_hashtag_search?user_id=${INSTAGRAM_BUSINESS_ACCOUNT_ID}&q=<hashtag-name>" --header "Authorization: Bearer ${INSTAGRAM_ACCESS_TOKEN}"'

记下返回的 JSON 中的 id 字段，以便在下一步中使用。

3.2 获取该主题标签的最新媒体

将 <hashtag-id> 替换为上方第 3.1 节“搜索主题标签”响应中的 id 字段：

bash -c 'curl -s -X GET "https://graph.facebook.com/v21.0/<hashtag-id>/recent_media?user_id=${INSTAGRAM_BUSINESS_ACCOUNT_ID}&fields=id,caption,media_type,media_url,permalink,timestamp" --header "Authorization: Bearer ${INSTAGRAM_ACCESS_TOKEN}"'

---

4. 发布图片帖子

通过 Graph API 发布图片帖子通常需要 两个步骤：

1. 创建媒体容器
2. 将容器发布到动态

4.1 创建媒体容器

将请求数据写入 /tmp/request.json：

{
  "image_url": "https://example.com/image.jpg",
  "caption": "Hello from Instagram API 👋"
}

将 https://example.com/image.jpg 替换为任意可公开访问的图片 URL，并按需更新说明文字。

bash -c 'curl -s -X POST "https://graph.facebook.com/v21.0/${INSTAGRAM_BUSINESS_ACCOUNT_ID}/media" -H "Content-Type: application/json" -d @/tmp/request.json --header "Authorization: Bearer ${INSTAGRAM_ACCESS_TOKEN}"'

响应中会包含一个 id（媒体容器 ID），例如：

{
  "id": "1790xxxxxxxxxxxx"
}

记下此 ID，以便在下一步中使用。

4.2 将媒体容器发布到动态

将请求数据写入 /tmp/request.json：

{
  "creation_id": "<your-creation-id>"
}

将 <your-creation-id> 替换为“创建媒体容器”响应中的 id 字段（见上文第 4.1 节）：

bash -c 'curl -s -X POST "https://graph.facebook.com/v21.0/${INSTAGRAM_BUSINESS_ACCOUNT_ID}/media_publish" -H "Content-Type: application/json" -d @/tmp/request.json --header "Authorization: Bearer ${INSTAGRAM_ACCESS_TOKEN}"'

如果成功，响应将包含最终媒体 id：

{
  "id": "1791yyyyyyyyyyyy"
}

然后，您可以使用“获取单条媒体的详细信息”命令来获取其 permalink。

---

5. 常见错误与故障排除

1. 权限 / OAuth 错误

• 典型错误消息：(#10) Application does not have permission for this action
• 请检查：
• 应用是否已通过审核 / 获批
• 是否已启用所需的 Instagram 权限
• INSTAGRAM_ACCESS_TOKEN 是否为有效的长期令牌

2. 不支持的账户类型

• 大多数 Graph API 功能都要求使用 Business / Creator 账户
• 请确保 Instagram 账户类型正确，且已关联 Facebook 公共主页

3. 速率限制

• 短时间内请求过多可能会触发速率限制；批量操作时请添加延迟

---

指南

1. 不要记录令牌：INSTAGRAM_ACCESS_TOKEN 是敏感信息；避免将其输出到日志或聊天记录中
2. 先在测试环境中验证 curl 命令：在将流程接入自动化 / Agent 之前，先确认其运行情况
3. 保持 API 版本为最新：定期查看 Facebook 文档，并将 URL 中的 v21.0 更新为最新版本
4. 使用占位文本表示 ID：所有示例都使用 <your-media-id> 等占位文本，而不是在 URL 中使用 shell 变量，以避免依赖并使示例可独立使用