Developers

Captions

Rewrite one base caption into a per-platform variant in the brand kit's voice: the same engine behind the dashboard composer's Tailor button, usable outside any post.

Tailor a caption per platform

POST/api/v1/captions/tailor

Pass the text you want to post and the platforms you want it tuned for. The rewrite is grounded in the workspace's brand kit (tone of voice, audience, catalog) and follows each platform's current norms: hooks before the fold, hashtag counts, character limits. It keeps the facts of your caption and avoids AI-sounding phrasing (no em dashes, no stock AI vocabulary). Scope posts:write. No Idempotency-Key: generation creates nothing, and re-running it is the point.

Each call spends the workspace's monthly AI-text budget; a 402 means the budget is exhausted until next month or a plan upgrade.

bash

curl -X POST https://postme.live/api/v1/captions/tailor \
  -H "Authorization: Bearer pml_live_AbCdEf123456_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "caption": "Our winter menu drops this Thursday. First 50 orders get free delivery.",
    "platforms": ["meta_instagram", "meta_facebook", "youtube"]
  }'

Response: `200 OK`

json

{
  "variants": [
    {
      "platform": "meta_instagram",
      "caption": "Winter menu lands Thursday.\n\nFirst 50 orders get free delivery, so set an alarm.\n\n#wintermenu #freedelivery #newmenu",
      "character_limit": 2200,
      "tailored": true
    },
    {
      "platform": "meta_facebook",
      "caption": "Our winter menu launches this Thursday.\n\nWe're marking it the simple way: free delivery for the first 50 orders.",
      "character_limit": 63206,
      "tailored": true
    },
    {
      "platform": "youtube",
      "caption": "Winter menu drops Thursday. First 50 orders get free delivery.",
      "title": "Our winter menu lands this Thursday",
      "description": "Winter menu drops Thursday. First 50 orders get free delivery.",
      "character_limit": 5000,
      "tailored": true
    }
  ]
}

Request and response fields

Field	Type	Notes
`caption`	string	The base caption to tailor, 1 to 5,000 characters. Treated as content only.
`platforms`	string[]	Unique platform values, the same ones `GET /channels` reports: `meta_facebook`, `meta_instagram`, `tiktok`, `youtube`, `linkedin_personal`, `linkedin_company`, `custom_webhook`. TikTok and LinkedIn tailoring works for channels connected earlier; current plans don't offer new connections to them.
`variants[].caption`	string	The platform-tuned caption. For YouTube it equals `description`.
`variants[].title` / `description`	string	YouTube only: a video title (aim under 60 chars) and long-form description.
`variants[].character_limit`	integer	The platform's caption cap, for client-side length checks.
`variants[].tailored`	boolean	`false` means the model skipped this platform twice and the base caption came back unchanged. Rare; retry if you need a rewrite.

Errors specific to this endpoint

Status	Code	Meaning
`402`	`quota_exceeded`	The monthly AI-text budget is used up.
`404`	`not_found`	The workspace has no brand kit yet.
`502`	`upstream_error`	The caption model returned nothing usable. Safe to retry shortly.

Composing with it

A typical agent flow: tailor the caption here, then pass each variant as the per-channel caption in POST /posts (channel captions override the base caption per target). Agents on MCP get the same behaviour from the postmelive_tailor_captions tool on the MCP server.