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.
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
| description | string | Required | 3 <= length <= 1500 | Free-form description of what the post should be about, in the creator's own words. |
| platforms | array<string> | Optional | Each entry: "twitter" | "instagram" | "youtube" | "tiktok" | "pinterest" | "linkedin" | "bluesky" | "facebook" | "threads" | "googlebusiness" | Platforms this post will target. Used to fit the strictest character limit. |
| existingContent | string | Optional | None supplied | Optional existing draft to rewrite/improve rather than start from scratch. |
Exact request contract for POST /v1/ai/write
| Field | Type | Required | Description |
|---|---|---|---|
| success | boolean | Required | Indicates the response outcome. |
| content | string | Required | The generated social media caption. |
| creditsCharged | number | Required | Credits charged for the successful generation. |
Exact 200 response contract
| Status | Content type | Field | Type | Required |
|---|---|---|---|---|
| 402 | application/json | success | boolean | Required |
| 402 | application/json | message | string | Required |
| 500 | application/json | success | boolean | Required |
| 500 | application/json | message | string | Required |
| 503 | application/json | success | boolean | Required |
| 503 | application/json | message | string | Required |
Exact error response contract; no cause is assigned to any status in the source contract
| Decision | Supply | Why |
|---|---|---|
| Caption must fit multiple destinations | platforms | The caption is fitted to the strictest character limit among the target platforms. |
| Rewriting an existing draft | existingContent | The draft is rewritten or improved rather than starting from scratch. |
| Fresh caption with no platform constraint | Omit both optional fields | Only 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.
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."
}'{
"success": true,
"content": "string",
"creditsCharged": 0
}{
"success": true,
"message": "string"
}| Scope | Field | Type | Type reference | Required | Description | Constraints |
|---|---|---|---|---|---|---|
| body#1 | body | object | __0 | Yes | ||
| body#1 | body.description | string | __1 | Yes | Free-form description of what the post should be about, in the creator's own words. | kind: schemaLength; value: 3 <= length <= 1500 |
| body#1 | body.platforms | array<string> | __2 | No | Platforms this post will target. Used to fit the strictest character limit. | |
| body#1 | body.platforms[] | string | __3 | kind: schemaValueIn; value: "twitter" | "instagram" | "youtube" | "tiktok" | "pinterest" | "linkedin" | "bluesky" | "facebook" | "threads" | "googlebusiness" | ||
| body#1 | body.existingContent | string | __4 | No | Optional existing draft to rewrite/improve rather than start from scratch. | |
| response#2 | response | object | __0 | |||
| response#2 | response.success | boolean | __1 | Yes | ||
| response#2 | response.content | string | __2 | Yes | ||
| response#2 | response.creditsCharged | number | __3 | Yes | ||
| response#3 | response | object | __0 | |||
| response#3 | response.success | boolean | __1 | Yes | ||
| response#3 | response.message | string | __2 | Yes |