FLUX Kontext Pro по API: правка готовой картинки фразой без маски

Если отправить готовый портрет в обычную модель «картинка в картинку» с просьбой сменить куртку, она нарисует кадр заново: скулы, причёска и поза съедут. FLUX.1 Kontext Pro от Black Forest Labs (BFL) получает исходник и короткую инструкцию и меняет только то, что в инструкции названо. Маску рисовать не нужно, но в промпте надо прямо сказать, что сохранить. Одна правка стоит $0,04 по прайсу BFL, результат получается около одного мегапикселя, а сам вендор относит модель к прошлому поколению.

Что модель меняет без маски и что вы получите на выходе

Kontext Pro и рисует по тексту, и правит. Режим определяется запросом: если в нём есть исходная картинка, модель её редактирует. Координаты объекта не нужны, модель находит его сама. В документации BFL пример правки занимает одну строку: Change the car color to red.

Что BFL заявляет для правки:

• смену цвета, фона, одежды, удаление предмета;
• замену надписи на вывеске, постере или этикетке;
• правку внутри цветной рамки: вы рисуете на исходнике яркий прямоугольник, модель меняет то, что внутри, а рамку из результата убирает. BFL советует этот приём, когда надпись нужно сдвинуть или поменять в размере;
• серию правок с одним и тем же персонажем.

Размеры по той же документации: на вход принимается картинка до 20 МБ или 20 мегапикселей, на выходе всегда около 1 Мп. Если пропорции не заданы, модель повторяет пропорции исходника и округляет стороны до кратных 32 пикселям: в примере BFL из кадра 2048×1365 получилось 1248×832. Пропорции допускаются от 9:21 до 21:9. Большого файла под печать из Kontext не получить, и заказчику это лучше сказать заранее.

Промпт правки: объект, действие и что оставить

Инструкция для Kontext ограничена 512 токенами. Токен — кусочек текста, обычно часть слова. Платите вы за картинку, а не за токены, но длинное описание сцены модели не нужно: всё, что не названо, она берёт из исходника.

Правила ниже взяты из гайда BFL по промптам Kontext. Живая страница гайда уже удалена, ссылка ведёт на копию в веб-архиве от 10.04.2026. Те же пункты коротко повторены в текущей шпаргалке BFL.

1. Называйте объект, а не местоимение: «The woman with short black hair» вместо «her». Местоимение модель может отнести к случайному человеку на фоне.
2. Пишите, что сохранить. Хвост while maintaining the same facial features, hairstyle and expression просит модель не трогать лицо, причёску и выражение.
3. Не пишите transform без уточнений. В примере из гайда запрос «Transform the person into a Viking» заменил лицо, причёску и выражение целиком, а «Change the clothes to be a viking warrior» поменял только одежду. BFL объясняет это так: голое «transform» модель понимает как просьбу переделать всё.
4. При смене фона фиксируйте кадр. Просьба «Put him on a beach» двигает камеру и масштаб. Гайд предлагает дописать: while keeping the person in the exact same position, scale, and pose.

Надпись меняют через одинарные кавычки: Replace 'SALE' with 'NEW COLLECTION' while maintaining the same font style and color. Такой синтаксис BFL приводит для вывесок и этикеток.

Параметр prompt_upsampling просит модель саму расписать ваш промпт перед работой. По умолчанию он выключен. В API-референсе BFL сказано, что он меняет промпт «for more creative generation», а точечной правке творческие добавки только вредят.

Цепочка правок: где начинается брак

BFL в анонсе модели от 29.05.2025 сама пишет, что длинная серия правок, где каждый результат идёт на вход следующей, копит артефакты. На иллюстрации к этому ограничению картинка заметно испорчена после шести правок подряд. При этом гайд советует разбивать сложное изменение на несколько шагов. Эти советы совместимы, если держать цепочку короткой.

Как мы бы строили конвейер:

• одна смысловая правка за шаг: фон отдельно, цвет упаковки отдельно;
• после трёх-четырёх шагов не идти дальше от промежуточного результата, а собрать нужные правки в одну-две инструкции и применить их к оригиналу;
• хранить оригинал и каждый промежуточный файл, чтобы откатиться на шаг назад, а не начинать с испорченного кадра;
• фиксировать seed, чтобы сравнивать варианты промпта между собой, а не со случайностью.

Порог «три-четыре шага» — наша осторожная оценка, а не цифра вендора. Свой порог проверьте на собственных картинках.

Вызов через API: синхронно и с постоянной ссылкой

У BFL напрямую правка асинхронная: вы отправляете запрос на /v1/flux-kontext-pro, получаете polling_url и опрашиваете его, пока статус не станет Ready. Подписанная ссылка на готовый файл живёт 10 минут, так что забрать результат нужно сразу.

Через altrouter тот же вызов идёт на OpenAI-совместимый POST https://api.altrouter.ai/v1/images/generations и возвращает результат в том же ответе. Исходник кладётся в поле image массивом ссылок или строк base64, и запрос уходит в режим правки (документация по изображениям). Ссылка в ответе ведёт на наше хранилище и не протухает (хранение данных). Учтите, что она публичная: файл увидит любой, кто знает URL.

curl https://api.altrouter.ai/v1/images/generations \
  -H "Authorization: Bearer $ALTROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-kontext-pro",
    "prompt": "Change the background to a sunny beach while keeping the man with a grey beard in the exact same position, scale, and pose, while maintaining the same facial features, hairstyle and expression",
    "image": ["https://example.com/portrait.jpg"],
    "aspect_ratio": "3:4",
    "seed": 42,
    "output_format": "png"
  }'

В Python работает обычный пакет openai. Поля модели он не знает, поэтому они уходят через extra_body — словарь, который SDK добавляет в тело запроса как есть.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ALTROUTER_API_KEY"],
    base_url="https://api.altrouter.ai/v1",
)

result = client.images.generate(
    model="flux-kontext-pro",
    prompt="Replace 'SALE' with 'NEW COLLECTION' while maintaining the same font style and color",
    extra_body={
        "image": ["https://example.com/signboard.jpg"],
        "aspect_ratio": "1:1",
        "seed": 12345,
        "output_format": "jpeg",
        "prompt_upsampling": False,
    },
)

print(result.data[0].url)
print("списано, $:", getattr(result.usage, "cost", None))

Что значат поля:

• aspect_ratio — форма кадра: 1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3, 21:9 или 9:21. В нашем каталоге у параметра указано значение по умолчанию 1:1, поэтому для правки передавайте пропорции исходника явно, иначе кадр может получиться квадратным. Число пикселей и цена от формы не зависят.
• seed — номер случайности. При том же номере, промпте и исходнике результат получается близким к прошлому прогону.
• output_format — png, jpeg или webp, по умолчанию png.
• usage.cost — сколько списано с баланса за этот запрос (API-референс).

Параметр BFL safety_tolerance, строгость модерации от 0 до 6, в нашем каталоге не выведен.

Сколько ждать: 16.09.2026 мы прогнали одну генерацию Kontext Pro через наш API, и от отправки запроса до готовой ссылки прошло около 14 секунд. Это один прогон генерации, а не правки, нагрузку и время суток мы не выравнивали. BFL в обзоре моделей пишет про 5–6 секунд, а в техническом отчёте — про 3–5 секунд на картинку 1024×1024. Какая часть разницы приходится на шлюз и перекладку файла в хранилище, мы не раскладывали.

Сколько стоит правка

По прайсу BFL на 29.10.2026 Kontext Pro стоит $0,04 за картинку, и правка стоит столько же, сколько генерация. В нашем каталоге на 27.10.2026 цена $0,0414: на 3,5% выше прайса BFL, скидки на эту модель нет. Размер исходника и пропорции на цену не влияют.

Расходы считайте на принятую картинку, а не на вызов: переделку вы оплачиваете как новую правку. Пример: каталог из 200 фото товара, на каждом меняем фон. Допустим, с первого раза вас устраивает 70% результатов. Это не наш замер, а параметр для расчёта, подставьте свою долю.

• цена принятой картинки: $0,0414 / 0,7 ≈ $0,059;
• 200 принятых карточек: 200 × $0,0414 / 0,7 ≈ $11,83;
• у BFL напрямую: 200 × $0,04 / 0,7 ≈ $11,43.

Если с первого раза проходит только половина правок, сумма для 200 карточек вырастет до $16,56. Разница между долей 70% и 50% стоит больше, чем разница между нами и BFL, поэтому сначала отладьте промпт на 10–20 картинках.

Kontext Pro, Kontext Max или FLUX.2

BFL называет Kontext моделью прошлого поколения. В API-референсе для правки прямо рекомендованы FLUX.2 [pro] и FLUX.2 [flex]. FLUX.2 принимает до 8 референсов через API и отдаёт до 4 Мп.

У BFL FLUX.2 считается по мегапикселям: результата и входных картинок. Для [pro] это $0,03 за первый мегапиксель результата, $0,015 за каждый следующий и $0,015 за мегапиксель исходника, отсюда ≈ $0,045 за правку кадра около 1 Мп.

Что из этого следует:

• Новый конвейер у BFL напрямую лучше строить на FLUX.2 [pro]: по цене правка почти та же, а референсов и пикселей больше. Так советует и сам вендор.
• Через altrouter из моделей BFL правка дешевле всего у Kontext Pro: FLUX.2 Pro в нашем каталоге на паузе, а правка во FLUX.2 Max стоит в 4,7 раза дороже. Чем Max отличается на практике, разобрано в статье про FLUX.2 Max.
• Kontext Max вдвое дороже Pro. Когда доплата окупается, мы посчитали в разборе Kontext Max.

Если на BFL вы не завязаны, правку по референсу умеют и другие модели. Сравнение по задачам — в обзоре моделей для картинок.

Чего Kontext Pro не сделает

• Не отдаст большой файл: выход около 1 Мп, и для печати картинку придётся увеличивать отдельно. Если нужен 4K, смотрите модели, которые его генерируют, например Wan 2.7 Pro, но правку она делает только до 2K.
• Не гарантирует, что инструкция выполнена. BFL признаёт, что модель иногда игнорирует часть промпта и возвращает почти тот же кадр, а такой вызов оплачивается как обычный.
• Путается в редких предметах и местах: знания о мире у модели ограничены, и узнаваемый объект она может нарисовать неверно.
• Не выдерживает длинных цепочек правок: артефакты копятся, об этом выше.

Сохранение лица и точность замены текста мы слепым тестом не мерили. Всё, что сказано о качестве, взято из документации и бенчмарка BFL. В её собственном тесте KontextBench Kontext Pro лидирует по правке текста и сохранению персонажа, но это оценка вендора, а не независимая.

FAQ