# Сгенерировать изображение

`POST /v1/images/generations`

> Генерация картинки по `prompt` в OpenAI-формате; ответ — `data[].b64_json` (default `response_format=b64_json`). Непустое поле `image` переключает запрос в режим редактирования (instruct-edit) — модель должна иметь capability `image_input`, иначе 400 `unsupported_capability`. Списание — после успешного ответа провайдера (по usage либо фикс-цене за картинку), при ошибке апстрима денег не берём; rate-limit — общий bucket 60 запросов в минуту на аккаунт.

Авторизация: заголовок `Authorization: Bearer <API-ключ>` (ключ sk-aiagg-… из личного кабинета). Base URL: `https://api.trackly.one/v1`.

Веб-версия: https://ai.trackly.one/developers/docs/reference/images-generations · Индекс документации: https://ai.trackly.one/llms.txt

## Тело запроса (ImageGenerationRequest)

Content-Type: `application/json`.

| Поле | Тип | Обязательное | Описание |
| --- | --- | --- | --- |
| `image` | `array<ImageInput> \| null` | нет | — |
| `mask` | `ImageInput \| null` | нет | — |
| `model` | `string` | да | — |
| `n` | `integer` | нет | По умолчанию: 1 |
| `prompt` | `string` | да | — |
| `quality` | `string \| null` | нет | — |
| `reference_images` | `array<ImageInput> \| null` | нет | — |
| `response_format` | `"b64_json" \| "url"` | нет | По умолчанию: "b64_json" |
| `size` | `string \| null` | нет | — |

## Схема ImageInput

Картинка, которую юзер передал во входе запроса.

Два варианта `type`:
  - `url`     — внешний URL, провайдер (или мы) скачаем по запросу.
  - `base64`  — уже сырые байты в base64 (без data:image/...; префикса).

`mime_type` обязателен для base64 (нужен Gemini для inline_data),
для url — опционально (можно определить из ответа).

| Поле | Тип | Обязательное | Описание |
| --- | --- | --- | --- |
| `data` | `string` | да | Длина 1–∞ символов |
| `mime_type` | `string \| null` | нет | image/png, image/jpeg, image/webp |
| `type` | `"url" \| "base64"` | да | — |

## Схема ImageGenerationResponse

| Поле | Тип | Обязательное | Описание |
| --- | --- | --- | --- |
| `created` | `integer` | нет | — |
| `data` | `array<ImageData>` | да | — |
| `usage` | `ImageUsage \| null` | нет | — |

## Схема ImageData

Одна сгенерированная картинка.

| Поле | Тип | Обязательное | Описание |
| --- | --- | --- | --- |
| `b64_json` | `string \| null` | нет | — |
| `revised_prompt` | `string \| null` | нет | — |
| `url` | `string \| null` | нет | — |

## Схема ImageUsage

Usage для image-моделей. gpt-image даёт полный breakdown,
gemini — только total_tokens, imagen — все нули.

| Поле | Тип | Обязательное | Описание |
| --- | --- | --- | --- |
| `input_tokens` | `integer` | нет | По умолчанию: 0 |
| `output_tokens` | `integer` | нет | По умолчанию: 0 |
| `total_tokens` | `integer` | нет | По умолчанию: 0 |

## Ответы

| Код | Описание | Схема |
| --- | --- | --- |
| 200 | Успешный ответ | `ImageGenerationResponse` |
| 422 | Ошибка валидации тела запроса или параметров | — |

## Пример запроса

```bash
curl https://api.trackly.one/v1/images/generations \
  -H "Authorization: Bearer $TRACKLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-2.5-flash-image",
    "prompt": "Уютное кафе на морском берегу на закате, акварель",
    "size": "1024x1024",
    "response_format": "b64_json"
  }'
```

```python
import base64

from openai import OpenAI

client = OpenAI(
    api_key="sk-aiagg-...",
    base_url="https://api.trackly.one/v1",
)

resp = client.images.generate(
    model="google/gemini-2.5-flash-image",
    prompt="Уютное кафе на морском берегу на закате, акварель",
    size="1024x1024",
)
with open("cafe.png", "wb") as f:
    f.write(base64.b64decode(resp.data[0].b64_json))
```

```javascript
import fs from "node:fs";
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "sk-aiagg-...",
  baseURL: "https://api.trackly.one/v1",
});

const resp = await client.images.generate({
  model: "google/gemini-2.5-flash-image",
  prompt: "Уютное кафе на морском берегу на закате, акварель",
  size: "1024x1024",
});
fs.writeFileSync("cafe.png", Buffer.from(resp.data[0].b64_json, "base64"));
```

## Пример ответа

```json
{
  "created": 1752395418,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAABAAAAAQ…"
    }
  ],
  "usage": {
    "input_tokens": 14,
    "output_tokens": 1290,
    "total_tokens": 1304
  }
}
```