安装
npx skills add https://github.com/vm0-ai/vm0-skills --skill instagram
- 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)
- 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
- -c
- 'curl -s "https://api.example.com" -H "Authorization: Bearer $API_KEY"'
- |
- jq
- '.'
- 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:
- 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
- 2. Get details for a single media
- If you already have a media
- id
- , you can fetch more complete information. Replace
- with the
- id
- field from the "Get User Media" response (section 1 above):
- bash
- -c
- 'curl -s -X GET "https://graph.facebook.com/v21.0/?fields=id,caption,media_type,media_url,permalink,thumbnail_url,timestamp,username" --header "Authorization: Bearer ${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
- with any hashtag name you want to search for (without the # symbol), e.g., "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=" --header "Authorization: Bearer ${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
- with the
- id
- field from the "Search Hashtag" response (section 3.1 above):
- bash
- -c
- 'curl -s -X GET "https://graph.facebook.com/v21.0//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
- 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.
- 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:
- {
- "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"
- :
- ""
- }
- Replace
- with the
- id
- field from the "Create Media Container" response (section 4.1 above):
- 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
- :
- {
- "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
instead of shell variables in URLs to avoid dependencies and make examples self-contained
← 返回排行榜