instagram

Instagram API（Graph API）

curl コマンドを直接実行して Instagram Graph API を使用し、Instagram コンテンツの読み取りと公開を行います。

公式ドキュメント：https://developers.facebook.com/docs/instagram-api

---

使用する場面

次の操作が必要な場合に、このスキルを使用してください。

• アカウントの最新のメディア（写真／動画／Reels）を取得する
• 特定のメディアに関する詳細情報（キャプション、種類、リンク、日時など）を取得する
• ハッシュタグで最新のメディアを検索する
• API 経由で画像投稿を公開する（キャプション付き）

---

前提条件

1. Facebook ページにリンクされた Instagram ビジネスアカウント／クリエイターアカウントが必要です
2. Facebook Developers でアプリを作成し、Instagram Basic Display／Instagram Graph APIの権限を有効にします
3. 次の情報を取得します。

• INSTAGRAM_ACCESS_TOKEN：有効期間の長いユーザーアクセストークン
• INSTAGRAM_BUSINESS_ACCOUNT_ID：Instagram ビジネスアカウント ID

次の例のように、環境変数を設定します。

export INSTAGRAM_ACCESS_TOKEN="EAAG..."
export INSTAGRAM_BUSINESS_ACCOUNT_ID="1784140xxxxxxx"

以下の例では Graph API バージョン v21.0 を使用しています。必要に応じて最新バージョンに置き換えることができます。

必要な権限（スコープ）

使用するエンドポイントに応じて、アプリで次の権限をリクエストし、少なくとも承認を受けていることを確認してください。

• instagram_basic
• pages_show_list
• instagram_content_publish（メディアを公開する場合）
• instagram_manage_insights および関連する権限（インサイト／一部のハッシュタグのユースケース向け）

---

重要： コマンドで $VAR を使用し、その出力を別のコマンドにパイプで渡す場合は、$VAR を含むコマンドを bash -c '...' で囲んでください。Claude Code のバグにより、パイプを直接使用すると環境変数が暗黙的にクリアされます。

bash -c 'curl -s "https://api.example.com" -H "Authorization: Bearer $API_KEY"' | jq '.'

使用方法

以下の例では、すでに次の設定が完了しているものとします。

INSTAGRAM_ACCESS_TOKEN
INSTAGRAM_BUSINESS_ACCOUNT_ID

1. アカウントの最新メディアを取得する

アカウントの最新メディア（写真／動画／Reels）を取得します。

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}"'

注：

• 返された JSON の各項目は、メディアオブジェクトを表します
• 主なフィールド：
  • id：メディア ID（後で詳細情報／インサイトを取得する際に使用）
  • caption：キャプションのテキスト
  • media_type：IMAGE／VIDEO／CAROUSEL_ALBUM
  • media_url：メディアへの直接 URL
  • permalink：Instagram のパーマリンク
  • timestamp：作成日時

---

2. 単一メディアの詳細情報を取得する

メディアの id がわかっている場合、より詳細な情報を取得できます。<your-media-id> を「Get User Media」のレスポンス（上記セクション 1）の id フィールドに置き換えてください。

bash -c '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 ${INSTAGRAM_ACCESS_TOKEN}"'

---

3. ハッシュタグでメディアを検索する

注：ハッシュタグ検索には、Facebook／Instagram が定める適切なビジネス上のユースケースと権限が必要です。公式ドキュメントを参照してください。

通常は、次の 2 つの手順で行います。

3.1 ハッシュタグ ID を取得する

検索する任意のハッシュタグ名（# 記号なし）を <hashtag-name> に指定します。例：「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=<hashtag-name>" --header "Authorization: Bearer ${INSTAGRAM_ACCESS_TOKEN}"'

返された JSON の id フィールドを確認し、次の手順で使用します。

3.2 ハッシュタグの最新メディアを取得する

<hashtag-id> を「Search Hashtag」のレスポンス（上記セクション 3.1）の id フィールドに置き換えてください。

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

---

4. 画像投稿を公開する

Graph API 経由で画像投稿を公開するには、通常、2 つの手順が必要です。

1. メディアコンテナを作成する
2. コンテナをフィードに公開する

4.1 メディアコンテナを作成する

リクエストデータを /tmp/request.json に書き込みます。

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

https://example.com/image.jpg を一般公開されている任意の画像 URL に置き換え、必要に応じてキャプションのテキストを更新します。

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}"'

レスポンスには、次の例のように id（メディアコンテナ ID）が含まれます。

{
  "id": "1790xxxxxxxxxxxx"
}

この ID を控えておき、次の手順で使用します。

4.2 メディアコンテナをフィードに公開する

リクエストデータを /tmp/request.json に書き込みます。

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

<your-creation-id> を「メディアコンテナを作成」のレスポンス（上記のセクション 4.1）の id フィールドに置き換えます。

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}"'

成功すると、レスポンスに最終的なメディアの id が含まれます。

{
  "id": "1791yyyyyyyyyyyy"
}

その後、「単一メディアの詳細を取得」コマンドを使って permalink を取得できます。

---

5. よくあるエラーとトラブルシューティング

1. 権限／OAuth エラー

• 典型的なエラーメッセージ：(#10) Application does not have permission for this action
• 確認事項：
• アプリが審査済み／承認済みかどうか
• 必要な Instagram 権限が有効になっているかどうか
• INSTAGRAM_ACCESS_TOKEN が有効な長期トークンかどうか

2. サポートされていないアカウントタイプ

• Graph API のほとんどの機能には、ビジネス／クリエイターアカウントが必要です
• Instagram アカウントのタイプが正しく、Facebook ページにリンクされていることを確認してください

3. レート制限

• 短時間にリクエストを送りすぎると、レート制限に達する場合があります。一括処理では遅延を追加してください

---

ガイドライン

1. トークンをログに記録しないでください：INSTAGRAM_ACCESS_TOKEN は機密情報です。ログやチャットの記録に出力しないでください
2. まずテスト環境で curl コマンドを検証してください：自動化やエージェントに組み込む前に、各フローを確認してください
3. API バージョンを最新に保ってください：Facebook のドキュメントを定期的に確認し、URL 内の v21.0 を最新バージョンに更新してください
4. ID にはプレースホルダーテキストを使用してください：依存関係を避け、例を単独で実行できるように、すべての例で URL 内にシェル変数ではなく <your-media-id> のようなプレースホルダーテキストを使用しています