Skip to content

AI Write Content API: Generate a Social Media Caption from a Description

The AI Write Content API generates a social media caption from a free-form description. You describe what the post should be about in your own words, optionally name the platforms the post will target so the caption can fit the strictest character limit, and optionally supply an existing draft to rewrite or improve. A successful generation costs 2 credits, and failed calls do not deduct credits.

Operation summary

Call POST /v1/ai/write to generate a social media caption tailored to the platforms you will post to. The operation costs 2 credits per successful generation, and failed calls do not deduct credits. Use this endpoint when you have a topic or announcement in plain language and need a caption, rather than writing the caption manually for each platform.

Authorization

Send the access key in the x-access-key header. The header name is x-access-key and its value is the token. Requests use application/json for the body.

Request body

The request body is an application/json object. The description field is required and must be a string between 3 and 1500 characters long, describing what the post should be about in the creator's own words. The platforms field is optional and is an array of strings; each entry must be one of the supported platform values listed in the input contract table. Supply platforms when the same caption must fit several destinations, because the caption is fitted to the strictest character limit among them. The existingContent field is optional and is a string; supply it when you want an existing draft rewritten or improved rather than starting from scratch. Omit optional fields when they do not apply instead of sending empty values.

Response body: 200

On success, the endpoint returns 200 with an application/json body containing success, content and creditsCharged. Read the generated social media caption from content, which is a string, and read creditsCharged, which is a number, to confirm what was charged for that generation. Treat success as the boolean gate for the call and only use content when the status is 200 and success is true.

Response body: 402, 500 and 503

The endpoint can also return 402, 500 or 503, each with an application/json body containing success and message. The message field is a string describing the response, and success is a boolean. The contract does not assign a specific cause to any of these statuses, so log the status and message, surface the message to the caller, and avoid assuming a cause that is not stated. The supplied error shape contains only success and message. Because failed calls do not deduct credits, a failed call should not be treated as a charged generation.

Making the call and checking failures

Build the request with the exact method and path, set Content-Type to application/json, add the x-access-key header, and send a JSON body that includes description and only the optional fields you need. Validate description length before sending, validate each platforms entry against the supported values, and decide whether existingContent is needed for a rewrite or should be omitted for a fresh caption. After the call, branch on the status code first, then on success, then read content and creditsCharged on a 200 response or message on an error response. The origin-modular request example below shows the full call shape with a placeholder token.

Request body fields
FieldTypeRequiredConstraintsDescription
descriptionstringRequired3 <= length <= 1500Free-form description of what the post should be about, in the creator's own words.
platformsarray<string>OptionalEach entry: "twitter" | "instagram" | "youtube" | "tiktok" | "pinterest" | "linkedin" | "bluesky" | "facebook" | "threads" | "googlebusiness"Platforms this post will target. Used to fit the strictest character limit.
existingContentstringOptionalNone suppliedOptional existing draft to rewrite/improve rather than start from scratch.

Exact request contract for POST /v1/ai/write

200 response fields
FieldTypeRequiredDescription
successbooleanRequiredIndicates the response outcome.
contentstringRequiredThe generated social media caption.
creditsChargednumberRequiredCredits charged for the successful generation.

Exact 200 response contract

Failure responses: 402, 500 and 503
StatusContent typeFieldTypeRequired
402application/jsonsuccessbooleanRequired
402application/jsonmessagestringRequired
500application/jsonsuccessbooleanRequired
500application/jsonmessagestringRequired
503application/jsonsuccessbooleanRequired
503application/jsonmessagestringRequired

Exact error response contract; no cause is assigned to any status in the source contract

When to supply optional fields
DecisionSupplyWhy
Caption must fit multiple destinationsplatformsThe caption is fitted to the strictest character limit among the target platforms.
Rewriting an existing draftexistingContentThe draft is rewritten or improved rather than starting from scratch.
Fresh caption with no platform constraintOmit both optional fieldsOnly description is required; optional fields are not needed.

Guidance derived only from the supplied field descriptions

Frequently asked questions

What do I send to generate a social media caption?

Send a POST request to /v1/ai/write with a required description string between 3 and 1500 characters. You may optionally add platforms to fit the strictest character limit among the target platforms, and existingContent to rewrite or improve an existing draft instead of starting from scratch.

How many credits does a successful generation cost?

A successful generation costs 2 credits. Failed calls do not deduct credits. On a 200 response, read the generated caption from content and the number charged from creditsCharged.

How is the request authorized?

Include the access key in the x-access-key header. The request body is application/json and the endpoint is POST /v1/ai/write.

What shape do 402, 500 and 503 responses have?

Each of those statuses returns an application/json body with success as a boolean and message as a string. The source contract does not describe a specific cause for any of them, so handle the message generically and do not assume a cause from the status alone.

Origin-modular request example
curl -X POST "{{API_BASE_URL}}/v1/ai/write" \
  -H "Content-Type: application/json" \
  -H "x-access-key: <token>" \
  -d '{
    "description": "Example post details.",
    "platforms": ["instagram", "facebook"],
    "existingContent": "An earlier example update."
  }'
200 response example
{
  "success": true,
  "content": "string",
  "creditsCharged": 0
}
402, 500 and 503 response example
{
  "success": true,
  "message": "string"
}
Interface fields
ScopeFieldTypeType referenceRequiredDescriptionConstraints
body#1bodyobject__0Yes
body#1body.descriptionstring__1YesFree-form description of what the post should be about, in the creator's own words.kind: schemaLength; value: 3 <= length <= 1500
body#1body.platformsarray<string>__2NoPlatforms this post will target. Used to fit the strictest character limit.
body#1body.platforms[]string__3kind: schemaValueIn; value: "twitter" | "instagram" | "youtube" | "tiktok" | "pinterest" | "linkedin" | "bluesky" | "facebook" | "threads" | "googlebusiness"
body#1body.existingContentstring__4NoOptional existing draft to rewrite/improve rather than start from scratch.
response#2responseobject__0
response#2response.successboolean__1Yes
response#2response.contentstring__2Yes
response#2response.creditsChargednumber__3Yes
response#3responseobject__0
response#3response.successboolean__1Yes
response#3response.messagestring__2Yes