Руководство: генерация и редактирование изображений

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

Изображения генерируются быстрее и дешевле всего, поэтому на них удобнее всего осваивать API. Большинство моделей изображений укладываются в минуту, так что можно добавить ?wait=60 и получить картинку в том же ответе.

Изображение по тексту

curl -X POST "https://api.popnow.ai/api/v1/jobs/createTask?wait=60" \
  -H "Authorization: Bearer $POPNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "model": "black-forest-labs/flux-2-klein-9b/text-to-image",
    "input": {
      "prompt": "Product photo of a ceramic coffee mug on a linen tablecloth, soft window light, shallow depth of field",
      "aspect_ratio": "4:3"
    }
  }'

Результат лежит в data.output.assets[0].url. Если пришёл 202, модели понадобилось больше 60 секунд — прочитайте задачу через recordInfo.

Какую модель выбрать

Нужно	Попробуйте	Почему
Самые быстрые и дешёвые черновики	`alibaba/z-image-turbo/text-to-image`	Около десяти секунд и пара кредитов за изображение
Хорошее качество за небольшие деньги	`black-forest-labs/flux-2-klein-9b/text-to-image`	Быстро, чётко, хорошо слушается промпта
Читаемый текст, постеры, схемы	`google/nano-banana-2.1/text-to-image`, `openai/gpt-image-2/text-to-image`	Сильны в надписях и вёрстке; до 4K
Несколько вариантов за один вызов	Модели с `num_outputs`	Одна задача — несколько изображений

Цены зависят от модели и опций. На странице Модели указана стартовая цена каждой, а на её справочной странице — все уровни.

Редактирование по референсам

Модели редактирования заканчиваются на /edit и принимают исходные изображения в image_urls — в том порядке, в каком промпт на них ссылается:

{
  "model": "google/nano-banana-2.1/edit",
  "input": {
    "prompt": "Turn the scene into a bright summer afternoon and keep the composition",
    "image_urls": ["https://media.popnow.ai/movie/lighthouse.webp"]
  }
}

Пишите не только что изменить, но и что оставить как есть: модели редактирования понимают «сохрани лицо и позу» буквально.
Если референсов несколько, называйте их по порядку: «надень на человека с первого изображения куртку со второго».
Локальные файлы сначала загрузите; те, что используются постоянно, держите в библиотеке ассетов.

Инструменты в один шаг

Инструменты самого PopNow принимают одно изображение и не требуют промпта:

ID модели	Что делает
`popnow/background-remover-v1/edit`	Вырезает объект на прозрачный фон
`popnow/image-upscaler-v1/upscale`	Увеличивает изображение и повышает резкость
`popnow/object-eraser-v1/edit`	Убирает указанный объект
`popnow/image-expander-v1/edit`	Достраивает изображение за его краями

{ "model": "popnow/background-remover-v1/edit",
  "input": { "image_url": "https://media.popnow.ai/movie/lighthouse.webp" } }

Важные настройки

aspect_ratio и resolution чаще всего влияют на цену. Если сомневаетесь, спросите jobs/quote.
seed: если его не передать, выбирается случайное значение и возвращается в input задачи. Отправьте это число снова, чтобы получить близкий вариант понравившегося результата; фиксированный seed делает запуски сравнимыми, но не обещает идентичную картинку.
output_format: png сохраняет прозрачность и детали, jpeg весит меньше.
Неизвестные настройки отклоняются, поэтому сверяйтесь со схемой конкретной модели, а не копируйте настройки другой.

Промпты, которые работают

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

Возможные ошибки

content_rejected — модель отклонила промпт или референс. Переформулируйте или попробуйте другую модель.
invalid_asset — референс не удалось прочитать. Проверьте, что URL отдаёт само изображение, или загрузите файл.
unsupported_combination — модель сейчас не поддерживает такое сочетание настроек; измените ту, что названа в сообщении.

Во всех этих случаях резерв возвращается, так что неудачное изображение ничего не стоит.