# Instagram API: Posting Reference

Instagram is supported via the Instagram Graph API. Connected accounts must be Instagram Business or Creator accounts linked to a Facebook Page. Personal Instagram accounts are not supported by Meta's API and cannot be connected.

**Channel ID:** `instagram`

## Supported content types

| Type | Supported | Notes |
|------|-----------|-------|
| Feed post | ✅ | Single image, video, or carousel (up to 10 items) |
| Story | ✅ | Requires media (image or video) |
| Reel | ✅ | Requires a vertical video |

## Minimal example

```bash
curl -X POST https://api.omnisocials.com/v1/posts/create \
  -H "Authorization: Bearer $OMNISOCIALS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": { "default": "Golden hour 🌅" },
    "accounts": ["your-instagram-account-id"],
    "media_urls": ["https://example.com/sunset.jpg"]
  }'
```

Instagram posts always require media. A post with no media returns `400`.

## Instagram options

Set these under the `instagram` key on the post body:

| Field | Type | Description |
|-------|------|-------------|
| `instagram.first_comment` | string | Text auto-posted as the first comment right after the post publishes (max 2200 characters). Common for keeping hashtags out of the caption. Works on feed posts and reels; not posted for stories. |
| `instagram.share_to_feed` | boolean | Reel only. Also display the reel on the profile grid. |
| `instagram.thumbnail_type` | string | Reel only. `from-video` or `from-library`. |
| `instagram.thumb_offset` | number | Reel only. Timestamp in milliseconds, used when `thumbnail_type` is `from-video`. |
| `instagram.cover_url` | string | Reel only. URL of a custom cover image, used when `thumbnail_type` is `from-library`. |

## Instagram-only post options

These are set as **top-level** fields on the post body (not under the `instagram` key) and are ignored by other platforms:

| Field | Type | Description |
|-------|------|-------------|
| `location_id` | string | Facebook Place/Page ID to tag the post's location. Single-image and carousel feed posts only. Find a Place ID with `GET /locations/search`. |
| `collaborators` | array of strings | Up to 3 public Instagram usernames invited as co-authors (the "Collab" feature). Image, carousel, and reel posts; not stories. |
| `user_tags` | array | Tag public accounts at positions on a photo: `[{"username": "name", "x": 0.5, "y": 0.8, "image_index": 0}]`. `x`/`y` are 0–1 from the top-left. Photos only, not video, reels, or stories. |

## Media requirements

| Media | Requirement |
|-------|-------------|
| Feed image | JPEG or PNG, 320 to 1440 px wide, aspect ratio between 9:16 (portrait) and 1.91:1 (landscape) |
| Feed video | MP4 or MOV, up to 15 minutes, max 300 MB |
| Story image | JPEG or PNG, aspect ratio 9:16 recommended |
| Story video | MP4, up to 60 seconds, max 300 MB |
| Reel video | MP4, vertical 9:16, up to 15 minutes, max 300 MB |
| Carousel | 2 to 10 items, all images or all videos |

Content that violates aspect ratio or duration is rejected at publish time with a `400` error referencing the Instagram Graph API response.

## Limitations

- Personal (non-business) Instagram accounts cannot be connected
- Tagging users in media requires each tagged user to be a public account
- Instagram does not allow scheduling posts further than 75 days in advance

## Testing

In test mode (`omsk_test_*` keys), Instagram posts are validated but never sent to Meta. The response shape matches production so your integration can be built and tested without risking real posts.