Images

Generate an image

Queues an image generation and returns immediately with the quest that will carry the result - no image yet, and the call never blocks on the render. Poll GET /api/v1/quests/{id} until status is "done" (see the generateImage200PollResult schema). Omit sessionId to create a new session. The prompt is resolved against the session history first, so a follow-up such as "make it darker" binds to the previous image; enhancedPrompt reports the prompt actually sent to the model. Send prompt_resolution: "literal" to skip that step and have the prompt sent as written (apart from truncation to the model's prompt limit). referenceImageFabFileIds passes up to 15 already-uploaded images as style anchors, after the input image taken from fabFileIds. Only gpt-image models accept them: sending any with another model is rejected with a 400 rather than ignored. Which size values a model accepts, and whether it honours background, seed, quality, n and reference images, is listed per model in the image block of GET /api/v1/models. Credits are checked when the render runs, so insufficient credits arrive on the polled quest rather than as a 422. POST /api/ai/generate-image is a legacy alias of this endpoint. Authenticate with an API key (b4m_live_) or a JWT.

Optional callbackUrl: an https URL that receives a signed POST when the quest settles (success, failure, or a stop; a failed render is type: "error" in the body, same as the poll). The body is the GET /api/v1/quests/{id} response. Headers: X-Webhook-Event-ID (the same on every attempt for one settlement; delivery is at-least-once, so dedupe on it, and a retried quest settles again under a new one), X-Webhook-Delivery-ID (unique per attempt), X-Webhook-Timestamp (unix seconds), X-Webhook-Signature-256 (sha256= + hex HMAC-SHA256 of <timestamp>.<raw body> keyed with the API key's callback signing secret), and X-Event-Type: quest.settled. Delivery makes up to 5 attempts, retrying on a 5xx, 408, 429, timeout or network error - never on any other 4xx, and redirects are not followed; your endpoint must answer 2xx within 10 seconds. Requires API-key authentication and a signing secret on that key (returned once at key creation, or via POST /api/user-api-keys/{id}/callback-secret). A callbackUrl is rejected with a 400 when the request is not API-key authenticated, the key has no signing secret, the URL resolves to a private address, or the deployment does not deliver callbacks; a URL that is not https fails request validation with a 422. Polling still works whether or not callbackUrl is set.

post/api/v1/image-generations

Request

  • Base URL: https://your-deployment.example.com
  • URL: https://your-deployment.example.com/api/v1/image-generations
  • Auth: one of:
    • HTTP bearer
    • API key in header x-api-key

Request body

promptstring required
nnumber
quality'standard' | 'hd' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'auto'
response_format'b64_json' | 'url'
style'vivid' | 'natural'
background'transparent' | 'opaque' | 'auto' | 'null' nullable
widthnumber
heightnumber
aspect_ratiostring
sessionIdstring
questIdstring
organizationIdstring nullable

The organization to bill: one you belong to, or null for your personal credits. Omitted bills your home organization, or your personal credits if you have none. An organization-billed API key always bills its own organization: omit this or set it to the key's organization; any other value, null included, is rejected with a 403 (errorCode: billing_organization_mismatch).

fabFileIdsstring[]
referenceImageFabFileIdsstring[]
safety_tolerancenumber
prompt_upsamplingboolean
seednumber nullable
output_format'png' | 'jpeg' | 'webp' | 'null' nullable
sessionNamestring
callbackUrlstring uri

Optional https URL that receives one signed POST when the job settles (success or failure). Requires API-key authentication and a callback signing secret on that key. The body is the GET /api/v1/quests/{id} response. Verify it with the X-Webhook-Signature-256 header: sha256= + hex HMAC-SHA256 of <X-Webhook-Timestamp>.<raw body> keyed with the signing secret. Polling keeps working either way.

projectIdstring
prompt_resolution'auto' | 'literal'

How the prompt is treated before it reaches the image model. "auto" (the default) resolves it against the session history, so a follow-up such as "make it darker" is rewritten to carry the previous subject and the prior image is fed back as input. "literal" skips that step: the prompt is sent unchanged (apart from truncation to the model's prompt limit), intent is "fresh", promptWasEnhanced is false, and a prior session image is carried forward only for models that cannot run without an input image. Use "literal" when the prompt is already self-contained, for example when an agent or pipeline builds it.

Example request

{
  "prompt": "a watercolor lighthouse at dusk",
  "model": "gpt-image-1",
  "size": "1024x1024"
}

Response

Generation queued - NOT a finished render. quest has no images yet; its outcome arrives on GET /api/v1/quests/{id}.

originalPromptstring required
enhancedPromptstring required
promptWasEnhancedboolean required
intent'fresh' | 'continuation' required

Changes

No recorded changes to this operation across all 1 revision of this API.