Skip to content

AI caption and image API

This AI caption and image API guide covers two Gemini-powered endpoints for social publishing. POST /v1/ai/write turns a free-form brief into a caption, while POST /v1/ai/image creates a picture and saves it to your project's media bucket. Authentication matches the rest of the service through the x-access-key header. Below you will find the exact request fields, credit charges, image controls, and error codes, plus checks to run before you publish anything.

Overview and endpoint contract sheet

Think of the pair as a small pipeline. The write endpoint handles words: you describe the announcement and name the destinations, and it returns finished caption text sized for the tightest limit in that set. The image endpoint handles visuals: you describe the scene, optionally pick a shape and look, and it returns a hosted file you can reuse. Both calls share the x-access-key header used elsewhere. Before sending anything, double-check the key, make the brief concrete, and confirm your balance covers a successful call. When a response comes back, inspect its fields instead of assuming success, since only successful calls carry a creditsCharged value and failures leave the balance untouched.

Credit costs

Charges apply only when a call succeeds. Caption generation costs 2 credits; image generation costs 10 credits. When a call fails, nothing is taken from the balance. Billing order matters for planning: the current subscription cycle is drawn on first, and one-time purchased credits are used after that. For a combined workflow, add each step separately, including any publishing charge shown in the worked example. If you receive an error, pause, fix the underlying problem, and only then retry, because the balance should not have changed.

Generate a caption

To Generate post captions, supply a description plus the platforms array naming every destination. Sizing follows the most restrictive limit among the named platforms, which is why listing all destinations in one request beats generating separate versions. A successful reply carries success, content, and creditsCharged. Confirm content exists and that creditsCharged equals 2 before copying the text anywhere. When a draft overshoots a destination limit, trim the brief or drop a platform; do not try to override the sizing rule.

Rewrite with existingContent

A rewrite path exists through existingContent. Place your current draft there and use description for the change you want, such as a punchier tone ending in a question. Including platforms keeps the new wording within the strictest limit. After the call, read the returned content side by side with your draft and your instruction, and check creditsCharged. If the rewrite misses the brief, adjust the instruction in description rather than editing existingContent into a new draft.

Generate an image

Image calls need only description; every other input can be left out. Add aspectRatio when shape matters and style when you want a particular visual treatment. Replies include success, url, mimeType, and creditsCharged. The returned url points to a permanent hosted file that the source prose describes as suitable for the mediaItems array of POST /v1/posts/. Before publishing, verify url and mimeType, confirm creditsCharged shows 10, and then hand the url to the publish step.

Aspect ratios

Shape is controlled through aspectRatio, with three accepted values. square gives a 1:1 frame and is the default. vertical gives 9:16. landscape gives 16:9. Enforcement happens inside the model through imageConfig.aspectRatio, so the chosen frame holds even if supplied reference pictures have different proportions. Start from the destination format, write the scene description to fit that frame, and inspect the output dimensions before it goes live.

Style presets

The style field accepts the Style presets listed in the table below, or can be omitted so the model selects a treatment matching the brief. Each preset pushes the result in a distinct direction, from photorealistic to hand-drawn. Choose a single value per request and judge the output against that preset's description. When the picture feels off, revise either the style choice or the description; stacking conflicting style language tends to muddy the result.

Reference images vs. asset images

Image inputs come in two flavours, both optional and usable together. referenceImageUrls takes up to four links meant as mood or composition guidance. The model reads them for context and does not reproduce them in the output. Reach for this field when you want a brand feel, a similar layout, or a comparable mood in a new scene. assetImageUrls also takes up to four links, but with the opposite meaning: those pictures must show up in the finished image, intact. Logos, product shots, and specific subjects belong here. In practice, the surrounding scene follows your brief while each asset is inserted without being redrawn or restyled.

Iterative tweaks and backwards compatibility

Small revisions to an earlier picture are handled by sending that picture through referenceImageUrl together with a short delta brief, for instance warmer lighting or the same mood relocated to a beach. Shape stays fixed on the server during such tweaks, so the revised version keeps the original frame. Compatibility note: the legacy singular field referenceImageUrl remains accepted and gets folded into referenceImageUrls. Fresh integrations should send the array form. While debugging, note which field name you used and confirm the frame survived the tweak.

End-to-end example

The full flow runs in three stages. Stage one produces caption text through POST /v1/ai/write. Stage two produces a picture through POST /v1/ai/image, with a logo supplied via assetImageUrls so it appears in the scene. Stage three publishes through POST /v1/posts, sending content, a platforms entry containing platform and accountId, mediaItems entries with type and url, and publishNow. The worked example totals 13 credits: 2 for words, 10 for the picture, and 1 for publishing. Follow the stages sequentially, capture content from the first reply and url from the second, and validate each reply before moving on.

Errors

Three status codes cover the failure cases. 402 Payment Required signals insufficient credits in the project; the remedy is to purchase more credits or move to a higher plan. 503 Service Unavailable signals that AI features are not configured server-side, described in the source as rare and linked to an unset GEMINI_API_KEY. Any other problem surfaces as 500. Across all three, the balance is not charged. Treat 402 as a balance issue, 503 as a configuration issue rather than something repeated retries will fix, and 500 as a prompt to review your request fields before trying again.

Tone of voice

Caption output follows a fixed style guide aimed at sounding human. Avoid em-dashes and filler buzzwords such as leverage, streamline, or unlock. Vary sentence length. Skip bullets formatted as Bold word: explanation. Skip transition openers like Moreover or Additionally. The goal is caption voice, not press-release voice. The underlying system prompt is locked, so there is no need to request it inside description. Write description as a plain brief, then proof the returned content against these rules before posting.

Credit costs
EndpointCredits per successful call
/v1/ai/write2
/v1/ai/image10

Failed calls do not deduct credits. Costs come out of subscription cycle first, then one-time purchased credits.

Input contract
FieldEndpointRequiredType / valuesNotes
descriptionPOST /v1/ai/writeShown in examplesstringFree-form caption brief
platformsPOST /v1/ai/writeShown in examplesarray of strings, e.g. twitter, bluesky, linkedinCaption fitted to strictest character limit among platforms
existingContentPOST /v1/ai/writeOptionalstringExisting draft to rewrite instead of starting fresh
descriptionPOST /v1/ai/imageRequiredstringMinimum required field; everything else optional
aspectRatioPOST /v1/ai/imageOptionalsquare (default), vertical, landscapeEnforced at model level via imageConfig.aspectRatio
stylePOST /v1/ai/imageOptionalphoto, illustration, minimal, vibrant, cinematic, 3d-render, retro, hand-drawnOmit for model to choose
referenceImageUrlsPOST /v1/ai/imageOptionalarray of URLs, up to 4Style/vibe inspiration only; not copied into result
assetImageUrlsPOST /v1/ai/imageOptionalarray of URLs, up to 4Images that must appear faithfully in result
referenceImageUrlPOST /v1/ai/imageOptional legacysingle image fieldStill accepted and merged into referenceImageUrls; new integrations should use array form

Exact field names preserved from source contract. Requiredness for platforms is shown in examples; source does not explicitly state it as a definitive schema requirement.

Response contract
FieldPOST /v1/ai/write responsePOST /v1/ai/image response
successbooleanboolean
contentstring captionnot present
urlnot presentstring permanent image URL
mimeTypenot presentstring, e.g. image/png
creditsCharged2 on success10 on success

Check fields on every successful call.

Aspect ratios
ValuePixelsUse for
square (default)1:1Instagram, Twitter, LinkedIn, Pinterest
vertical9:16TikTok, Reels, YouTube Shorts
landscape16:9YouTube thumbnails, blog headers

aspectRatio enum preserved exactly.

Style presets
ValueEffect
photoPhotorealistic, natural lighting
illustrationFlat vector, bold shapes, limited palette
minimalLots of negative space, two or three colors max
vibrantHigh-saturation, high-contrast pop
cinematicStrong directional light, deep shadows, film grain
3d-renderSoft 3D, clay materials, smooth shading
retro70s/80s palette, slight grain, period typography
hand-drawnPencil lines, light watercolor wash

style enum preserved exactly.

Failure matrix
StatusMeaningActionCredits deducted
402 Payment RequiredProject does not have enough credits for the callBuy more credits or upgrade planNo
503 Service UnavailableAI features are not configured on the server; source states this means GEMINI_API_KEY is unsetTreat as server configuration issue, not a credit issueNo
500Any other failureCheck request fields and status before retryingNo

No credits are deducted on failure.

End-to-end credit total
StepCallCredits
1 CaptionPOST /v1/ai/write2
2 ImagePOST /v1/ai/image10
3 PublishPOST /v1/posts1
Total13

Source worked example total.

Generate a caption with curl
curl -X POST {{API_BASE_URL}}/v1/ai/write \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Example post details.",
    "platforms": ["twitter", "bluesky", "linkedin"]
  }'
Rewrite a caption using existingContent
{
  "description": "Example post details.",
  "existingContent": "An earlier example update.",
  "platforms": ["twitter"]
}
Generate an image with curl
curl -X POST {{API_BASE_URL}}/v1/ai/image \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Example post details.",
    "aspectRatio": "square",
    "style": "photo"
  }'
Image response example
{
  "success": true,
  "url": "https://assets.example.com/uploads/<projectId>/ai-<uuid>.png",
  "mimeType": "image/png",
  "creditsCharged": 10
}
Generate an image with referenceImageUrls and assetImageUrls
curl -X POST {{API_BASE_URL}}/v1/ai/image \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Example post details.",
    "aspectRatio": "square",
    "style": "photo",
    "referenceImageUrls": [
      "https://assets.example.com/uploads/<projectId>/brand-mood-1.jpg"
    ],
    "assetImageUrls": [
      "https://assets.example.com/uploads/<projectId>/logo.png"
    ]
  }'
End-to-end caption, image, and publish example
# Step 1: caption
curl -X POST {{API_BASE_URL}}/v1/ai/write \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "description": "Example post details.", "platforms": ["twitter"] }'

# Step 2: image with brand logo placed in
curl -X POST {{API_BASE_URL}}/v1/ai/image \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Example post details.",
    "aspectRatio": "vertical",
    "style": "cinematic",
    "assetImageUrls": ["https://assets.example.com/uploads/.../logo.png"]
  }'

# Step 3: publish
curl -X POST {{API_BASE_URL}}/v1/posts \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "A short example update.",
    "platforms": [ { "platform": "twitter", "accountId": "your-account-id" } ],
    "mediaItems": [ { "type": "image", "url": "https://assets.example.com/uploads/.../ai-...png" } ],
    "publishNow": true
  }'
Contract example 5
-d '{
  "description": "Example post details.",
  "existingContent": "An earlier example update.",
  "platforms": ["twitter"]
}'
Response example 9
{
	"success": true,
	"url": "{{MEDIA_BASE_URL}}/uploads/<projectId>/ai-<uuid>.png",
	"mimeType": "image/png",
	"creditsCharged": 10
}
Example 11
# Step 1: caption
curl -X POST {{API_BASE_URL}}/v1/ai/write \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "description": "Example post details.", "platforms": ["twitter"] }'
# → { "content": "A short example update." }

# Step 2: image with brand logo placed in
curl -X POST {{API_BASE_URL}}/v1/ai/image \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Example post details.",
    "aspectRatio": "vertical",
    "style": "cinematic",
    "assetImageUrls": ["{{MEDIA_BASE_URL}}/uploads/.../logo.png"]
  }'
# → { "url": "{{MEDIA_BASE_URL}}/uploads/.../ai-...png" }

# Step 3: publish
curl -X POST {{API_BASE_URL}}/v1/posts \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "A short example update.",
    "platforms": [ { "platform": "twitter", "accountId": "your-account-id" } ],
    "mediaItems": [ { "type": "image", "url": "{{MEDIA_BASE_URL}}/uploads/.../ai-...png" } ],
    "publishNow": true
  }'
Preserved response example 4
{
	"success": true,
	"content": "A short example update.",
	"creditsCharged": 2
}
Preserved request example 10
curl -X POST {{API_BASE_URL}}/v1/ai/image \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Example post details.",
    "aspectRatio": "square",
    "style": "photo",
    "referenceImageUrls": [
      "{{MEDIA_BASE_URL}}/uploads/<projectId>/brand-mood-1.jpg"
    ],
    "assetImageUrls": [
      "{{MEDIA_BASE_URL}}/uploads/<projectId>/brand-logo.png"
    ]
  }'