Skip to main content
POST

Выбор модели

Обе модели обеспечивают одинаковые размеры и качество изображений. Для нескольких изображений за один запрос выбирайте официальную версию, для оценки стоимости за изображение — Ext. Актуальные цены указаны в тарифах моделей.
Этот эндпоинт работает асинхронно. При успешной отправке возвращается task_id. Получайте статус и изображения через запрос состояния задачи. Рекомендуется опрашивать каждые 3–5 секунд и установить общий тайм-аут ожидания не менее 3 минут.

Заголовки запроса

string
обязательно
Bearer-аутентификация в формате Bearer <token>, где <token> — ваш APIMart API Key.

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

string
обязательно
ID модели: gemini-nano-banana-2.1 или gemini-nano-banana-2.1-ext.
string
обязательно
Текстовое описание для генерации или редактирования изображения. Поддерживаются китайский и английский языки.
string
по умолчанию:"auto"
Соотношение сторон результата. Поддерживаются 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9 и 21:9. Также принимается формат 16x9.Если параметр не указан или задан как auto, выбор делает модель. При генерации по изображению результат следует соотношению сторон референса.Другие соотношения, включая 1:4, 4:1, 1:8 и 8:1, не поддерживаются. Неподдерживаемое значение приводит к ошибке задачи и возврату средств.
string
по умолчанию:"1K"
Уровень разрешения: 1K, 2K или 4K. Допускается нижний регистр. Значение также влияет на оплату.0.5K и 512 не поддерживаются: при отправке возвращается HTTP 400. Другие нераспознанные значения, например 3K, обрабатываются и оплачиваются как 1K. Используйте только поддерживаемые значения выше.
integer
по умолчанию:"1"
Количество изображений: 1–4 для официальной версии, только 1 для Ext.Значения больше 4 сразу возвращают HTTP 400. Запросы Ext со значением 2–4 завершаются ошибкой на этапе выполнения с полным возвратом средств. Для нескольких изображений отправляйте отдельные задачи Ext или используйте официальную версию.
string[]
Список референсных изображений. Без него выполняется генерация по тексту, с ним — генерация по изображению или редактирование. Каждый элемент поддерживает:
  • Общедоступный HTTP(S) URL изображения.
  • Base64 Data URL, например data:image/png;base64,....
Рекомендуются PNG, JPEG или WEBP. Для официальной версии лимит составляет 20MB на изображение. Для Ext — 20MB на изображение и 50MB суммарно.Платформа не задаёт фиксированный предел количества референсов, но это не означает неограниченную загрузку: превышение возможностей модели может привести к ошибке задачи и возврату средств. Чем больше референсов, тем обычно дольше обработка.
boolean
по умолчанию:"false"
Применяется только к gemini-nano-banana-2.1-ext. При включении, если Ext завершается ошибкой, выполняется попытка завершить задачу с помощью официальной версии.Если фактически используется официальная версия, оплата рассчитывается по её реальному расходу токенов, а не по цене Ext за изображение.
string
URL обратного вызова для уведомления о завершении задачи. См. вебхуки задач.

Справочные размеры результата

В таблице приведены измеренные и справочные значения для семейства моделей. Проверены не все комбинации. Окончательные размеры в пикселях определяются возвращённым изображением.

Редактирование референсного изображения

Замените пример URL на доступный URL изображения. Если size не указан, результат следует соотношению сторон референса.

Пакетная генерация (только официальная версия)

Ответ на отправку

integer
Код состояния ответа. 200 означает успех.
array
Результат отправки задачи. status равен submitted. task_id используется для запроса состояния и результатов; это не URL итогового изображения.

Запрос результатов задачи

Пример успешного ответа (URL изображения — заглушка):
Все ссылки на итоговые изображения находятся в массиве data.result.images[0].url. При генерации 4 изображений в массиве будет 4 ссылки. Возвращаются только итоговые изображения; n=1 соответствует 1 итоговому изображению. Ссылки действуют 24 часа после завершения задачи, согласно expires_at. Своевременно скачайте и сохраните изображения. Формат — PNG или JPEG; ориентируйтесь на фактическое содержимое файла. data.cost в результате запроса — итоговая сумма списания в USD.

Оплата

  • Официальная версия: оплата по фактическому расходу входных и выходных токенов. Промпт и референсы учитываются как входные данные. При отправке предварительно списывается сумма на основе разрешения и n, после завершения выполняется возврат разницы или дополнительное списание по фактическому расходу.
  • Версия Ext: цена выбранного разрешения × фактическое число изображений. Соотношение сторон не влияет на уровень разрешения. Если official_fallback включён и фактически использована официальная версия, применяется её оплата по токенам.
  • Цены указаны в тарифах моделей. Отклонённые при отправке запросы не создают задач и не оплачиваются. При ошибке задачи средства возвращаются полностью.

Частые ошибки

Nano banana 2.1 и Gemini 3.1 Flash Image — разные модели; их названия нельзя использовать как взаимозаменяемые псевдонимы. При переходе с последней замените разрешение 0.5K и четыре экстремальных соотношения: 1:4, 4:1, 1:8 и 8:1.