Back to Details

instagram

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Instagram API (Graph API)

Instagram API（Graph API）

Use the Instagram Graph API by directly executing 
curl
commands to read and publish Instagram content.
Official docs: 
https://developers.facebook.com/docs/instagram-api
通过直接执行
curl
命令使用Instagram Graph API来读取和发布Instagram内容。
官方文档：
https://developers.facebook.com/docs/instagram-api

When to Use

适用场景

Use this skill when you need to:
  • Fetch recent media (photos / videos / Reels) from an account
  • Get detailed information about a specific media item (caption, type, link, time, etc.)
  • Search recent media by hashtag
  • Publish image posts via API (with caption)
当你需要以下操作时使用该技能：
  • 从账户获取近期媒体内容（照片/视频/Reels）
  • 获取特定媒体项的详细信息（说明文字、类型、链接、时间等）
  • 按话题标签搜索近期媒体内容
  • 通过API发布图片帖子（带说明文字）

Prerequisites

前提条件

  1. You must have an Instagram Business / Creator account linked to a Facebook Page
  2. Create an app in Facebook Developers and enable Instagram Basic Display / Instagram Graph API permissions
  3. Obtain:
  • INSTAGRAM_ACCESS_TOKEN
    : a long-lived user access token
  • INSTAGRAM_BUSINESS_ACCOUNT_ID
    : your Instagram Business account ID
Set the environment variables, for example:
bash
export INSTAGRAM_ACCESS_TOKEN="EAAG..."
export INSTAGRAM_BUSINESS_ACCOUNT_ID="1784140xxxxxxx"
These examples use Graph API version 
v21.0
. You can replace this with the latest version if needed.
  1. 你必须拥有一个关联到Facebook主页的Instagram商家/创作者账户
  2. 在Facebook开发者平台创建应用，并启用Instagram Basic Display / Instagram Graph API权限
  3. 获取：
  • INSTAGRAM_ACCESS_TOKEN
    ：长期用户访问令牌
  • INSTAGRAM_BUSINESS_ACCOUNT_ID
    ：你的Instagram商家账户ID
设置环境变量，例如：
bash
export INSTAGRAM_ACCESS_TOKEN="EAAG..."
export INSTAGRAM_BUSINESS_ACCOUNT_ID="1784140xxxxxxx"
这些示例使用Graph API版本
v21.0
。如有需要，你可以替换为最新版本。

Required permissions (scopes)

所需权限（范围）

Depending on which endpoints you use, make sure your app has requested and been approved for (at least):
  • instagram_basic
  • pages_show_list
  • instagram_content_publish
    (for publishing media)
  • instagram_manage_insights
    and related permissions (for insights / some hashtag use cases)
Important: When using 
$VAR
in a command that pipes to another command, wrap the command containing 
$VAR
in 
bash -c '...'
. Due to a Claude Code bug, environment variables are silently cleared when pipes are used directly.
bash
bash -c 'curl -s "https://api.example.com" -H "Authorization: Bearer $API_KEY"' | jq '.'
根据你使用的端点，请确保你的应用已申请并获得（至少）以下权限：
  • instagram_basic
  • pages_show_list
  • instagram_content_publish
    （用于发布媒体内容）
  • instagram_manage_insights
    及相关权限（用于数据洞察/部分话题标签使用场景）
重要提示： 当在包含管道的命令中使用
$VAR
时，请将包含
$VAR
的命令用
bash -c '...'
包裹。由于Claude Code的一个bug，直接使用管道时环境变量会被静默清除。
bash
bash -c 'curl -s "https://api.example.com" -H "Authorization: Bearer $API_KEY"' | jq '.'

How to Use

使用方法

All examples below assume you have already set:
bash
INSTAGRAM_ACCESS_TOKEN
INSTAGRAM_BUSINESS_ACCOUNT_ID
以下所有示例均假设你已设置好：
bash
INSTAGRAM_ACCESS_TOKEN
INSTAGRAM_BUSINESS_ACCOUNT_ID

1. Fetch recent media for the account

1. 获取账户的近期媒体内容

Fetch the most recent media (photos / videos / Reels) for the account:
bash
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}"'
Notes:
  • Each item in the returned JSON represents a media object
  • Common fields: 
    • id
      : media ID (used for details / insights later)
    • caption
      : caption text
    • media_type
      : 
      IMAGE
      / 
      VIDEO
      / 
      CAROUSEL_ALBUM
    • media_url
      : direct URL to the media
    • permalink
      : Instagram permalink
    • timestamp
      : creation time
获取账户的最新媒体内容（照片/视频/Reels）：
bash
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
      ：媒体内容的直接链接
    • permalink
      ：Instagram永久链接
    • timestamp
      ：创建时间

2. Get details for a single media

2. 获取单个媒体内容的详情

If you already have a media 
id
, you can fetch more complete information. Replace 
<your-media-id>
with the 
id
field from the "Get User Media" response (section 1 above):
bash
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}"'
如果你已有媒体
id
，可以获取更完整的信息。将
<your-media-id>
替换为“获取用户媒体内容”响应（上文第1部分）中的
id
字段：
bash
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. Search media by hashtag

3. 按话题标签搜索媒体内容

Note: hashtag search requires proper business use cases and permissions as defined by Facebook/Instagram. Refer to the official docs.
This usually involves two steps:
注意：话题标签搜索需要符合Facebook/Instagram定义的合理商业使用场景及权限。请参考官方文档。
这通常分为两个步骤：

3.1 Get the hashtag ID

3.1 获取话题标签ID

Replace 
<hashtag-name>
with any hashtag name you want to search for (without the # symbol), e.g., "travel", "food", "photography":
bash
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}"'
Note the 
id
field in the returned JSON for use in the next step.
将
<hashtag-name>
替换为你要搜索的话题标签名称（不带#符号），例如“travel”、“food”、“photography”：
bash
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 Fetch recent media for the hashtag

3.2 获取话题标签的近期媒体内容

Replace 
<hashtag-id>
with the 
id
field from the "Search Hashtag" response (section 3.1 above):
bash
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}"'
将
<hashtag-id>
替换为“搜索话题标签”响应（上文第3.1部分）中的
id
字段：
bash
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. Publish an image post

4. 发布图片帖子

Publishing an image post via the Graph API usually requires two steps:
  1. Create a media container
  2. Publish the container to the feed
通过Graph API发布图片帖子通常需要两个步骤：
  1. 创建媒体容器
  2. 将容器发布到动态

4.1 Create a media container

4.1 创建媒体容器

Write the request data to 
/tmp/request.json
:
json
{
  "image_url": "https://example.com/image.jpg",
  "caption": "Hello from Instagram API 👋"
}
Replace 
https://example.com/image.jpg
with any publicly accessible image URL and update the caption text as needed.
bash
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}"'
The response will contain an 
id
(media container ID), for example:
json
{
  "id": "1790xxxxxxxxxxxx"
}
Note this ID for use in the next step.
将请求数据写入
/tmp/request.json
：
json
{
  "image_url": "https://example.com/image.jpg",
  "caption": "Hello from Instagram API 👋"
}
将
https://example.com/image.jpg
替换为任何可公开访问的图片链接，并根据需要更新说明文字。
bash
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），例如：
json
{
  "id": "1790xxxxxxxxxxxx"
}
记录该ID用于下一步操作。

4.2 Publish the media container to the feed

4.2 将媒体容器发布到动态

Write the request data to 
/tmp/request.json
:
json
{
  "creation_id": "<your-creation-id>"
}
Replace 
<your-creation-id>
with the 
id
field from the "Create Media Container" response (section 4.1 above):
bash
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}"'
If successful, the response will contain the final media 
id
:
json
{
  "id": "1791yyyyyyyyyyyy"
}
You can then use the "Get details for a single media" command to fetch its 
permalink
.
将请求数据写入
/tmp/request.json
：
json
{
  "creation_id": "<your-creation-id>"
}
将
<your-creation-id>
替换为“创建媒体容器”响应（上文第4.1部分）中的
id
字段：
bash
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
：
json
{
  "id": "1791yyyyyyyyyyyy"
}
之后你可以使用“获取单个媒体内容的详情”命令来获取其
permalink
。

5. Common errors and troubleshooting

5. 常见错误与故障排除

  1. Permissions / OAuth errors
  • Typical error message: 
    (#10) Application does not have permission for this action
  • Check:
  • Whether the app has been reviewed / approved
  • Whether the required Instagram permissions are enabled
  • Whether 
    INSTAGRAM_ACCESS_TOKEN
    is a valid long-lived token
  1. Unsupported account type
  • Most Graph API features require Business / Creator accounts
  • Make sure the Instagram account type is correct and linked to a Facebook Page
  1. Rate limits
  • Too many requests in a short period may hit rate limits; add delays for bulk operations
  1. 权限/OAuth错误
  • 典型错误信息：
    (#10) Application does not have permission for this action
  • 检查：
  • 应用是否已通过审核/获批
  • 是否已启用所需的Instagram权限
  • INSTAGRAM_ACCESS_TOKEN
    是否为有效的长期令牌
  1. 不支持的账户类型
  • 大多数Graph API功能需要商家/创作者账户
  • 确保Instagram账户类型正确且已关联到Facebook主页
  1. 速率限制
  • 短时间内请求过多可能会触发速率限制；批量操作时请添加延迟

Guidelines

注意事项

  1. Do not log tokens: 
    INSTAGRAM_ACCESS_TOKEN
    is sensitive; avoid printing it in logs or chat transcripts
  2. Validate curl commands in a test environment first: confirm flows before wiring them into automation / agents
  3. Keep API version up to date: periodically check Facebook docs and update the 
    v21.0
    version in URLs to the latest
  4. Use placeholder text for IDs: all examples use placeholder text like 
    <your-media-id>
    instead of shell variables in URLs to avoid dependencies and make examples self-contained
  1. 不要记录令牌：
    INSTAGRAM_ACCESS_TOKEN
    是敏感信息；避免在日志或聊天记录中打印它
  2. 先在测试环境验证curl命令：在将流程接入自动化/代理之前，先确认流程可用
  3. 保持API版本为最新：定期查看Facebook文档，将URL中的
    v21.0
    版本更新为最新版本
  4. 使用占位符表示ID：所有示例使用
    <your-media-id>
    等占位符而非Shell变量，以避免依赖并使示例独立可用