Instagram Publish

publish images to instagram through meta's graph api. the skill handles token validation, container creation, and publishing in one command. assumes meta app setup is complete and an access token is available.

intent

use this skill when you need to post a single image to instagram programmatically. trigger it when the user wants to automate instagram posting, push an image with caption to their account, set up instagram graph api access for the first time, or troubleshoot errors like "media download has failed" or "unsupported post request". the skill bundles three graph api calls (token validation, container creation, publish) into a single command. does not handle reels, stories, carousels, or local files.

inputs

meta graph api access:

• ACCESS_TOKEN: long-lived instagram graph api token (starts with IGAA). required. store in .env file as ACCESS_TOKEN=IGAAxxxx.... regenerate in meta app dashboard if expired or permissions change.
• IG_USER_ID: instagram user id (10-13 digits). optional. auto-detected from token validation step if omitted. can be passed via .env or retrieved manually at meta app dashboard under use cases.
• image_url: publicly reachable url to the image file (jpg, png). must be accessible by meta's servers without authentication. required per invocation.
• caption: text to post with the image (supports hashtags, mentions, newlines). optional. max length 2200 characters.
• .env file path: defaults to ./.env in script directory. can override with --env flag.

external connection:

• meta graph api v24.0+ endpoint: https://graph.instagram.com/. requires http outbound access. no proxy or firewall blocks on port 443.
• image hosting service: must be able to serve the image_url publicly (no auth required). examples: aws s3, github raw, alibaba oss, cloudflare, any cdn.

edge cases to handle:

• token expiry: long-lived tokens default to ~60 days. expired tokens return 401 on /me call.
• rate limits: meta applies 200 api calls per hour. hitting this returns 429 response.
• network timeout: image download can take 30+ seconds for large files. set socket timeout to 60 seconds.
• empty result sets: /me call returns no id field if token is invalid or revoked.

procedure

prerequisite: instagram account must be creator or business type (not personal). meta app created and token generated. see part 1 manual setup section below for one-time browser steps.

step 1: read and validate credentials

input: .env file or env vars.

• load ACCESS_TOKEN from .env or $ACCESS_TOKEN env var.
• load IG_USER_ID from .env or $IG_USER_ID env var (optional).
• if no token, exit with error message "access_token required. set in .env or $ACCESS_TOKEN env var".
• if token doesn't start with IGAA, warn user: "token format unexpected. should start with IGAA".

output: ACCESS_TOKEN, IG_USER_ID (or null if not provided).

step 2: validate token and fetch user id

input: ACCESS_TOKEN.

• make http get request to https://graph.instagram.com/v24.0/me?fields=id,username&access_token={ACCESS_TOKEN}.
• set connection timeout to 10 seconds, read timeout to 30 seconds.

if request succeeds (http 200):

• extract id and username from response json.
• if IG_USER_ID was null, set it to the id from response.
• print: "✓ token valid , user: {username} (id: {id})".

if request fails (http 401, 400, or network timeout):

• print error: "token validation failed: {error_message}. regenerate token in meta app dashboard and update .env".
• exit with failure code.

output: validated IG_USER_ID (string).

step 3: parse image url and caption

input: image_url (required), caption (optional string).

• if image_url is empty or not provided, exit with error "image_url required".
• if image_url does not start with http:// or https://, exit with error "image_url must be absolute http(s) url".
• if caption length exceeds 2200 characters, truncate and warn: "caption exceeds 2200 chars, truncating".
• trim whitespace from caption.

output: validated image_url, caption (string, may be empty).

step 4: create media container

input: ACCESS_TOKEN, IG_USER_ID, image_url, caption.

• make http post request to https://graph.instagram.com/v24.0/{IG_USER_ID}/media?image_url={image_url}&caption={caption}&access_token={ACCESS_TOKEN}.
• url-encode caption and image_url.
• set timeout to 60 seconds (image download can be slow).

if request succeeds (http 200):

• extract id from response json. this is the creation_id.
• print: "✓ container created: {creation_id}".

if request returns specific error messages:

• "media download has failed": image is not publicly accessible. print "media download failed. check that image_url is public and reachable without auth. test in incognito browser window".
• "unsupported post request": token lacks required permissions. print "token permissions insufficient. regenerate token with instagram_content_publish and instagram_basic scopes".
• other http 4xx or 5xx: print "container creation failed: {error_message}".

if network timeout or no response:

• print "container creation timed out after 60 seconds. image may be too large or url unreachable".
• exit with failure code.

output: creation_id (string).

step 5: publish media (skip if dry-run mode)

input: ACCESS_TOKEN, IG_USER_ID, creation_id, dry_run flag.

if --dry-run flag was passed:

• print: "dry-run mode: skipping publish step. token and container validated successfully".
• exit with success code.

if publish enabled:

• make http post request to https://graph.instagram.com/v24.0/{IG_USER_ID}/media_publish?creation_id={creation_id}&access_token={ACCESS_TOKEN}.
• set timeout to 30 seconds.

if request succeeds (http 200):

• extract id from response json. this is the post id.
• construct instagram post url: https://www.instagram.com/p/{post_id}.
• print: "✓ published: {post_id}" and the post url.

if request fails (http 4xx, 5xx, or timeout):

• print: "publish failed: {error_message}. container created but post not published. try again or check meta api status".
• exit with failure code.

output: post_id (string), instagram post url (string).

decision points

if access token missing or invalid: exit immediately with instruction to regenerate token in meta app dashboard. do not proceed to container creation.

if image url is not publicly reachable: stop at step 4. print diagnostic: "open image_url in incognito window. if you cannot see it, meta cannot either". do not retry.

if caption exceeds 2200 characters: truncate silently and warn user in output. do not fail the publish.

if --dry-run flag is set: skip step 5 (publish). validate token and create container only. exit with success after step 4.

if rate limit hit (http 429): print "api rate limit exceeded (200 calls per hour). retry in 5 minutes". exit with backoff code. do not retry automatically.

if token has expired (http 401 on /me call): do not attempt container creation. exit immediately with instruction to regenerate token. long-lived tokens expire after ~60 days.

if account type is not creator or business: this is caught during meta app setup (step 1 manual setup). the skill does not validate account type. if errors occur during container creation that suggest personal account, print "account may be personal. switch to creator or business account at https://www.instagram.com/accounts/professional_account_settings/".

output contract

on success:

✓ token valid ,  user: {username} (id: {ig_user_id})
✓ container created: {creation_id}
✓ published: {post_id}
https://www.instagram.com/p/{post_id}

output is printed to stdout. shell exit code is 0.

on failure, one of:

token validation failed: {error_message}

media download failed. check that image_url is public and reachable without auth.

token permissions insufficient. regenerate token with instagram_content_publish and instagram_basic scopes.

publish failed: {error_message}. container created but post not published.

on dry-run success:

✓ token valid ,  user: {username} (id: {ig_user_id})
✓ container created: {creation_id}
dry-run mode: skipping publish step. token and container validated successfully.

exit code is non-zero (1 or 4) on failure. shell scripts can check $? to determine success.

outcome signal

the user knows the skill worked when:

1. the script prints "✓ published:" with a post id.
2. the instagram post url is printed (e.g., https://www.instagram.com/p/ABC123XYZ/).
3. the user opens that url in a browser and sees the image and caption live on their instagram feed.
4. exit code is 0.

the user knows it failed if:

1. script exits with non-zero code.
2. one of the three checkmarks is missing from output.
3. error message describes the failure (token expired, image unreachable, rate limit, etc.).
4. instagram post does not appear in feed within 1 minute of script completion.

---

part 1: one-time manual setup (browser only)

these steps cannot be automated. they require human logins, email verification, and meta's ui. do them once, save the resulting ACCESS_TOKEN, and you never need to touch meta's dashboard again unless permissions change.

step 1: switch instagram to a creator account

visit https://www.instagram.com/accounts/professional_account_settings/ and follow:

Settings
  ↓
Account Type
  ↓
Switch to Professional Account
  ↓
Creator

step 2: create a meta developer account

visit https://developers.facebook.com/ and sign in with your facebook account, then:

Get Started
  ↓
Verify Email
  ↓
Accept Terms

step 3: create an app

visit https://developers.facebook.com/apps/:

Create App
  ↓
Use cases: Manage messaging & content on Instagram
  ↓
Do NOT connect a Business portfolio

warning: skipping the business portfolio avoids the "insufficient developer permissions" error later.

step 4: finish app settings

in App settings → Basic:

• upload an app icon.
• fill in privacy policy url and data deletion url.
• pick an app category.
• (optional) in Use cases → Customize, configure account linking at https://accountscenter.instagram.com/connected_experiences/.
• click Publish to make the app live.

step 5: generate the access token

Use cases → Customize
  ↓
Left sidebar: API setup with Instagram login
  ↓
Add required messaging permissions
  ↓
Add account → authorize your Instagram account
  ↓
Generate token
  ↓
Check "I understand" → copy the token

the token starts with IGAA.... save it to .env (next section).

credentials after part 1

field	example	location
ACCESS_TOKEN	IGAAxxxxx...	.env
IG_USER_ID	2700xxxxxx	.env (optional, auto-fetched)
USERNAME	xxxxx	reference only

warning: never commit .env to git. the token authenticates posts on your behalf.

---

part 2: automated publishing (the skill does this)

the three graph api calls below are bundled in scripts/publish.py. you run one command; the script runs all three.

[1] Validate token   →  GET /me?fields=id,username
       ↓
[2] Create container  →  POST /{ig_user_id}/media   (image_url + caption)
       ↓
[3] Publish           →  POST /{ig_user_id}/media_publish   (creation_id)

setting up .env

cp .env.example .env

.env contents:

ACCESS_TOKEN=IGAAxxxxxxxxxxxxxxxxxxxx
IG_USER_ID=2700xxxxxxxx        # optional, auto-detected if missing

the script reads .env from the skill directory. if you run it from elsewhere, pass --env /path/to/.env.

publishing an image

python3 scripts/publish.py \
  --image-url "https://example.com/photo.jpg" \
  --caption "Hello from Instagram API"

optional flags:

flag	default	notes
--image-url URL	required	must be publicly reachable by meta's servers
--caption TEXT	empty	instagram caption with hashtags and mentions
--env PATH	./.env	path to a .env file
--api-version	v24.0	graph api version
--dry-run	off	validate token and build container, skip final publish

successful output:

✓ token valid ,  user: xxxxx (id: 2700xxxxxx)
✓ container created: xxxxx
✓ published: xxxxx
https://www.instagram.com/p/xxxxxxxxx

---

common errors

"media download has failed"

{"error": {"message": "Media download has failed"}}

meta's servers cannot reach your image_url. fix:

• host the image somewhere public: alibaba cloud oss, aws s3, github raw, any cdn.
• open the url in a fresh browser while logged out. if you can't see it, meta can't either.
• avoid localhost, 127.0.0.1, and private network ips.
• check that the image file is not corrupted or missing.

"unsupported post request"

{"error": {"message": "Unsupported post request"}}

almost always a token permission issue. fix:

• back to Use cases → Customize in the app dashboard.
• confirm instagram_content_publish and instagram_basic are granted.
• regenerate the token and replace ACCESS_TOKEN in .env.

token expired

long-lived tokens still expire (default ~60 days). if /me returns an auth error, regenerate the token in the app dashboard and update .env.

rate limit exceeded

meta applies 200 api calls per hour per token. if you hit this, wait 60 minutes before retrying.

network timeout during image download

meta's servers may fail to download large images. if container creation times out, check image file size (keep under 20 mb) and test the url in a browser to confirm it is reachable.

---

files in this skill

instagram-publish/
├── SKILL.md            # this file
├── .env.example        # template for ACCESS_TOKEN and IG_USER_ID
├── .gitignore          # keeps .env out of git
└── scripts/
    └── publish.py      # the three-step publisher