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.
| Endpoint | Credits per successful call |
|---|---|
| /v1/ai/write | 2 |
| /v1/ai/image | 10 |
Failed calls do not deduct credits. Costs come out of subscription cycle first, then one-time purchased credits.
| Field | Endpoint | Required | Type / values | Notes |
|---|---|---|---|---|
| description | POST /v1/ai/write | Shown in examples | string | Free-form caption brief |
| platforms | POST /v1/ai/write | Shown in examples | array of strings, e.g. twitter, bluesky, linkedin | Caption fitted to strictest character limit among platforms |
| existingContent | POST /v1/ai/write | Optional | string | Existing draft to rewrite instead of starting fresh |
| description | POST /v1/ai/image | Required | string | Minimum required field; everything else optional |
| aspectRatio | POST /v1/ai/image | Optional | square (default), vertical, landscape | Enforced at model level via imageConfig.aspectRatio |
| style | POST /v1/ai/image | Optional | photo, illustration, minimal, vibrant, cinematic, 3d-render, retro, hand-drawn | Omit for model to choose |
| referenceImageUrls | POST /v1/ai/image | Optional | array of URLs, up to 4 | Style/vibe inspiration only; not copied into result |
| assetImageUrls | POST /v1/ai/image | Optional | array of URLs, up to 4 | Images that must appear faithfully in result |
| referenceImageUrl | POST /v1/ai/image | Optional legacy | single image field | Still 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.
| Field | POST /v1/ai/write response | POST /v1/ai/image response |
|---|---|---|
| success | boolean | boolean |
| content | string caption | not present |
| url | not present | string permanent image URL |
| mimeType | not present | string, e.g. image/png |
| creditsCharged | 2 on success | 10 on success |
Check fields on every successful call.
| Value | Pixels | Use for |
|---|---|---|
| square (default) | 1:1 | Instagram, Twitter, LinkedIn, Pinterest |
| vertical | 9:16 | TikTok, Reels, YouTube Shorts |
| landscape | 16:9 | YouTube thumbnails, blog headers |
aspectRatio enum preserved exactly.
| Value | Effect |
|---|---|
| photo | Photorealistic, natural lighting |
| illustration | Flat vector, bold shapes, limited palette |
| minimal | Lots of negative space, two or three colors max |
| vibrant | High-saturation, high-contrast pop |
| cinematic | Strong directional light, deep shadows, film grain |
| 3d-render | Soft 3D, clay materials, smooth shading |
| retro | 70s/80s palette, slight grain, period typography |
| hand-drawn | Pencil lines, light watercolor wash |
style enum preserved exactly.
| Status | Meaning | Action | Credits deducted |
|---|---|---|---|
| 402 Payment Required | Project does not have enough credits for the call | Buy more credits or upgrade plan | No |
| 503 Service Unavailable | AI features are not configured on the server; source states this means GEMINI_API_KEY is unset | Treat as server configuration issue, not a credit issue | No |
| 500 | Any other failure | Check request fields and status before retrying | No |
No credits are deducted on failure.
| Step | Call | Credits |
|---|---|---|
| 1 Caption | POST /v1/ai/write | 2 |
| 2 Image | POST /v1/ai/image | 10 |
| 3 Publish | POST /v1/posts | 1 |
| Total | 13 |
Source worked example total.
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"]
}'{
"description": "Example post details.",
"existingContent": "An earlier example update.",
"platforms": ["twitter"]
}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"
}'{
"success": true,
"url": "https://assets.example.com/uploads/<projectId>/ai-<uuid>.png",
"mimeType": "image/png",
"creditsCharged": 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": [
"https://assets.example.com/uploads/<projectId>/brand-mood-1.jpg"
],
"assetImageUrls": [
"https://assets.example.com/uploads/<projectId>/logo.png"
]
}'# 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
}'-d '{
"description": "Example post details.",
"existingContent": "An earlier example update.",
"platforms": ["twitter"]
}'{
"success": true,
"url": "{{MEDIA_BASE_URL}}/uploads/<projectId>/ai-<uuid>.png",
"mimeType": "image/png",
"creditsCharged": 10
}# 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
}'{
"success": true,
"content": "A short example update.",
"creditsCharged": 2
}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"
]
}'