> ## 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.

# FLUX.2 API: редактирование изображений и до 8 референсов

> Как редактировать изображения моделями flux-2-pro, flux-2-flex и flux-2-max в LaoZhang API: JSON-запрос с референсами, локальные файлы, пример на Python и сохранение результата до истечения ссылки.

FLUX.2 редактирует изображения через тот же JSON-эндпоинт, что и генерирует: передайте одно изображение, чтобы изменить его, или объедините несколько референсов. Запросы оплачиваются за вызов, а ссылка на результат действует 10 минут после генерации.

| Параметр | Значение |
| - | - |
| Эндпоинт | `POST https://api.laozhang.ai/v1/images/generations` с телом JSON |
| Изображение для правки | Передайте `prompt` и `input_image` |
| Дополнительные референсы | От `input_image_2` до `input_image_8`, всего до восьми изображений |
| Формат референса | Публичный URL изображения или URL вида `data:` |
| Цена | `flux-2-pro` — \$0.03 за вызов, `flux-2-flex` — \$0.06, `flux-2-max` — \$0.07; публичные цены на 24 сентября 2026 года (см. [Цены на API моделей ИИ](https://docs.laozhang.ai/ru/models.md)) |
| Результат | `data[0].url`; ссылка действует 10 минут после генерации, поэтому скачивайте сразу |

Начните с `flux-2-pro`. Black Forest Labs рекомендует `flux-2-max` для самых точных правок, а `flux-2-flex` — для тонкого контроля, например отрисовки текста и мелких деталей. Запрос у всех трёх моделей одинаковый.

## Подготовка

**1. Создайте API-ключ**

Модели FLUX.2 оплачиваются за вызов. В разделе [Управление токенами](https://api.laozhang.ai/token) создайте ключ (или измените существующий) и выберите **Режим оплаты** (计费模式) — **«сначала по использованию»** (按量优先, рекомендуется) или **«оплата за вызов»** (按次计费). Ключ с режимом «сначала по использованию» вызывает и модели с оплатой за вызов, и модели с оплатой по использованию; ключ с оплатой за вызов — только модели с оплатой за вызов.

Храните ключ в переменной окружения на сервере.

![Диалог создания токена в консоли LaoZhang API с режимом оплаты «оплата за вызов» (按次计费)](https://mintcdn.com/laozhangai-edd05f2c/_loZ0Jy0ZI__xJ9z/images/token-create-per-request.png?fit=max\&auto=format\&n=_loZ0Jy0ZI__xJ9z\&q=85\&s=1fdceb804bb3ad50f83a21ec65b4d807)

**2. Настройте окружение**

Экспортируйте ключ и установите `requests`, который нужен примеру на Python:

```bash theme={null}
export LAOZHANG_API_KEY="sk-..."  # замените на свой API-ключ LaoZhang API
python3 -m pip install requests
```

**3. Сохраните скрипт скачивания**

Сохраните скрипт как `save_images.py`. Примеры на cURL запускают его для файла ответа, чтобы скачать все изображения. FLUX возвращает только URL, но скрипт умеет декодировать и `b64_json`, который возвращают некоторые другие модели изображений:

```python save_images.py theme={null}
import base64
import json
import sys
import urllib.request
from pathlib import Path

response_file, stem = sys.argv[1], sys.argv[2]
response = json.loads(Path(response_file).read_text())
if not response.get("data"):
    sys.exit(f"В {response_file} нет изображения: {response}")

for number, item in enumerate(response["data"], start=1):
    if item.get("b64_json"):
        # Убираем необязательный префикс data:image/...;base64, и восстанавливаем недостающее выравнивание.
        value = item["b64_json"].split(",", 1)[-1]
        image = base64.b64decode(value + "=" * (-len(value) % 4))
    else:
        with urllib.request.urlopen(item["url"], timeout=120) as download:
            image = download.read()
    if image.startswith(b"\x89PNG"):
        extension = "png"
    elif image[:4] == b"RIFF" and image[8:12] == b"WEBP":
        extension = "webp"
    else:
        extension = "jpg"
    path = Path(f"{stem}-{number}.{extension}")
    path.write_bytes(image)
    print(f"Сохранено: {path}")
```

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

Добавьте `input_image` в запрос генерации, и он станет редактированием. Замените URL на публично доступное изображение:

```bash theme={null}
curl --fail-with-body --max-time 300 "https://api.laozhang.ai/v1/images/generations" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2-pro",
    "prompt": "Сохрани тот же главный объект. Замени фон на чистый бледно-голубой студийный фон и сохрани исходное освещение.",
    "input_image": "https://example.com/source.png",
    "width": 1792,
    "height": 1024,
    "output_format": "png"
  }' \
  -o flux-edit.json

python3 save_images.py flux-edit.json flux-edit
```

Скрипт выведет `Сохранено: flux-edit-1.png`. Референс скачивается во время запроса, поэтому URL должен открываться без входа в аккаунт, cookie и проверок на бота.

> [!WARNING]
>
> **Чтобы объединить референсы, отправляйте JSON на `/v1/images/generations` и кладите каждый референс в своё поле `input_image`.**
>
> * Multipart-эндпоинт `/v1/images/edits` принимает один файл в поле `image` и объединять референсы не умеет.

### Редактирование локального файла

Чтобы отредактировать файл со своего компьютера, передайте его как data URL с MIME-типом, соответствующим файлу, например `data:image/png;base64,...` для PNG. Тело запроса через heredoc не даёт большому изображению попасть в командную строку:

```bash theme={null}
IMG=$(base64 < product.png | tr -d '\n')

curl --fail-with-body --max-time 300 "https://api.laozhang.ai/v1/images/generations" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- \
  -o flux-local-edit.json <<EOF
{
  "model": "flux-2-pro",
  "prompt": "Поставь товар на мраморную столешницу в мягком утреннем свете. Сам товар и его этикетку не меняй.",
  "input_image": "data:image/png;base64,$IMG",
  "size": "1024x1024",
  "output_format": "png"
}
EOF

python3 save_images.py flux-local-edit.json flux-product
```

## Объединение референсных изображений

Для дополнительных референсов добавьте поля от `input_image_2` до `input_image_8` и называйте их в промпте «изображение 1», «изображение 2» и так далее — в порядке полей. Этот пример берёт три PNG-файла из текущего каталога:

```bash theme={null}
IMG1=$(base64 < robot.png | tr -d '\n')
IMG2=$(base64 < greenhouse.png | tr -d '\n')
IMG3=$(base64 < skateboard.png | tr -d '\n')

curl --fail-with-body --max-time 300 "https://api.laozhang.ai/v1/images/generations" \
  -H "Authorization: Bearer $LAOZHANG_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- \
  -o flux-multi-edit.json <<EOF
{
  "model": "flux-2-pro",
  "prompt": "Объедини три референса в одно цельное новое изображение. Изображение 1 — красный робот, изображение 2 — фон с бирюзовой стеклянной оранжереей, изображение 3 — жёлтый скейтборд. Используй детали всех трёх референсов. Не делай коллаж и не дели кадр на части.",
  "input_image": "data:image/png;base64,$IMG1",
  "input_image_2": "data:image/png;base64,$IMG2",
  "input_image_3": "data:image/png;base64,$IMG3",
  "width": 1792,
  "height": 1024,
  "output_format": "png"
}
EOF

python3 save_images.py flux-multi-edit.json flux-multi-edit
```

## Редактирование на Python

Скрипт принимает от одного до восьми референсов: локальные файлы превращает в data URL, публичные URL передаёт без изменений и сохраняет результат сразу после ответа.

```python theme={null}
import base64
import mimetypes
import os
from pathlib import Path

import requests

API_URL = "https://api.laozhang.ai/v1/images/generations"
HEADERS = {"Authorization": f"Bearer {os.environ['LAOZHANG_API_KEY']}"}


def to_image_input(source):
    """URL возвращаем как есть, локальный файл превращаем в data URL."""
    if source.startswith(("https://", "http://", "data:")):
        return source
    path = Path(source)
    mime_type = mimetypes.guess_type(path.name)[0] or "image/png"
    encoded = base64.b64encode(path.read_bytes()).decode("ascii")
    return f"data:{mime_type};base64,{encoded}"


def flux_edit(prompt, sources, width=1024, height=1024, model="flux-2-pro"):
    if not 1 <= len(sources) <= 8:
        raise ValueError("FLUX.2 принимает от 1 до 8 референсных изображений")
    payload = {
        "model": model,
        "prompt": prompt,
        "width": width,
        "height": height,
        "output_format": "png",
    }
    for number, source in enumerate(sources, start=1):
        field = "input_image" if number == 1 else f"input_image_{number}"
        payload[field] = to_image_input(source)
    response = requests.post(API_URL, headers=HEADERS, json=payload, timeout=240)
    response.raise_for_status()
    return response.json()


def save_first_image(result, stem):
    # FLUX возвращает ссылку, которая действует 10 минут, поэтому скачиваем сразу.
    download = requests.get(result["data"][0]["url"], timeout=120)
    download.raise_for_status()
    image = download.content
    extension = "png" if image.startswith(b"\x89PNG") else "jpg"
    path = Path(f"{stem}.{extension}")
    path.write_bytes(image)
    return path


result = flux_edit(
    "Изображение 1 — красный робот, изображение 2 — фон с оранжереей, изображение 3 — "
    "жёлтый скейтборд. Создай одну цельную новую сцену, а не коллаж.",
    ["robot.png", "greenhouse.png", "skateboard.png"],
    width=1792,
    height=1024,
)
print("Сохранено:", save_first_image(result, "flux-python-edit"))
```

## Параметры

| Параметр | Тип | Обязательный | Описание |
| - | - | - | - |
| `model` | string | Да | `flux-2-pro`, `flux-2-flex` или `flux-2-max` |
| `prompt` | string | Да | Инструкция для правки; при нескольких референсах называйте их «изображение 1», «изображение 2» и т. д. |
| `input_image` | string | Да, для правки | Первый референс: публичный URL или data URL |
| `input_image_2` … `input_image_8` | string | Нет | Дополнительные референсы по порядку |
| `size` | string | Нет | Размер, например `1792x1024` |
| `width`, `height` | integer | Нет | Размер в пикселях: кратно 16, не меньше 64, всего до \~4 Мп; вместо `size` |
| `output_format` | string | Нет | `jpeg` (по умолчанию) или `png` |
| `seed` | integer | Нет | Фиксированный seed для воспроизводимого результата |
| `n` | integer | Нет | Число изображений; поддерживается только `1` |

Размер задаётся либо через `size`, либо через `width` и `height`, но не обоими способами сразу. Распространённые значения `size` перечислены в разделе о размере изображения на странице [Генерация FLUX.2](https://docs.laozhang.ai/ru/api-capabilities/flux-image-generation.md).

## Обработка ответа

В ответе приходит одно изображение в `data[0].url`. FLUX не возвращает `b64_json`, поэтому не передавайте `response_format`. Ссылка действует 10 минут после генерации: скачивайте изображение сразу после ответа, особенно в пакетных задачах.

Изображение приходит в JPEG, если не указать `output_format` со значением `png`.

## Советы по промптам

* Называйте источники «изображение 1», «изображение 2», «изображение 3» и так далее — в порядке полей.
* Перечислите, что нужно сохранить из каждого референса: логотип, лицо, цвет товара.
* Укажите, что результат должен быть одним цельным изображением.
* Укажите, чего избегать: коллажа, разделённого кадра, рамок, подписей.

```text theme={null}
Изображение 1 — персонаж, изображение 2 — фон, изображение 3 — товар.
Создай один цельный рекламный постер.
Сохрани одежду персонажа, освещение фона и логотип товара.
Не делай коллаж и не дели кадр на части.
```

## Ошибки и оплата

* **HTTP 400**: проверьте имена полей, число референсов и размер изображения.
  * Имена полей: `input_image`, затем `input_image_2` и далее.
  * Число референсов: не больше 8.
  * Размер: кратно 16, не меньше 64 пикселей, до \~4 Мп, задаётся через `size` или через `width` и `height`.
* **Референс не загружается**: URL должен быть публичным. Иначе передайте файл как data URL.
* **Ссылка на результат больше не работает**: она истекла через 10 минут после генерации. Повторите запрос и скачайте результат сразу.
* **HTTP 401**: проверьте ключ и заголовок `Authorization: Bearer`.
* **HTTP 429, 5xx или таймаут**: повторите запрос с нарастающей паузой. После таймаута сначала проверьте [журнал вызовов](https://api.laozhang.ai/log), чтобы не заплатить дважды.

Каждый запрос оплачивается по цене за вызов для выбранной модели. В журнале вызовов видны модель и списание по каждому запросу.

## Прежние модели FLUX Kontext

`flux-kontext-pro` и `flux-kontext-max` остаются в каталоге для существующих интеграций. Вместо `size` они принимают поле `aspect_ratio`; подробности — в разделе о FLUX Kontext на странице [Генерация FLUX.2](https://docs.laozhang.ai/ru/api-capabilities/flux-image-generation.md). Новые правки стройте на FLUX.2.

## Частые вопросы

### Можно ли отредактировать только часть изображения?

Да, описав её словами. Поля для маски в запросе нет, поэтому назовите в промпте элемент, который нужно изменить, и укажите, что должно остаться прежним.

### Редактирование стоит дороже генерации?

Нет. FLUX.2 оплачивается за вызов, поэтому правка стоит столько же, сколько генерация, — независимо от того, один референс вы передали или восемь, и от размера результата. Фактическое списание смотрите в [журнале вызовов](https://docs.laozhang.ai/en/faq/call-logs.md).

### Для редактирования и генерации используется одна модель?

Да. `flux-2-pro`, `flux-2-flex` и `flux-2-max` умеют и то и другое. Запрос с `input_image` — это редактирование, без него — генерация нового изображения, как на странице [Генерация FLUX.2](https://docs.laozhang.ai/ru/api-capabilities/flux-image-generation.md).

### Можно ли редактировать через `images.edit()` в OpenAI SDK?

Только если изображение одно. `images.edit()` отправляет multipart/form-data на `/v1/images/edits`, а этот эндпоинт принимает одно изображение и не объединяет референсы.

Вместо него используйте `client.images.generate()` и передавайте `input_image` (и нумерованные поля для остальных референсов) в `extra_body` как публичные URL или data URL. Вспомогательная функция на Python на этой странице делает то же самое через `requests`.

## Связанные материалы и источники

* [Генерация FLUX.2](https://docs.laozhang.ai/ru/api-capabilities/flux-image-generation.md) — генерация по тексту, размеры изображений и прежние модели Kontext
* [Сравнение API изображений](https://docs.laozhang.ai/ru/api-capabilities/image-generation-guide.md) — FLUX.2 рядом с другими моделями изображений
* [Images API](https://docs.laozhang.ai/ru/api-reference/images.md) — общий формат запроса и ответа
* [Цены на API моделей ИИ](https://docs.laozhang.ai/ru/models.md) — актуальные цены и группы FLUX
* [Журнал вызовов](https://docs.laozhang.ai/en/faq/call-logs.md) — модель и списание по каждому запросу
* [Black Forest Labs: редактирование в FLUX.2](https://docs.bfl.ai/flux_2/flux2_image_editing) (на английском) — редактирование с несколькими референсами, лимиты референсов и срок жизни ссылок
* [Black Forest Labs: обзор FLUX.2](https://docs.bfl.ai/flux_2/flux2_overview) (на английском) — для чего создана каждая версия FLUX.2


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