Generate Image
Queue an image from a text prompt and poll for the result. Returns a job ID straight away rather than holding the connection open.
Permission: ai.generate. See Roles and permissions.
Images take roughly 10 to 40 seconds, too long to hold an HTTP request open. So generation is two calls: start a job, then poll it.
POST /api/v1/ai/images
POST /api/v1/ai/images{
"prompt": "a red bicycle leaning against a yellow wall, soft morning light",
"aspectRatio": "16:9",
"model": "premium"
}| Field | Required | Description |
|---|---|---|
| prompt | Yes | What to draw. Up to 2000 characters |
| aspectRatio | No | 1:1 (default), 16:9, 9:16, 3:2, 2:3, 4:5, 5:4, 21:9, 9:21 |
| model | No | standard (default) or premium |
| quality | No | LOW, MEDIUM or HIGH |
| sessionId | No | Groups related images. Omit it and one is created for you |
| referenceImages | No | Up to 5 public image URLs to steer the result |
{
"jobId": "generate-image-8f2a1c40-6d3b-4e91-b7c2-0a5d9e13f846",
"sessionId": "b31c7a44-2f19-4c85-9d60-7e2af4c81b93",
"status": "queued"
}Keep the sessionId and pass it on the next call to keep a set of images together, the way a conversation keeps its messages. Leave it out and every image starts its own session.
GET /api/v1/ai/images/{jobId}
GET /api/v1/ai/images/generate-image-8f2a1c40-6d3b-4e91-b7c2-0a5d9e13f846{
"jobId": "generate-image-8f2a1c40-6d3b-4e91-b7c2-0a5d9e13f846",
"sessionId": "b31c7a44-2f19-4c85-9d60-7e2af4c81b93",
"status": "completed",
"imageUrl": "https://cdn.adaptlypost.com/ai-images/ai-studio-4c81b93.png",
"imageId": "d7e44a10-93bc-4f27-8ae5-1b06c2f4d938",
"error": null
}| Status | Meaning |
|---|---|
queued | Waiting for a worker |
generating | The model is drawing |
processing | Uploading the result |
completed | imageUrl is ready to use |
failed | error says why |
Poll every 3 to 5 seconds. Anything faster just burns rate limit.
If you would rather not poll at all, register a webhook and we will POST image.completed with the same fields the moment the job finishes, or image.failed with the reason.
imageUrl points at the CDN and can go straight into the mediaUrls of a post, so generating and scheduling is: create the image, poll until completed, then create a post with that URL.
Credits
Credits are charged when generation starts and refunded automatically if it fails, so a failed job costs nothing. With your own OpenAI or Google key connected, images run on your key and skip credits entirely. premium and standard draw different amounts.