Skip to content

Generate Image API: Generate a social media image from a description

The Generate Image API generates a social media image from a text description. Use POST {{API_BASE_URL}}/v1/ai/image with a JSON request body. The endpoint generates a square or vertical image suitable for social media, with landscape also available through the aspectRatio field. A successful generation costs 10 credits, and failed calls do not deduct credits.

Generate Image API overview and exact endpoint contract

The Generate Image API creates a social media image from a description supplied in the request body. Send a POST request to {{API_BASE_URL}}/v1/ai/image. The required description field is a string between 3 and 1500 characters long. When aspectRatio is omitted, the output defaults to square. A successful generation costs 10 credits per generation, and failed calls do not deduct credits. The request example titled Generate Image API request example shows the exact method, path and JSON body shape to use.

Authorization

Authenticate every request by sending the access key in the x-access-key header. The header value is the token placeholder shown in the request example. Do not place the token in the JSON body, because the captured contract defines authorization as a header field named x-access-key.

Request body field map

Build the JSON request body from the field map titled Request body field map. The description field is required and must be a string with length from 3 to 1500. The aspectRatio field is optional and accepts square, vertical or landscape, defaulting to square when omitted. The style field is optional and accepts photo, illustration, minimal, vibrant, cinematic, 3d-render, retro or hand-drawn; when style is omitted, the model picks a style that fits the brief. Use referenceImageUrls for up to four uri strings that provide style or vibe inspiration only, such as matching a brand look or a composition, because the model will not copy those images. Use assetImageUrls for up to four uri strings that must appear in the generated image, such as a brand logo or a specific product photo, because the model places those assets faithfully according to the brief without redrawing them. The deprecated referenceImageUrl field is a single uri string still accepted for backwards compatibility, and new requests should use referenceImageUrls instead. Before sending a request, check that description is present and within the length limit, that every enum value is spelled exactly as listed, that each image array contains no more than four uri items, and that reference images and asset images have not been swapped, since they have opposite placement semantics.

Response bodies for 200, 402, 500 and 503

The response body uses four documented status codes. A 200 response returns success, url, mimeType and creditsCharged, where url is a uri string, mimeType is a string and creditsCharged is a number. The 402, 500 and 503 responses each return only success and message in the captured contract, where success is a boolean and message is a string. Handle each status separately in client code: treat 200 as the only response that supplies a generated image url, and treat 402, 500 and 503 as message responses that do not supply url, mimeType or creditsCharged. The response examples titled 200 response example and 402, 500 and 503 response example show the exact captured shapes. Do not assume additional error fields, because the captured contract for those statuses contains only success and message.

Origin-modular HTTP request example

To implement the call, set the request method to POST, set the path to /v1/ai/image under {{API_BASE_URL}}, add the x-access-key header and a Content-Type of application/json, and send the JSON body. After the call, branch on the status code, read url and mimeType from a 200 response, and read message from a 402, 500 or 503 response. Verify the returned creditsCharged value on success and verify that a failed call has not been treated as a successful generation.

Request body field map
FieldRequiredTypeConstraints and meaning
descriptionRequiredstringLength: 3 <= length <= 1500
aspectRatioOptionalstringOutput aspect ratio. Defaults to square when omitted. Values: "square" | "vertical" | "landscape"
styleOptionalstringVisual style preset. Adds style guidance to the prompt. Omit for the model to pick whatever fits the brief. Values: "photo" | "illustration" | "minimal" | "vibrant" | "cinematic" | "3d-render" | "retro" | "hand-drawn"
referenceImageUrlsOptionalarray<string>Reference images. Used as style/vibe inspiration ONLY. The model will not copy them. Useful for "match my brand look" or "same composition as this". Items: items <= 4; each item format: uri
assetImageUrlsOptionalarray<string>Asset images that MUST appear in the generated image (e.g. a brand logo, a specific product photo). The model will place them faithfully according to the brief, without redrawing them. Items: items <= 4; each item format: uri
referenceImageUrlOptionalstringDEPRECATED: use referenceImageUrls instead. Still accepted for backwards compatibility. Format: uri

Exact captured contract; referenceImageUrl is deprecated but still accepted for backwards compatibility.

Response field map by status
StatusFieldRequiredTypeMeaning
200successRequiredbooleanCaptured success field
200urlRequiredstringGenerated image uri; format: uri
200mimeTypeRequiredstringCaptured MIME type field
200creditsChargedRequirednumberCaptured credits field
402successRequiredbooleanCaptured success field
402messageRequiredstringCaptured message field
500successRequiredbooleanCaptured success field
500messageRequiredstringCaptured message field
503successRequiredbooleanCaptured success field
503messageRequiredstringCaptured message field

Only the captured success/message shape is documented for 402, 500 and 503; no additional error semantics are specified.

Reference images versus asset images
DecisionUse this fieldPlacement rule
Match a brand look, vibe or composition without copying the imagereferenceImageUrlsStyle/vibe inspiration ONLY; the model will not copy them
Include a specific logo or product photo in the outputassetImageUrlsMUST appear; the model places them faithfully without redrawing them

Decision criteria from the captured field descriptions.

Generate Image API request example
curl -X POST "{{API_BASE_URL}}/v1/ai/image" \
  -H "Content-Type: application/json" \
  -H "x-access-key: <token>" \
  -d '{
    "description": "string"
  }'
200 response example
{
  "success": true,
  "url": "http://example.com",
  "mimeType": "string",
  "creditsCharged": 0
}
402, 500 and 503 response example
{
  "success": true,
  "message": "string"
}
Interface fields
ScopeFieldTypeType referenceRequiredDescriptionConstraints
body#1bodyobject__0Yes
body#1body.descriptionstring__1Yeskind: schemaLength; value: 3 <= length <= 1500
body#1body.aspectRatiostring__2NoOutput aspect ratio. Defaults to square when omitted.kind: schemaValueIn; value: "square" | "vertical" | "landscape"
body#1body.stylestring__3NoVisual style preset. Adds style guidance to the prompt. Omit for the model to pick whatever fits the brief.kind: schemaValueIn; value: "photo" | "illustration" | "minimal" | "vibrant" | "cinematic" | "3d-render" | "retro" | "hand-drawn"
body#1body.referenceImageUrlsarray<string>__4NoReference images. Used as style/vibe inspiration ONLY. The model will not copy them. Useful for "match my brand look" or "same composition as this".kind: schemaItems; value: items <= 4
body#1body.referenceImageUrls[]string__5kind: schemaFormat; value: uri
body#1body.assetImageUrlsarray<string>__6NoAsset images that MUST appear in the generated image (e.g. a brand logo, a specific product photo). The model will place them faithfully according to the brief, without redrawing them.kind: schemaItems; value: items <= 4
body#1body.assetImageUrls[]string__7kind: schemaFormat; value: uri
body#1body.referenceImageUrlstring__8NoDEPRECATED: use referenceImageUrls instead. Still accepted for backwards compatibility.kind: schemaFormat; value: uri
response#2responseobject__0
response#2response.successboolean__1Yes
response#2response.urlstring__2Yeskind: schemaFormat; value: uri
response#2response.mimeTypestring__3Yes
response#2response.creditsChargednumber__4Yes
response#3responseobject__0
response#3response.successboolean__1Yes
response#3response.messagestring__2Yes