Instagram Publish

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

⚠️ 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:

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