---
title: "Generate an image"
method: POST
path: "/api/v1/image-generations"
tags: ["Images"]
---

# Generate an image

`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`

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.

## Request body

- GenerateImageRequest
  - `prompt` string, required
  - `model` union, required
    - 'gpt-image-1' | 'gpt-image-1.5' | 'gpt-image-1-mini' | 'gpt-image-2' | 'gpt-image-2.5-sunburst' | 'gpt-image-2.5-flare' | 'flux-pro-1.1' | 'flux-pro' | 'flux-pro-1.1-ultra' | 'flux-pro-1.0-fill' | 'flux-kontext-pro' | 'flux-kontext-max' | 'grok-imagine-image-quality' | 'gemini-2.5-flash-image' | 'gemini-3-pro-image-preview' | 'gemini-3-pro-image' | 'gemini-3.1-flash-image'
    - string
  - `n` number
  - `quality` 'standard' | 'hd' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'auto'
  - `response_format` 'b64_json' | 'url'
  - `size` union
    - '1024x1024' | '1024x1536' | '1536x1024' | '2048x2048' | '2048x1152' | '3840x2160' | '2160x3840' | 'auto' | '1024x768'
    - string
  - `style` 'vivid' | 'natural'
  - `background` 'transparent' | 'opaque' | 'auto' | 'null', nullable
  - `width` number
  - `height` number
  - `aspect_ratio` string
  - `sessionId` string
  - `questId` string
  - `organizationId` string, 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`).
  - `fabFileIds` string[]
  - `referenceImageFabFileIds` string[]
  - `tools` union[]
    - union
      - 'dice_roll' | 'image_generation' | 'edit_image' | 'music_generation' | 'audio_generation' | 'video_generation' | 'weather_info' | 'web_search' | 'web_fetch' | 'wolfram_alpha' | 'math_evaluate' | 'mermaid_chart' | 'current_datetime' | 'deep_research' | 'prompt_enhancement' | 'recharts' | 'edit_file' | 'blog_publish' | 'blog_edit' | 'blog_draft' | 'wikipedia_on_this_day' | 'moon_phase' | 'sunrise_sunset' | 'iss_tracker' | 'planet_visibility' | 'search_knowledge_base' | 'chess_engine' | 'retrieve_knowledge_content' | 'count_knowledge_base' | 'describe_knowledge_base' | 'list_my_data_lakes' | 'create_data_lake' | 'save_content_to_data_lake' | 'delegate_to_agent' | 'optihashi_schedule' | 'optihashi_formulate' | 'optihashi_edit_problem' | 'navigate_view' | 'generate_jupyter_notebook' | 'excel_generation' | 'fmp_financial_data' | 'bob_panel_read' | 'skill'
      - string
  - `safety_tolerance` number
  - `prompt_upsampling` boolean
  - `seed` number, nullable
  - `output_format` 'png' | 'jpeg' | 'webp' | 'null', nullable
  - `sessionName` string
  - `callbackUrl` string, 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.
  - `projectId` string
  - `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.

## Response `200`

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

- GenerateImageResponse200
  - `quest` object, required
    - `id` string, required
    - `status` 'pending' | 'stopped' | 'running' | 'done'
    - `type` 'message' | 'oob' | 'error' | 'system' | 'voice_transcript'
    - `errorCode` 'insufficient_credits' | 'spend_cap_exceeded'
    - `reply` string, nullable
    - `replies` string[]
    - `fallbackInfo` object
      - `primaryModel` string, required
      - `primaryModelName` string, required
      - `fallbackModel` string, required
      - `fallbackModelName` string, required
      - `reason` string
    - `sessionId` string, required
    - `images` string[]
  - `session` object, required
    - `id` string, required
  - `originalPrompt` string, required
  - `enhancedPrompt` string, required
  - `promptWasEnhanced` boolean, required
  - `intent` 'fresh' | 'continuation', required

## Other responses

- `400`: `referenceImageFabFileIds` is set for a non-gpt-image model, or the `callbackUrl` was rejected: the request is not API-key authenticated, the key has no callback signing secret, the URL resolves to a private address, or the deployment does not deliver callbacks. An organization-billed API key bills an organization that no longer exists, or one its owner is no longer a member of; re-mint the key.
- `401`: Missing or invalid credentials.
- `403`: The API key lacks the `ai:generate` scope, or the billing organization names one you do not belong to (or is not a valid id), or an organization-billed API key names any organization but its own (`errorCode: billing_organization_mismatch`).
- `404`: The session, or the quest being retried, does not exist or is not accessible to the caller. A nonexistent billing `organizationId` is `404` only for an admin caller; for anyone else, an invalid or inaccessible `organizationId` is `403` instead.
- `405`: The path does not serve this HTTP method.
- `422`: Request failed validation.

---

[API](https://skmtc.dev/bike4mind/apis/bike4mind-api.md) · [All operations](https://skmtc.dev/bike4mind/apis/bike4mind-api/llms.txt) · [OpenAPI document](https://skmtc.dev/bike4mind/apis/bike4mind-api/revisions/db47495b892f?raw)