PostEverywhere AI Caption Guide

Generates 1-5 caption variants for a social media post from a topic + tone + platform. Companion to /v1/ai/generate-image: together they let an MCP agent compose an entire post in two API calls.

Captions respect per-platform character limits and follow each platform's hashtag conventions automatically:

Platform	Hard limit	Hashtag style
X / Twitter	280 chars	1-3 hashtags at end
Bluesky	300 chars	1-3 hashtags
Threads	500 chars	1-3 hashtags
Pinterest	500 chars	No hashtags (uses natural-language search)
YouTube	1,000 chars	1-3 hashtags
Instagram	2,200 chars	5-10 hashtags at end
TikTok	2,200 chars	5-10 hashtags
LinkedIn	3,000 chars	2-3 hashtags (LinkedIn discourages heavy use)
Facebook	5,000 chars	1-3 hashtags
WordPress	5,000 chars	No hashtags

Generate a caption from a prompt: POST /v1/ai/generate-caption#

curl -X POST https://app.posteverywhere.ai/api/v1/ai/generate-caption \
  -H "Authorization: Bearer $POSTEVERYWHERE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "topic":    "Black Friday sale on running shoes — 30% off through Monday",
    "platform": "instagram",
    "tone":     "enthusiastic",
    "length":   "medium",
    "count":    3
  }'

Requires the ai scope. Costs 1 AI credit per returned caption.

Controlling tone, length and platform#

Field	Type	Default	Description
topic	string (required)	N/A	What the post should be about (max 1,000 chars).
platform	string	none	If set, applies platform-specific length + style rules. Omit for generic.
tone	string	professional	professional | casual | witty | enthusiastic | urgent | inspirational
length	string	medium	short (80 chars) | medium (180 chars) | long (~400 chars)
include_hashtags	boolean	true	Set false to omit hashtags entirely.
include_emojis	boolean	true	Set false for emoji-free output.
count	integer	1	Number of variants to return (1-5).

What the caption response returns#

{
  "data": {
    "captions": [
      "🏃 30% OFF until Monday! Time to lace up. Our best running shoes — half a closet, all the comfort. Free shipping over $50. Link in bio.\n\n#blackfriday #runningshoes #sale #fitness #running",
      "BLACK FRIDAY MADNESS 🛍️ ...",
      "..."
    ],
    "platform":        "instagram",
    "tone":            "enthusiastic",
    "length":          "medium",
    "count_requested": 3,
    "count_returned":  3,
    "credits_used":    3,
    "credits_remaining": 197
  },
  "error": null,
  "meta": { "request_id": "a1b2c3d4", "timestamp": "2026-06-11T09:55:12.341Z" }
}

Caption generation errors#

Code	HTTP	When
validation_error	400	Missing topic or topic > 1000 chars.
insufficient_credits	402	Not enough AI credits for the requested count. Response includes needed and available.
ai_no_content	502	OpenAI returned no content. Rephrase the topic and retry.

Pairing captions with generated images#

const me = await client.me.get();
if (me.quota.ai_credits.limit - me.quota.ai_credits.used < 6) {
  showUpgrade();
  return;
}

// 1 image (~5 credits) + 1 caption (1 credit) = 6 credits.
const [image, captions] = await Promise.all([
  client.ai.generateImage({ prompt: 'Vibrant running shoes on a track' }),
  client.ai.generateCaption({
    topic: 'Black Friday — 30% off running shoes',
    platform: 'instagram',
    tone: 'enthusiastic',
    count: 1,
  }),
]);

await client.posts.create({
  content: captions.captions[0],
  account_ids: [igAccountId],
  media_ids: [image.media_id],
  scheduled_for: '2026-11-29T10:00:00Z',
});

What caption generation costs in credits#

• Tone influences word choice. professional produces measured copy with full sentences. witty introduces wordplay. enthusiastic uses exclamation marks and energy words. Match tone to brand voice.
• Multi-platform posting. If you're posting to multiple platforms with different character limits, generate ONE caption sized for the shortest (X/Bluesky). Or call this endpoint per-platform.
• Hashtag placement. Hashtags always land at the end of the caption (Instagram convention), unless you set include_hashtags: false.
• Pinterest is special: include_hashtags is ignored. Pinterest uses natural-language search, not hashtags, so they're omitted.

Related: the ai scope · media limits per platform · testing without publishing · AI credits per plan

Full reference: POST /v1/ai/generate-caption and POST /v1/ai/generate-image.