From f4eb25d5d4b4fa57d283ae150bd65705958b3d20 Mon Sep 17 00:00:00 2001 From: Gilad Resisi Date: Fri, 30 Oct 2026 16:20:02 +0700 Subject: [PATCH 1/2] docs: Instagram alt text via API, dashboard and CLI --alt Co-Authored-By: Claude Fable 5.1 --- cli/managing-posts.mdx | 1 + cli/platform-examples.mdx | 14 ++++++++++++++ public-api/posts/create.mdx | 12 ++++++++++++ public-api/providers/instagram.mdx | 2 ++ 4 files changed, 29 insertions(+) diff --git a/cli/managing-posts.mdx b/cli/managing-posts.mdx index 1391f5ba..fbe27567 100644 --- a/cli/managing-posts.mdx +++ b/cli/managing-posts.mdx @@ -25,6 +25,7 @@ postiz posts:create \ | `-s, --date` | Schedule date in ISO 8601 format (required) | | `-t, --type` | `schedule` (default) or `draft` | | `-m, --media` | Comma-separated media URLs (use after uploading) | +| `--alt` | Comma-separated alt texts for the media of the corresponding `-m`, in the same order (use `--json` with `image[].alt` for alt texts containing commas) | | `-i, --integrations` | Comma-separated integration IDs (required) | | `-d, --delay` | Delay between comments in milliseconds (default: 5000) | | `--settings` | Platform-specific settings as JSON | diff --git a/cli/platform-examples.mdx b/cli/platform-examples.mdx index 3cce21c8..15002a1f 100644 --- a/cli/platform-examples.mdx +++ b/cli/platform-examples.mdx @@ -116,6 +116,20 @@ postiz posts:create \ -i "instagram-id" ``` +### Image with Alt Text + +`--alt` pairs with `-m` in the same order. Instagram applies it to images in posts and carousels only, not to videos or stories: + +```bash +postiz posts:create \ + -c "Beautiful day! #photography" \ + -m "$IMAGE_URL,$IMAGE_URL_2" \ + --alt "A sunset over the sea,A sandy beach" \ + -s "2025-01-15T10:00:00Z" \ + --settings '{"post_type":"post"}' \ + -i "instagram-id" +``` + ### Story ```bash diff --git a/public-api/posts/create.mdx b/public-api/posts/create.mdx index ae7e825f..24c6bb5c 100644 --- a/public-api/posts/create.mdx +++ b/public-api/posts/create.mdx @@ -29,6 +29,18 @@ Before re-submitting, strip the server-managed fields from the fetched object, r Then set a fresh `type` (`now`, `schedule`, or `draft`) and `date`, and `POST` the cleaned object. +## Image alt text (`alt`) + +Each media object in a post's `image` array accepts an optional `alt` field: a text description of the image for accessibility. + +```json +{ + "image": [{ "id": "img-123", "path": "https://uploads.postiz.com/sunset.jpg", "alt": "A sunset over the sea" }] +} +``` + +Providers that support alt text (Instagram, Instagram Standalone, Bluesky, Mastodon, Slack, Tumblr) send it with the image; other providers ignore the field. Instagram applies it to images only (single images and carousel items, up to 1000 characters), not to videos or stories. + ## Video cover frame (`thumbnailTimestamp`) Each media object in a post's `image` array accepts an optional `thumbnailTimestamp` field: the number of milliseconds into the video to use as the cover/thumbnail frame. diff --git a/public-api/providers/instagram.mdx b/public-api/providers/instagram.mdx index 56cd74c5..fdaf842d 100644 --- a/public-api/providers/instagram.mdx +++ b/public-api/providers/instagram.mdx @@ -39,6 +39,8 @@ Use `__type: "instagram"` for Facebook Business-linked accounts and `__type: "in | `collaborators` | `array` | No | List of collaborator usernames | | `audio` | `object` | No | Audio to attach to a Reel (single video only) | +Alt text is not a setting: set [`alt`](/public-api/posts/create#image-alt-text-alt) on the media object in `image`. Instagram receives it as `alt_text` on images (single images and carousel items, up to 1000 characters); it is not sent for videos or stories. + ### `post_type` | Value | Description | From 80765345140f7c7ec89ce51264167325d9281826 Mon Sep 17 00:00:00 2001 From: Gilad Resisi Date: Fri, 30 Oct 2026 16:55:50 +0700 Subject: [PATCH 2/2] docs: upload the second image before the --alt carousel example Co-Authored-By: Claude Fable 5.1 --- cli/platform-examples.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/cli/platform-examples.mdx b/cli/platform-examples.mdx index 15002a1f..3a449a89 100644 --- a/cli/platform-examples.mdx +++ b/cli/platform-examples.mdx @@ -121,6 +121,8 @@ postiz posts:create \ `--alt` pairs with `-m` in the same order. Instagram applies it to images in posts and carousels only, not to videos or stories: ```bash +IMAGE_2=$(postiz upload beach.jpg) +IMAGE_URL_2=$(echo "$IMAGE_2" | jq -r '.path') postiz posts:create \ -c "Beautiful day! #photography" \ -m "$IMAGE_URL,$IMAGE_URL_2" \