Instagram Graph API 使用指南：读取与发布内容，获取媒体和话题标签数据

instagram by vm0-ai/vm0-skills

189 周安装量

52 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/vm0-ai/vm0-skills --skill instagram

社交网络营销 API

🇨🇳中文介绍

Instagram API (Graph API)

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

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

使用时机

当您需要时，请使用此技能：

从账户获取近期媒体内容（照片/视频/Reels）
获取特定媒体项目的详细信息（标题、类型、链接、时间等）
按话题标签搜索近期媒体内容
通过 API 发布图片帖子（附带标题）

先决条件

您必须拥有一个链接到 Facebook 主页的 Instagram 商业账户/创作者账户
在 Facebook 开发者平台创建一个应用，并启用 Instagram Basic Display / Instagram Graph API 权限
获取以下信息：

INSTAGRAM_ACCESS_TOKEN：一个长期有效的用户访问令牌
INSTAGRAM_BUSINESS_ACCOUNT_ID：您的 Instagram 商业账户 ID

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

所需权限（作用域）

根据您使用的端点，请确保您的应用已请求并获批（至少）以下权限：

instagram_basic
pages_show_list
instagram_content_publish（用于发布媒体）
instagram_manage_insights 及相关权限（用于洞察分析/某些话题标签用例）

以下所有示例均假设您已设置：

INSTAGRAM_ACCESS_TOKEN
INSTAGRAM_BUSINESS_ACCOUNT_ID

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

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

curl -s -X GET "https://graph.facebook.com/v21.0/$(printenv INSTAGRAM_BUSINESS_ACCOUNT_ID)/media?fields=id,caption,media_type,media_url,permalink,timestamp" --header "Authorization: Bearer $(printenv 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 字段：

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 $(printenv INSTAGRAM_ACCESS_TOKEN)"

3. 按话题标签搜索媒体

注意：话题标签搜索需要符合 Facebook/Instagram 定义的适当商业用例和权限。请参考官方文档。

这通常涉及两个步骤：

3.1 获取话题标签 ID

将 <hashtag-name> 替换为您想要搜索的任何话题标签名称（不带 # 符号），例如 "travel"、"food"、"photography"：

curl -s -X GET "https://graph.facebook.com/v21.0/ig_hashtag_search?user_id=$(printenv INSTAGRAM_BUSINESS_ACCOUNT_ID)&q=<hashtag-name>" --header "Authorization: Bearer $(printenv INSTAGRAM_ACCESS_TOKEN)"

记下返回的 JSON 中的 id 字段，用于下一步。

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

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

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

4. 发布图片帖子

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

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

4.1 创建媒体容器

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

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

将 https://example.com/image.jpg 替换为任何可公开访问的图片 URL，并根据需要更新标题文本。

curl -s -X POST "https://graph.facebook.com/v21.0/$(printenv INSTAGRAM_BUSINESS_ACCOUNT_ID)/media" -H "Content-Type: application/json" -d @/tmp/request.json --header "Authorization: Bearer $(printenv INSTAGRAM_ACCESS_TOKEN)"

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

{
  "id": "1790xxxxxxxxxxxx"
}

记下此 ID 用于下一步。

4.2 将媒体容器发布到动态

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

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

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

curl -s -X POST "https://graph.facebook.com/v21.0/$(printenv INSTAGRAM_BUSINESS_ACCOUNT_ID)/media_publish" -H "Content-Type: application/json" -d @/tmp/request.json --header "Authorization: Bearer $(printenv INSTAGRAM_ACCESS_TOKEN)"

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

{
  "id": "1791yyyyyyyyyyyy"
}

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

5. 常见错误与故障排除

权限 / OAuth 错误

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

不支持的账户类型

大多数 Graph API 功能需要商业/创作者账户
确保 Instagram 账户类型正确且已链接到 Facebook 主页

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

不要记录令牌：INSTAGRAM_ACCESS_TOKEN 是敏感信息；避免在日志或聊天记录中打印它
先在测试环境中验证 curl 命令：在将其集成到自动化流程/代理之前，先确认流程
保持 API 版本更新：定期检查 Facebook 文档，并将 URL 中的 v21.0 版本更新到最新
对 ID 使用占位符文本：所有示例都使用像 <your-media-id> 这样的占位符文本，而不是在 URL 中使用 shell 变量，以避免依赖并使示例自成一体

🇺🇸English

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

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)

Prerequisites

You must have an Instagram Business / Creator account linked to a Facebook Page
Create an app in Facebook Developers and enable Instagram Basic Display / Instagram Graph API permissions
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:

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.

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)

How to Use

All examples below assume you have already set:

INSTAGRAM_ACCESS_TOKEN
INSTAGRAM_BUSINESS_ACCOUNT_ID

1. Fetch recent media for the account

Fetch the most recent media (photos / videos / Reels) for the account:

curl -s -X GET "https://graph.facebook.com/v21.0/$(printenv INSTAGRAM_BUSINESS_ACCOUNT_ID)/media?fields=id,caption,media_type,media_url,permalink,timestamp" --header "Authorization: Bearer $(printenv 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

2. Get details for a single media

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

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 $(printenv INSTAGRAM_ACCESS_TOKEN)"

3. Search media by hashtag

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:

3.1 Get the hashtag ID

Replace <hashtag-name> with any hashtag name you want to search for (without the # symbol), e.g., "travel", "food", "photography":

curl -s -X GET "https://graph.facebook.com/v21.0/ig_hashtag_search?user_id=$(printenv INSTAGRAM_BUSINESS_ACCOUNT_ID)&q=<hashtag-name>" --header "Authorization: Bearer $(printenv INSTAGRAM_ACCESS_TOKEN)"

Note the id field in the returned JSON for use in the next step.

3.2 Fetch recent media for the hashtag

Replace <hashtag-id> with the id field from the "Search Hashtag" response (section 3.1 above):

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

4. Publish an image post

Publishing an image post via the Graph API usually requires two steps :

Create a media container
Publish the container to the feed

4.1 Create a media container

Write the request data to /tmp/request.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.

curl -s -X POST "https://graph.facebook.com/v21.0/$(printenv INSTAGRAM_BUSINESS_ACCOUNT_ID)/media" -H "Content-Type: application/json" -d @/tmp/request.json --header "Authorization: Bearer $(printenv INSTAGRAM_ACCESS_TOKEN)"

The response will contain an id (media container ID), for example:

{
  "id": "1790xxxxxxxxxxxx"
}

Note this ID for use in the next step.

4.2 Publish the media container to the feed

Write the request data to /tmp/request.json:

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

Replace <your-creation-id> with the id field from the "Create Media Container" response (section 4.1 above):

curl -s -X POST "https://graph.facebook.com/v21.0/$(printenv INSTAGRAM_BUSINESS_ACCOUNT_ID)/media_publish" -H "Content-Type: application/json" -d @/tmp/request.json --header "Authorization: Bearer $(printenv INSTAGRAM_ACCESS_TOKEN)"

If successful, the response will contain the final media id:

{
  "id": "1791yyyyyyyyyyyy"
}

You can then use the "Get details for a single media" command to fetch its permalink.

5. Common errors and troubleshooting

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

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

Rate limits

Too many requests in a short period may hit rate limits; add delays for bulk operations

Guidelines

Do not log tokens : INSTAGRAM_ACCESS_TOKEN is sensitive; avoid printing it in logs or chat transcripts
Validate curl commands in a test environment first : confirm flows before wiring them into automation / agents
Keep API version up to date : periodically check Facebook docs and update the v21.0 version in URLs to the latest
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

Weekly Installs

148

Repository

vm0-ai/vm0-skills

GitHub Stars

First Seen

Jan 24, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

Installed on

opencode123

gemini-cli121

codex119

github-copilot116

cursor116

amp115

社交媒体内容策略指南：创建、优化与互动全流程 | 营销技能

39,000 周安装

Instagram Graph API 使用指南：读取与发布内容，获取媒体和话题标签数据

🇨🇳中文介绍

Instagram API (Graph API)

使用时机

先决条件

相关 Skills

所需权限（作用域）

使用方法

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

2. 获取单个媒体的详细信息

3. 按话题标签搜索媒体

3.1 获取话题标签 ID

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

4. 发布图片帖子

4.1 创建媒体容器

4.2 将媒体容器发布到动态

5. 常见错误与故障排除

指南

🇺🇸English

Instagram API (Graph API)

When to Use

Prerequisites

Required permissions (scopes)

How to Use

1. Fetch recent media for the account

2. Get details for a single media

3. Search media by hashtag

3.1 Get the hashtag ID

3.2 Fetch recent media for the hashtag

4. Publish an image post

4.1 Create a media container

4.2 Publish the media container to the feed

5. Common errors and troubleshooting

Guidelines

最新 Skills