# Генерация изображений: как использовать

> Гайд по /v1/images/generations и /v1/images/edits — параметры, base64-ответ, редактирование через multipart и JSON, лимит 20 МБ.

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

Картинки генерируются запросом `POST /v1/images/generations`: обязательны
`model` и `prompt`, ответ приходит в `data[].b64_json`. Редактирование — это
`POST /v1/images/edits`: multipart с файлами, как в OpenAI SDK, или JSON с
base64 (суммарно до 20 МБ). Для редактирования модель должна принимать
картинки на вход — например, `google/gemini-2.5-flash-image`. Списание — после
успешной генерации.

## Как сгенерировать картинку?

**POST /v1/images/generations**

```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"
  }'
```

```python
import base64

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";

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"));
```

По умолчанию `response_format` = `b64_json`, то есть картинка приходит прямо
в теле ответа — остаётся декодировать base64 и сохранить. В `usage` — расход
токенов (состав зависит от модели: gpt-image даёт полный разбор, gemini —
только `total_tokens`, imagen токены не считает).

## Какие параметры поддерживаются?

Основные: `n` (количество картинок), `size` («1024x1024» и т.п.), `quality`,
`response_format` (`b64_json` | `url`). Это passthrough-поля — что именно
умеет конкретная модель, решает она сама. Полная таблица полей — в
[референсе images/generations](https://ai.trackly.one/developers/docs/reference/images-generations).

Генерировать умеют модели с пометкой «image» в
[каталоге](https://ai.trackly.one/developers/models): семейства `gpt-image`, `gemini-*-image`,
`imagen`. Текстовая модель в этом эндпоинте ответит 400
`unsupported_capability`.

## Как отредактировать картинку?

Эндпоинт `POST /v1/images/edits` принимает два формата тела:

- **multipart/form-data** — так работает `client.images.edit()` в OpenAI
  SDK: файл `image` (можно несколько), опционально `mask`, плюс `prompt` и
  `model`;
- **application/json** — то же тело, что у generations, с полем `image`
  (массив картинок как base64 или URL) — удобно для curl и бэкендов, где
  файла на диске нет.

Суммарный размер файлов — не больше 20 МБ.

**POST /v1/images/edits**

```bash
curl https://api.trackly.one/v1/images/edits \
  -H "Authorization: Bearer $TRACKLY_API_KEY" \
  -F model="google/gemini-2.5-flash-image" \
  -F prompt="Сделай небо закатным, остальное не трогай" \
  -F image=@photo.png
```

```python
resp = client.images.edit(
    model="google/gemini-2.5-flash-image",
    prompt="Сделай небо закатным, остальное не трогай",
    image=open("photo.png", "rb"),
)
# ответ тот же, что у generations: data[0].b64_json
```

```javascript
import fs from "node:fs";
import { toFile } from "openai";

const resp = await client.images.edit({
  model: "google/gemini-2.5-flash-image",
  prompt: "Сделай небо закатным, остальное не трогай",
  image: await toFile(fs.createReadStream("photo.png"), "photo.png"),
});
```

JSON-вариант того же запроса — картинка объектом
`{ "type": "base64", "data": "<...>", "mime_type": "image/png" }` или
`{ "type": "url", "data": "https://..." }` в массиве `image`. Все поля — в
[референсе images/edits](https://ai.trackly.one/developers/docs/reference/images-edits).

Тот же режим редактирования включается и в `/v1/images/generations`, если
передать туда непустое поле `image`, — `/v1/images/edits` существует для
совместимости с SDK, внутри это один путь.

## Какая модель подходит для редактирования?

Та, что принимает картинки на вход (capability `image_input`) — сейчас это
семейство `gemini-*-image`. Модель без этой возможности (например,
`imagen-4`) ответит 400 `unsupported_capability` — подробнее про коды в
гайде [«Ошибки API»](https://ai.trackly.one/developers/docs/errors). Актуальные пометки по каждой
модели — в [каталоге моделей](https://ai.trackly.one/developers/models).

## Сколько стоит генерация?

Зависит от модели: где-то тариф за картинку, где-то по токенам. Цены в
рублях — на странице [цен для разработчиков](https://ai.trackly.one/developers/pricing), списание
только после успешного ответа. Пощупать генерацию и редактирование без кода
можно в [генераторе изображений на сайте](https://ai.trackly.one/chat/gemini-image-flash).