> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Nano banana 2.1 Генерация изображений
> Генерация по тексту и редактирование референсных изображений в 1K / 2K / 4K с 10 соотношениями сторон. Доступны официальная версия и Ext.
## Выбор модели
| ID модели | Оплата | Изображений за запрос | Размер референсов |
| - | - | - | - |
| `gemini-nano-banana-2.1` | По фактическому расходу токенов | 1–4 | До 20MB на изображение |
| `gemini-nano-banana-2.1-ext` | За изображение, в зависимости от разрешения | Только 1 | До 20MB на изображение, суммарно до 50MB |
Обе модели обеспечивают одинаковые размеры и качество изображений. Для нескольких изображений за один запрос выбирайте официальную версию, для оценки стоимости за изображение — Ext. Актуальные цены указаны в [тарифах моделей](https://apimart.ai/pricing).
Этот эндпоинт работает асинхронно. При успешной отправке возвращается `task_id`. Получайте статус и изображения через [запрос состояния задачи](/ru/api-reference/tasks/status). Рекомендуется опрашивать каждые 3–5 секунд и установить общий тайм-аут ожидания не менее 3 минут.
```bash cURL theme={null}
curl --request POST \
--url https://api.apimart.ai/v1/images/generations \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{
"model": "gemini-nano-banana-2.1",
"prompt": "Рыжий кот на деревянном столе рядом с чашкой кофе, мягкий утренний свет, реалистичная фотография",
"size": "16:9",
"resolution": "2K",
"n": 1
}'
```
```python Python theme={null}
import requests
response = requests.post(
"https://api.apimart.ai/v1/images/generations",
headers={"Authorization": "Bearer "},
json={
"model": "gemini-nano-banana-2.1",
"prompt": "Рыжий кот на деревянном столе рядом с чашкой кофе, мягкий утренний свет, реалистичная фотография",
"size": "16:9",
"resolution": "2K",
"n": 1
}
)
print(response.json())
```
```javascript JavaScript theme={null}
const response = await fetch("https://api.apimart.ai/v1/images/generations", {
method: "POST",
headers: {
Authorization: "Bearer ",
"Content-Type": "application/json"
},
body: JSON.stringify({
model: "gemini-nano-banana-2.1",
prompt: "Рыжий кот на деревянном столе рядом с чашкой кофе, мягкий утренний свет, реалистичная фотография",
size: "16:9",
resolution: "2K",
n: 1
})
});
console.log(await response.json());
```
```json 200 theme={null}
{
"code": 200,
"data": [
{
"status": "submitted",
"task_id": "task_01K..."
}
]
}
```
## Заголовки запроса
Bearer-аутентификация в формате `Bearer `, где `` — ваш APIMart API Key.
## Параметры запроса
ID модели: `gemini-nano-banana-2.1` или `gemini-nano-banana-2.1-ext`.
Текстовое описание для генерации или редактирования изображения. Поддерживаются китайский и английский языки.
Соотношение сторон результата. Поддерживаются `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`, не поддерживаются. Неподдерживаемое значение приводит к ошибке задачи и возврату средств.
Уровень разрешения: `1K`, `2K` или `4K`. Допускается нижний регистр. Значение также влияет на оплату.
`0.5K` и `512` не поддерживаются: при отправке возвращается HTTP 400. Другие нераспознанные значения, например `3K`, обрабатываются и оплачиваются как `1K`. Используйте только поддерживаемые значения выше.
Количество изображений: 1–4 для официальной версии, только 1 для Ext.
Значения больше 4 сразу возвращают HTTP 400. Запросы Ext со значением 2–4 завершаются ошибкой на этапе выполнения с полным возвратом средств. Для нескольких изображений отправляйте отдельные задачи Ext или используйте официальную версию.
Список референсных изображений. Без него выполняется генерация по тексту, с ним — генерация по изображению или редактирование. Каждый элемент поддерживает:
* Общедоступный HTTP(S) URL изображения.
* Base64 Data URL, например `data:image/png;base64,...`.
Рекомендуются PNG, JPEG или WEBP. Для официальной версии лимит составляет 20MB на изображение. Для Ext — 20MB на изображение и 50MB суммарно.
Платформа не задаёт фиксированный предел количества референсов, но это не означает неограниченную загрузку: превышение возможностей модели может привести к ошибке задачи и возврату средств. Чем больше референсов, тем обычно дольше обработка.
Применяется только к `gemini-nano-banana-2.1-ext`. При включении, если Ext завершается ошибкой, выполняется попытка завершить задачу с помощью официальной версии.
**Если фактически используется официальная версия, оплата рассчитывается по её реальному расходу токенов, а не по цене Ext за изображение.**
URL обратного вызова для уведомления о завершении задачи. См. [вебхуки задач](/ru/api-reference/tasks/webhook).
## Справочные размеры результата
| Соотношение сторон | 1K | 2K | 4K |
| - | - | - | - |
| 1:1 | 1024×1024 | 2048×2048 | 4096×4096 |
| 2:3 | 848×1264 | 1696×2528 | 3392×5056 |
| 3:2 | 1264×848 | 2528×1696 | 5056×3392 |
| 3:4 | 896×1200 | 1792×2400 | 3584×4800 |
| 4:3 | 1200×896 | 2400×1792 | 4800×3584 |
| 4:5 | 928×1152 | 1856×2304 | 3712×4608 |
| 5:4 | 1152×928 | 2304×1856 | 4608×3712 |
| 9:16 | 768×1376 | 1536×2752 | 3072×5504 |
| 16:9 | 1376×768 | 2752×1536 | 5504×3072 |
| 21:9 | 1584×672 | 3168×1344 | 6336×2688 |
В таблице приведены измеренные и справочные значения для семейства моделей. Проверены не все комбинации. Окончательные размеры в пикселях определяются возвращённым изображением.
## Редактирование референсного изображения
```json theme={null}
{
"model": "gemini-nano-banana-2.1-ext",
"prompt": "Надень на кота на изображении красную вязаную шапку, остальное оставь без изменений",
"image_urls": ["https://example.com/cat.jpg"],
"resolution": "1K"
}
```
Замените пример URL на доступный URL изображения. Если `size` не указан, результат следует соотношению сторон референса.
## Пакетная генерация (только официальная версия)
```json theme={null}
{
"model": "gemini-nano-banana-2.1",
"prompt": "Ночной город в стиле киберпанк, неоновые огни, улицы после дождя",
"size": "16:9",
"resolution": "2K",
"n": 4
}
```
## Ответ на отправку
Код состояния ответа. `200` означает успех.
Результат отправки задачи. `status` равен `submitted`. `task_id` используется для запроса состояния и результатов; это не URL итогового изображения.
## Запрос результатов задачи
```bash theme={null}
curl --request GET \
--url https://api.apimart.ai/v1/tasks/task_01K... \
--header 'Authorization: Bearer '
```
Пример успешного ответа (URL изображения — заглушка):
```json theme={null}
{
"code": 200,
"data": {
"id": "task_01K...",
"status": "completed",
"progress": 100,
"result": {
"images": [
{
"url": ["https://example.com/generated-image.png"],
"expires_at": 1791417625
}
]
}
}
}
```
| Статус задачи | Значение |
| - | - |
| `pending` | В очереди |
| `processing` | Генерация выполняется |
| `completed` | Успех; массив URL изображений находится в `data.result.images[0].url` |
| `failed` | Ошибка; причина в `data.error.message`. Полный возврат средств; `data.cost` равен 0 |
Все ссылки на итоговые изображения находятся в массиве `data.result.images[0].url`. При генерации 4 изображений в массиве будет 4 ссылки. Возвращаются только итоговые изображения; `n=1` соответствует 1 итоговому изображению.
Ссылки действуют 24 часа после завершения задачи, согласно `expires_at`. Своевременно скачайте и сохраните изображения. Формат — PNG или JPEG; ориентируйтесь на фактическое содержимое файла. `data.cost` в результате запроса — итоговая сумма списания в USD.
## Оплата
* **Официальная версия**: оплата по фактическому расходу входных и выходных токенов. Промпт и референсы учитываются как входные данные. При отправке предварительно списывается сумма на основе разрешения и `n`, после завершения выполняется возврат разницы или дополнительное списание по фактическому расходу.
* **Версия Ext**: цена выбранного разрешения × фактическое число изображений. Соотношение сторон не влияет на уровень разрешения. Если `official_fallback` включён и фактически использована официальная версия, применяется её оплата по токенам.
* Цены указаны в [тарифах моделей](https://apimart.ai/pricing). Отклонённые при отправке запросы не создают задач и не оплачиваются. При ошибке задачи средства возвращаются полностью.
## Частые ошибки
| Ситуация | Действие |
| - | - |
| HTTP 400 | Проверьте `0.5K` / `512`, значение `n` больше 4 или превышение лимита размера одного референса |
| HTTP 401 | Проверьте API Key |
| HTTP 402 | Убедитесь, что баланса хватает на предварительное списание |
| HTTP 429 | Достигнут лимит запросов; повторите с увеличением интервала |
| Ошибка задачи: неподдерживаемое соотношение сторон | Используйте одно из 10 поддерживаемых значений `size` или `auto` |
| Ошибка задачи: несколько изображений в Ext | Установите `n` равным 1 или используйте официальную версию |
| Ошибка задачи: блокировка проверкой безопасности | Измените промпт или референсы и повторите |
| Ошибка задачи: не удалось скачать референс | Убедитесь, что URL изображения общедоступен |
Nano banana 2.1 и Gemini 3.1 Flash Image — разные модели; их названия нельзя использовать как взаимозаменяемые псевдонимы. При переходе с последней замените разрешение `0.5K` и четыре экстремальных соотношения: `1:4`, `4:1`, `1:8` и `8:1`.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.