---
title: "Generate a social caption from images you own"
method: POST
path: "/v1/images/instagram-enhance"
tags: ["Images"]
---

# Generate a social caption from images you own

`POST /v1/images/instagram-enhance`

## Request

- Base URL: `https://contentmaschine.ai/api`
- URL: `https://contentmaschine.ai/api/v1/images/instagram-enhance`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://contentmaschine.ai/api/oauth/authorize`, token URL `https://contentmaschine.ai/api/oauth/token`)

Produces a platform-shaped caption - and on headline platforms a headline and a
description - from 1 to 10 images.

**SCOPES: this route needs `images:write` to CALL, but its OUTPUT reads as `text`**
(D-15-23). The result is stored as a `caption_generation`, which classifies into the
`text` container, so finding it later through /v1/gallery, /v1/library or
/v1/jobs/{id} needs `text:read`. A token holding only `images:write` can run this
and be charged for it, and then not be able to read the result back. The response
body returns the caption directly, so a single call still works.

Give the images as library `file_uuids` (upload with POST /v1/files/upload) or inline
as base64 in `images`; exactly one of the two.
Limits: 10485760 bytes per image, 26214400 bytes across the call,
`context` at most 2000 characters.

The prompt is built SERVER-SIDE. There is deliberately no raw `prompt` field: it
would turn the caption credit path into a general-purpose vision prompt. `context`
and the blueprint fields are untrusted text spliced into a model instruction and the
builder emits a guard sentence about them - a mitigation, not a guarantee.

## Request body

- object
  - `file_uuids` string[]: Uuids of images you own. Must be a real JSON array. Use this or `images`.
  - `images` string[]: The images inline, each base64 or a data URL (PNG, JPEG, WebP or GIF). Must be a real JSON array. Use this or `file_uuids`.
  - `platform` string, required: Target platform, e.g. "Instagram" or "TikTok".
  - `length` 'Short' | 'Medium' | 'Long' | 'Very Long', required: Caption length.
  - `tone` string, required: Tone, e.g. "Friendly".
  - `language` string, required: Output language, e.g. "English".
  - `context` string: Extra brief for the model. At most 2000 characters.
  - `blueprint` object: Optional StoryBrand fields: title, businessName, hero, problem, guide, plan, callToAction, avoidFailure, success.
  - `additional_hashtags` union: Your own hashtags as a string, or their count as an integer. On TikTok the model is asked for the remainder of five.
    - string
    - integer

## Response `200`

The generated caption.

- object
  - `success` boolean
  - `data` object
    - `headline` string, nullable: Headline platforms only.
    - `description` string, nullable
    - `caption` string
    - `hashtags` string[]
    - `credits_used` number, float: Credits actually charged.
    - `generation_id` integer: The stored generation, readable with text:read.
    - `processing_time_ms` integer: Wall clock inside the handler.
  - `timestamp` string, date-time

## Other responses

- `400`: Bad input: a missing field, an over-long value, more than 10 images, both image forms, an unusable inline image, or a JSON object where an array was required.
- `401`: Missing or invalid API key.
- `402`: Insufficient credits.
- `404`: A file_uuid is unknown or not yours.
- `413`: The images exceed the per-image or total byte limit.
- `415`: One of the files is not an image.
- `503`: The captioning provider is unavailable or rate limited.
- `default`: Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.

---

[API](https://skmtc.dev/contentmaschine/apis/contentmaschine-ai-api.md) · [All operations](https://skmtc.dev/contentmaschine/apis/contentmaschine-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/contentmaschine/apis/contentmaschine-ai-api/revisions/28c74f46051c?raw)