## Generate an image

`POST /v1/images/generations`

Creates one image from a text description using BitrixGPT 5.6 Image and returns it as base64. The platform does not store images, so save the image in your application.

Images count toward your Bitrix24 account's AI quota: within the plan's quota, nothing is charged to the balance; beyond it, each image is charged to the account balance at the price in the model's `pricing.perCall` field in [`GET /v1/models`](/docs/ai/models/list). With a Cowork key — a key with the `vibe:cowork` scope — images consume the Cowork subscription quota instead of the account AI quota. Failed calls are not charged. The request and response format is compatible with `POST /v1/images/generations` in the OpenAI API.

> **The response comes in raw OpenAI format.**
>
> The `{success, data}` wrapper used by other Vibecode endpoints — `/v1/deals`, `/v1/tasks` and others — is not returned here.
>
> This ensures compatibility with the OpenAI SDK. If your shared client checks `if (!response.success)`, add an exception for the AI Router.

## Request fields (body)

| Field | Type | Required | Description |
|-------|------|:--------:|-------------|
| `model` | string | yes | Image generation model ID — `bitrix/bitrixgpt-5.6-image`. In `GET /v1/models`, these models have `capabilities.image_generation` |
| `prompt` | string | yes | Image description, from 1 to 4000 characters |
| `size` | string | no | Width and height in pixels separated by a Latin `x`. Dimensions are independent: `1024x1024` is square, `1024x576` is landscape, `576x1024` is portrait. Each side must be from 64 to 1024 pixels. When omitted, the generation service returns a 1024x1024 image |
| `output_format` | string | no | Image format: `png`, `jpeg` or `webp` |
| `negative_prompt` | string | no | What to exclude from the image, up to 4000 characters |
| `seed` | integer | no | Generation seed — an integer starting from `0`. Identical `prompt`, `size` and `seed` produce exactly the same image, so you can generate a successful result again |
| `num_inference_steps` | integer | no | Number of generation steps, from 1 to 8. Default: `4` |
| `response_format` | string | no | Only `b64_json` is accepted |
| `n` | integer | no | Number of images. Only `1` is accepted — the price is per call |
| `user` | string | no | End user identifier in your application, up to 200 characters. Passed to the model unchanged |

Any field outside this list is rejected with `400 invalid_request`.

## Examples

### curl — personal key

```bash
curl -X POST https://vibecode.bitrix24.com/v1/images/generations \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bitrix/bitrixgpt-5.6-image",
    "prompt": "A red fox sitting on a rock by a lake, watercolor",
    "size": "512x512",
    "output_format": "jpeg"
  }'
```

### curl — OAuth application

```bash
curl -X POST https://vibecode.bitrix24.com/v1/images/generations \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bitrix/bitrixgpt-5.6-image",
    "prompt": "A red fox sitting on a rock by a lake, watercolor",
    "size": "512x512",
    "output_format": "jpeg"
  }'
```

### JavaScript — personal key

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/images/generations', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'bitrix/bitrixgpt-5.6-image',
    prompt: 'A red fox sitting on a rock by a lake, watercolor',
    size: '512x512',
    output_format: 'jpeg',
  }),
})

const result = await res.json()
const dataUrl = `data:image/jpeg;base64,${result.data[0].b64_json}`
console.log('Image ready:', dataUrl.slice(0, 60))
```

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/images/generations', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'bitrix/bitrixgpt-5.6-image',
    prompt: 'A red fox sitting on a rock by a lake, watercolor',
    size: '512x512',
    output_format: 'jpeg',
  }),
})

const result = await res.json()
const dataUrl = `data:image/jpeg;base64,${result.data[0].b64_json}`
console.log('Image ready:', dataUrl.slice(0, 60))
```

## Response fields

| Field | Type | Description |
|-------|------|-------------|
| `created` | number | Creation time as a Unix timestamp in seconds |
| `data` | array | Generated images. One image per call |
| `data[].b64_json` | string | Image encoded as `base64` |
| `output_format` | string | Image format. Present when reported by the generation service |
| `size` | string | Image width and height in pixels, such as `512x512`. Present when reported by the generation service |

## Response example

The `b64_json` string is shortened: a real response contains the entire image, about 140 KB for a 512x512 JPEG.

```json
{
  "created": 1789740000,
  "data": [
    { "b64_json": "/9j/4AAQSkZJRgABAQAAAQABAAD..." }
  ],
  "output_format": "jpeg",
  "size": "512x512"
}
```

## Error response example

`400 invalid_request` — an image side exceeds 1024 pixels:

```json
{
  "error": {
    "message": "size: each side must be between 64 and 1024 pixels",
    "type": "invalid_request_error",
    "code": "invalid_request"
  }
}
```

## Errors

| HTTP | Code | Description |
|------|------|-------------|
| 400 | `invalid_request` | Body validation failed: unknown field, empty `prompt`, a side outside 64–1024, `n` other than `1`, or `response_format` other than `b64_json`. Checked before quota and generation; nothing is charged |
| 400 | `ai_provider_rejected` | The generation service rejected the request with 400 or 422. `providerStatusCode` carries the original status. Retrying unchanged will not help |
| 402 | `insufficient_balance` | Except with a Cowork key: the account's prepaid balance is past its overdraft limit. Checked before generation |
| 402 | `ai_quota_exhausted` | Except with a Cowork key: the monthly AI quota is exhausted and the image cannot be paid for beyond it — see "Known specifics" |
| 402 | `account_frozen` | Except with a Cowork key: the billing account is frozen due to debt and the image exceeds the AI quota, so it would draw on the balance. Images within the quota keep working under this freeze |
| 402 | `ACCOUNT_FROZEN` | The billing account is frozen due to debt. For some accounts, the freeze rejects every generation call, including calls within the quota and Cowork calls. The response uses the `{success, error}` envelope and an uppercase code — [what the refusal covers](/docs/errors) |
| 402 | `company_budget_exhausted` | Except with a Cowork key: the monthly company spend budget set by the Bitrix24 account administrator is exhausted. `scope` identifies the budget: `USER` for the caller, `PORTAL` for the whole account. `canRequest` says whether an increase can be requested. Refused only for images beyond the quota that draw on the account balance |
| 402 | `cowork_subscription_inactive` | Cowork keys only: generation is paid from a Cowork subscription seat, but the key owner has no active seat |
| 402 | `cowork_subscription_inactive` | Cowork keys only: the subscription is suspended because the account balance was insufficient. `reason` is `INSUFFICIENT_BALANCE`; `topupUrl` links to the balance top-up page |
| 402 | `cowork_model_not_allowed` | Cowork keys only: the requested model is outside the Cowork model set for this account |
| 402 | `cowork_quota_exhausted` | Cowork keys only: the seat quota for the window is exhausted. `window` identifies the window, `resetAt` the reset time, and `nextTier` the next subscription tier. Retry after the number of seconds in `Retry-After` |
| 402 | `ai_credentials_not_configured` | Access to the generation service is not configured on the platform |
| 403 | `scope_missing` | The API key lacks the `vibe:ai` scope |
| 404 | `not_found` | Image generation is unavailable to your key or Bitrix24 account |
| 404 | `ai_model_not_found` | `model` is not an image generation model available to the key. Available models appear in `GET /v1/models` with `capabilities.image_generation`. Nothing is charged |
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header was not provided |
| 429 | `ai_image_congested` | The generation service is busy. The request was not executed and nothing was charged — retry after the number of seconds in `Retry-After` |
| 429 | `ai_congested` | The AI cluster pool is overloaded. The request was not executed and nothing was charged — retry per `Retry-After`. The response carries `X-AI-Admission: shed` |
| 429 | `ai_pacing_limited` | Except with a Cowork key: the daily or weekly quota pacing window was exceeded. The quota itself is not exhausted — retry per `Retry-After`. See [quota pacing](/docs/ai/consumption/quota#pacing-day-week-smoothing) |
| 429 | `rate_limit_exceeded` | The AI endpoint rate limit was exceeded, or the generation service limited the request rate. In the latter case, `providerStatusCode` is present. Retry per `Retry-After` |
| 429 | `ai_provider_cooldown` | The generation service is temporarily unavailable and the platform pauses requests. Nothing was executed or charged — retry per `Retry-After` |
| 500 | `ai_credentials_invalid` | The platform credentials for the generation service lack an access key. Retrying will not help |
| 502 | `ai_provider_unavailable` | The generation service is unavailable, returned an internal error, or returned no image. Nothing is charged; retry the request |
| 502 | `ai_provider_network` | The platform could not connect to the generation service. Nothing is charged; retry the request |
| 503 | `ai_provider_timeout` | The image was not ready within 60 seconds. Nothing is charged — retry per `Retry-After` |
| 503 | `ai_cluster_not_configured` | The image generation service is not connected to the platform |

For common API errors, see [Errors](/docs/errors).

## Known specifics

**Discover the model by capability.** Image models appear alongside chat models in `GET /v1/models` and carry `capabilities.image_generation`. If none appears, image generation is unavailable to your key or account and the endpoint returns `404`. You do not need to hard-code the model ID.

**Text descriptions only.** The endpoint does not accept an input image: there is no reference image field in the request body. `prompt` describes what to include and `negative_prompt` what to exclude.

**Within the quota, no balance charge; beyond it, a per-image price.** With a key without `vibe:cowork`, each successful image consumes the account's monthly AI quota. Within the plan quota, nothing is charged to the balance. Beyond it, the balance is charged at `pricing.perCall`. If the quota is exhausted and payment beyond it is unavailable, the response is `402 ai_quota_exhausted`. `reason` distinguishes three cases: `breaker` — the hourly safeguard for spend beyond the quota was reached; `wallet_empty` — the account balance has no funds; `wallet_off` — spend beyond the quota is unavailable. `resetAt` says when requests can resume; it may be absent for `wallet_off`. When the account has no paid access to AI models, a `wallet_off` response also carries `details.learnMoreUrl`, linking to the Bitrix24 plan that includes AI, and `message` names the required product. Other `wallet_off` reasons do not include `details.learnMoreUrl`. Cowork keys follow a different path: images consume the subscription quota, and exhaustion returns `402 cowork_quota_exhausted`. That path neither charges the account balance at `pricing.perCall` nor returns `ai_quota_exhausted`.

**Concurrency is limited.** The generation service handles a limited number of requests at a time; others wait in a queue. When the queue is full, the request immediately returns `429 ai_image_congested` without generation. An image not ready within 60 seconds returns `503 ai_provider_timeout`. Higher `num_inference_steps` and larger images increase both your request time and the wait for queued requests.

**Images are not stored.** The image is returned only in `data[].b64_json`: the platform provides no file URL and cannot serve it again. Save it as soon as you receive the response.

## See also

- [Model list](/docs/ai/models/list)
- [Consumption and limits](/docs/ai/consumption)
- [AI Router](/docs/ai)
