Instagram Publish

Use when publishing images to Instagram via the Graph API from a Creator or Business account. Triggers when the user wants to automate Instagram posting, push an image with caption to their account, set up Instagram API access for the first time, or troubleshoot Instagram Graph API errors like "Media download has failed" or "Unsupported post request". Assumes one-time Meta App setup is complete and an Access Token is available.

Publish images to Instagram through Meta's Graph API. Part 1 is one-time manual setup (browser clicks); Part 2 is the repeatable automated publish (this skill does it for you).

When to use

• User wants to post an image to Instagram programmatically
• User has a public image URL and wants to attach a caption and publish
• User just registered a Meta App and needs the rest of the wiring done
• User is hitting "Media download has failed" or "Unsupported post request"

When NOT to use

• Posting Reels, Stories, or Carousels (this skill handles single-image posts only)
• Local files (image must be a public URL — see error #1 below)
• Account is still a personal account (must be Creator or Business first)

Quick Start (after Part 1 setup is done)

# 1. Put credentials in .env (one time)
cp .env.example .env
# edit .env with ACCESS_TOKEN (and optionally IG_USER_ID)

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

The script prints the new post ID on success. Done.

---

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

⚠️ 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 you should have after Part 1

Field	Example	Lives in
ACCESS_TOKEN	IGAAxxxxx...	.env
IG_USER_ID	2700xxxxxx	.env (optional — script can auto-fetch)
USERNAME	xxxxx	reference only

⚠️ Never commit .env to git. The token is the only thing that 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's 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 the container, but skip the 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

"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
• Re-generate 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.

---

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