> ## Documentation Index
> Fetch the complete documentation index at: https://docs.laozhang.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Images API: генерация и редактирование изображений через LaoZhang API

> Запросы к /v1/images/generations и /v1/images/edits с полными примерами на cURL и Python: загрузка файла, чтение b64_json и url, сохранение результата и обработка ошибок.

Создавайте изображения по тексту или загружайте изображение и описывайте, что в нём изменить. Оба эндпоинта возвращают ответ в формате OpenAI Images.

| Параметр | Значение |
| - | - |
| Генерация | `POST /v1/images/generations` |
| Редактирование | `POST /v1/images/edits` |
| Результат | Каждое изображение в `data[]`, в виде `b64_json` или `url` |
| Модели в примерах | `gpt-image-2.5-flare-vip` для генерации, `gpt-image-2.5-sunburst-vip` для редактирования |

Нативная генерация и правка изображений Gemini через модели Nano Banana описаны в [обзоре Nano Banana](https://docs.laozhang.ai/ru/api-capabilities/nano-banana-image.md). Сравнить модели изображений и эндпоинты можно на странице [Сравнение API изображений](https://docs.laozhang.ai/ru/api-capabilities/image-generation-guide.md).

## Ключ и параметры подключения

Создайте API-ключ для моделей в разделе [Управление токенами](https://api.laozhang.ai/token) и сделайте его доступным через переменную окружения `LAOZHANG_API_KEY`. Убедитесь, что группе ключа доступны модели GPT Image 2.5 VIP, в разделе [Модели и цены в консоли](https://api.laozhang.ai/account/pricing).

Задайте ключ в терминале, заменив заглушку:

```bash theme={null}
export LAOZHANG_API_KEY="YOUR_LAOZHANG_API_KEY"
```

В примерах ниже используются:

* **Хост API:** `https://api.laozhang.ai`
* **Базовый URL для OpenAI SDK:** `https://api.laozhang.ai/v1`
* **Аутентификация:** `Authorization: Bearer $LAOZHANG_API_KEY`
* **Модели:** `gpt-image-2.5-flare-vip` (генерация) и `gpt-image-2.5-sunburst-vip` (редактирование)

Установите пакеты Python для вызова API и сохранения изображений. Примеры с cURL тоже используют Python, чтобы декодировать ответ и выбрать правильное расширение файла.

```bash theme={null}
python -m pip install openai pillow httpx
```

### Сохранение изображений из ответа

Сохраните этот вспомогательный модуль как `save_images.py` в папке, из которой запускаете примеры. Он записывает на диск каждое изображение из `data[]`, независимо от того, содержит ли элемент `b64_json` или `url`:

```python theme={null}
"""Сохранение всех изображений из ответа OpenAI Images API."""
import base64
import io
import json
import sys
from pathlib import Path

import httpx
from PIL import Image

EXTENSIONS = {"PNG": "png", "JPEG": "jpg", "WEBP": "webp"}


def image_bytes(item):
    """Возвращает байты изображения из одного элемента data[]."""
    encoded = item.get("b64_json")
    if encoded:
        encoded = "".join(encoded.split())
        if encoded.startswith("data:"):
            encoded = encoded.split(",", 1)[1]  # убираем префикс data:image/...;base64,
        encoded += "=" * (-len(encoded) % 4)  # восстанавливаем выравнивание
        return base64.b64decode(encoded)
    if item.get("url"):
        # Скачиваем результат, не отправляя свой API-ключ LaoZhang API.
        download = httpx.get(item["url"], timeout=120, follow_redirects=True)
        download.raise_for_status()
        return download.content
    raise ValueError("В элементе data[] нет ни b64_json, ни url")


def save_images(response, stem):
    """Сохраняет каждое изображение как <stem>.<ext>, затем <stem>-2.<ext> и так далее."""
    entries = response.get("data") or []
    if not entries:
        raise RuntimeError(f"В ответе нет изображений: {json.dumps(response)[:500]}")
    for number, item in enumerate(entries, start=1):
        raw = image_bytes(item)
        with Image.open(io.BytesIO(raw)) as image:
            image.load()
            extension = EXTENSIONS.get(image.format, (image.format or "bin").lower())
            size = f"{image.width} × {image.height}"
        suffix = "" if number == 1 else f"-{number}"
        output = Path(f"{stem}{suffix}.{extension}")
        output.write_bytes(raw)
        print(f"Сохранено: {output} ({size})")


if __name__ == "__main__":
    save_images(json.loads(Path(sys.argv[1]).read_text(encoding="utf-8")), sys.argv[2])
```

После запроса через cURL запустите его как `python save_images.py <ответ.json> <имя>`, а в Python импортируйте функцию `save_images`.

## Генерация изображения

Отправьте JSON с полями `model` и `prompt` на эндпоинт:

```text theme={null}
POST https://api.laozhang.ai/v1/images/generations
```

Эти примеры создают изображение товара и сохраняют его как `generated.png`, `generated.jpg` или `generated.webp` — в зависимости от формата возвращённого файла.

> [tab] cURL
>
> ```bash theme={null}
> curl --fail-with-body --max-time 360 \
>   "https://api.laozhang.ai/v1/images/generations" \
>   -H "Authorization: Bearer $LAOZHANG_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "model": "gpt-image-2.5-flare-vip",
>     "prompt": "Синяя керамическая чашка на белом столе, мягкий естественный свет, предметная фотосъёмка."
>   }' \
>   -o generation-response.json
> ```
>
> Когда запрос завершится, сохраните изображение из `generation-response.json`:
>
> ```bash theme={null}
> python save_images.py generation-response.json generated
> ```

> [tab] Python
>
> ```python theme={null}
> import os
> from openai import OpenAI
> from save_images import save_images
>
> client = OpenAI(
>     api_key=os.environ["LAOZHANG_API_KEY"],
>     base_url="https://api.laozhang.ai/v1",
>     timeout=360.0,
>     max_retries=0,
> )
> response = client.images.generate(
>     model="gpt-image-2.5-flare-vip",
>     prompt="Синяя керамическая чашка на белом столе, мягкий естественный свет, предметная фотосъёмка.",
> )
> save_images(response.model_dump(), "generated")
> ```

Чтобы увидеть результат, откройте сохранённое изображение. Файл `.json` содержит ответ API, и если сменить его расширение на `.png`, изображением он не станет.

## Редактирование изображения

Положите изображение `input.png` в папку, из которой запускаете команду. Отправьте файл и инструкцию как multipart form data на эндпоинт:

```text theme={null}
POST https://api.laozhang.ai/v1/images/edits
```

Примеры ниже меняют фон и сохраняют результат как `edited.png`, `edited.jpg` или `edited.webp`.

> [tab] cURL
>
> ```bash theme={null}
> curl --fail-with-body --max-time 360 \
>   "https://api.laozhang.ai/v1/images/edits" \
>   -H "Authorization: Bearer $LAOZHANG_API_KEY" \
>   -F "model=gpt-image-2.5-sunburst-vip" \
>   -F "image[]=@input.png" \
>   -F 'prompt=Сделай фон бледно-голубым. Объект оставь без изменений.' \
>   -o edit-response.json
> ```
>
> Когда запрос завершится, сохраните изображение из `edit-response.json`:
>
> ```bash theme={null}
> python save_images.py edit-response.json edited
> ```

> [tab] Python
>
> ```python theme={null}
> import os
> from openai import OpenAI
> from save_images import save_images
>
> client = OpenAI(
>     api_key=os.environ["LAOZHANG_API_KEY"],
>     base_url="https://api.laozhang.ai/v1",
>     timeout=360.0,
>     max_retries=0,
> )
> with open("input.png", "rb") as source:
>     response = client.images.edit(
>         model="gpt-image-2.5-sunburst-vip",
>         image=[source],
>         prompt="Сделай фон бледно-голубым. Объект оставь без изменений.",
>     )
> save_images(response.model_dump(), "edited")
> ```

`image[]=@input.png` загружает содержимое файла; путь к файлу строкой в JSON локальный файл не загружает. С опцией `-F` в cURL тип multipart-содержимого и границу выставляет сам cURL, поэтому не добавляйте `Content-Type: application/json`.

Опишите и нужное изменение, и детали, которые должны сохраниться. Редактирование генеративное, поэтому даже инструкция «объект не меняй» не гарантирует совпадения пикселей за пределами изменённой области.

## Параметры запроса

Минимальные примеры используют настройки вывода модели по умолчанию. Чтобы выбрать размер или качество, берите параметры, указанные для конкретной модели в руководствах [GPT Image 2.5](https://docs.laozhang.ai/ru/api-capabilities/gpt-image-2-5.md) или [GPT Image 2](https://docs.laozhang.ai/ru/api-capabilities/gpt-image-2.md).

| Поле | Назначение |
| - | - |
| `model` | Обязательный ID модели, включая суффикс вроде `-vip` |
| `prompt` | Обязательное описание изображения или нужных изменений |
| `image[]` | Обязательная загрузка файла для multipart-запроса на редактирование |
| `size` | Необязательный размер вывода; допустимые значения зависят от модели |
| `quality` | Необязательная настройка качества; значения зависят от модели |
| `n` | Необязательное число изображений в пределах лимитов модели |

У GPT Image и DALL·E разные параметры. Не переносите `quality="hd"` и `style` из DALL·E в запрос GPT Image. Маски, несколько референсных изображений, прозрачный фон и выбор формата вывода тоже настраиваются по инструкциям для конкретной модели; для правки одного локального изображения достаточно простой загрузки файла, показанной выше.

## Чтение результата

Каждый элемент `data[]` — это одно выходное изображение в одном из двух видов:

* **`b64_json`** содержит байты изображения в Base64. Некоторые ответы добавляют префикс `data:image/...;base64,` или отбрасывают завершающее выравнивание `=`, поэтому перед декодированием уберите префикс и восстановите выравнивание, как это делает `save_images.py`.
* **`url`** — ссылка для скачивания. Скачайте файл сразу, не передавая свой API-ключ LaoZhang API, и храните собственную копию: ссылки в результате могут истекать.

Если запрошено несколько изображений, обработайте все элементы `data[]`. ID задачи генерации изображения или ответ Gemini с `candidates` имеют другой формат, и для них нужен обработчик соответствующего API.

## Ошибки и повторы

* **400:** проверьте поля запроса и параметры модели. Для редактирования убедитесь, что файл загружен как multipart.
* **401 или 403:** проверьте API-ключ, группу токена и права на модель.
* **404 или ошибка недоступной модели:** проверьте эндпоинт и точный ID модели в разделе [Модели и цены в консоли](https://api.laozhang.ai/account/pricing).
* **429:** прочитайте тело ошибки, чтобы отличить лимит частоты или параллельности от проблем с балансом аккаунта.
* **5xx или таймаут:** проверьте [журнал вызовов](https://docs.laozhang.ai/en/faq/call-logs.md), прежде чем отправлять запрос на изображение повторно.

Таймаут на клиенте не отменяет генерацию на сервере. Примеры на Python отключают автоматические повторы SDK, чтобы приложение само решало, повторять ли запрос.

Актуальные цены и единицы тарификации показаны в консоли; условия обслуживания и возврата средств описаны в [Условиях использования](https://www.laozhang.ai/terms).

## Связанные материалы

* [Руководство по подключению](https://docs.laozhang.ai/ru/api-manual.md)
* [Сравнение API изображений](https://docs.laozhang.ai/ru/api-capabilities/image-generation-guide.md)
* [Обзор Nano Banana](https://docs.laozhang.ai/ru/api-capabilities/nano-banana-image.md)
* [Руководство OpenAI по генерации изображений](https://developers.openai.com/api/docs/guides/image-generation)
* [Справочник OpenAI по редактированию изображений](https://developers.openai.com/api/reference/resources/images/methods/edit)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.