Три значения, необходимые для каждой интеграции
Почти все руководства по интеграции nanobanana api сводятся к заполнению одних и тех же трёх полей в разных местах. Сервис использует протокол OpenAI chat-completions, поэтому инструмент, позволяющий переопределить эндпоинт OpenAI, сможет работать с ним.
| Поле | Значение |
|---|---|
| Базовый URL | https://api.nanobananaapis.com/v1 |
| API-ключ | Ваш ключ, отправляемый как Authorization: Bearer <key> |
| ID модели | uncensored |
Одно замечание перед началом. Это текстовая языковая модель, поэтому она не подойдет для задач генерации изображений, речи или эмбеддингов. Поддерживаемые методы — POST /v1/chat/completions и GET /v1/models. Если инструмент запрашивает модель эмбеддингов для поиска, укажите для этой части другого провайдера.
Получите ключ на странице API-ключ. Новые аккаунты могут получить $0.50 пробного баланса в один клик, без карты, сроком на 7 дней.
Протестируйте эндпоинт перед настройкой любого инструмента
Когда интеграция работает со сбоями, люди винят инструмент. Чаще всего неверны ключ или URL. Тест curl на 30 секунд снимает эти сомнения. Сначала перечислите модели:
curl https://api.nanobananaapis.com/v1/models -H "Authorization: Bearer YOUR_API_KEY"
Затем отправьте короткий чат-запрос:
curl https://api.nanobananaapis.com/v1/chat/completions -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d '{"model":"uncensored","messages":[{"role":"user","content":"Reply with the word ready."}],"max_tokens":10}'
Если оба работают, эндпоинт и ключ в порядке, и любая последующая ошибка связана с настройкой инструмента. Если первый вызов возвращает 401, ключ неверен или в заголовке отсутствует слово Bearer. Ошибка 404 обычно означает, что в URL отсутствует /v1 или есть лишний путь.
SillyTavern
SillyTavern — это интерфейс для ролевых игр и чатов с персонажами, позволяющий добавить эндпоинт, совместимый с OpenAI. Названия в меню меняются от версии к версии, поэтому воспринимайте шаги как карту, а не как точные формулировки.
- Откройте панель подключения API и выберите Chat Completion в качестве типа API.
- Выберите источник Custom (OpenAI-compatible).
- Вставьте
https://api.nanobananaapis.com/v1в качестве URL эндпоинта. - Вставьте свой ключ в поле ключа.
- Введите
uncensoredв качестве имени модели или нажмите кнопку подключения и выберите ее из списка, возвращаемогоGET /v1/models. - Нажмите «Подключить» и отправьте тестовое сообщение.
Два уточнения. SillyTavern отправляет длинные истории с карточками персонажей, поэтому следите за контекстным окном на 100 000 токенов, которое делится между промптом и ответом. А если вы используете групповые чаты, которые отправляют несколько запросов одновременно, помните о лимите 8 параллельных запросов на полный ключ (2 на пробном ключе). Сценарии для ролевой игры и компаньонов рассчитаны на взрослых; модель не будет генерировать сексуальный контент с участием несовершеннолетних ни при каком промпте.
LangChain
В Python пакет langchain-openai предоставляет ChatOpenAI, который принимает пользовательский базовый URL. Установите его с помощью pip install langchain-openai.
import os
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(
base_url="https://api.nanobananaapis.com/v1",
api_key=os.environ["NANOBANANA_KEY"],
model="uncensored",
temperature=0.7,
)
print(llm.invoke("Give me three names for a fictional smuggler ship.").content)
Цепочки, шаблоны промптов и парсеры вывода работают так же, так как им важен только интерфейс чата. Вызов инструментов идет стандартным путем, поэтому llm.bind_tools([...]) отправляет tools в запросе. Протестируйте один вызов инструмента перед созданием агента и ограничьте параллелизм агента значением 8. Граф, разветвляющийся на двадцать ветвей, столкнется с ошибкой concurrency.
Пакет JavaScript @langchain/openai использует ту же идею через параметр configuration: { baseURL } в ChatOpenAI.
Cursor и другие редакторы
Cursor, как и несколько других редакторов кода, имеет раздел настроек моделей, где вы можете указать свой API-ключ OpenAI и переопределить базовый URL. Приблизительно: откройте настройки моделей, включите опцию пользовательского ключа OpenAI, установите базовый URL переопределения в https://api.nanobananaapis.com/v1, вставьте свой ключ и добавьте uncensored в качестве пользовательского имени модели.
Будьте реалистичны в отношении того, что это дает. Редакторы строят некоторые функции, такие как встроенное завершение, вокруг своих собственных бэкендов и конкретных имен моделей, поэтому пользовательский эндпоинт может применяться только к чату или подмножеству команд. Точные параметры меняются между версиями, поэтому проверьте текущую документацию редактора. Если функция требует чего-то, чего не предлагает этот API, например эмбеддингов или ввода изображений, она не будет работать через этот эндпоинт.
Та же схема применяется к другим клиентам, совместимым с OpenAI, таким как Open WebUI, Continue и аналогичным интерфейсам чата: найдите поле для пользовательского эндпоинта OpenAI, введите три значения и протестируйте.
Обычные SDK и переменные окружения
Если вы пишете собственный код, официальные SDK читают стандартные переменные окружения, что позволяет переключать эндпоинты без изменения исходных файлов. В SDK Python и Node достаточно установить OPENAI_BASE_URL и OPENAI_API_KEY.
export OPENAI_BASE_URL="https://api.nanobananaapis.com/v1"
export OPENAI_API_KEY="YOUR_API_KEY"
python app.py # app.py calls client.chat.completions.create(model="uncensored", ...)
Явный клиент в Node выглядит так:
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.nanobananaapis.com/v1",
apiKey: process.env.NANOBANANA_KEY,
});
const stream = await client.chat.completions.create({
model: "uncensored",
messages: [{ role: "user", content: "Draft a short product description for a paper lantern." }],
stream: true,
});
for await (const part of stream) {
process.stdout.write(part.choices[0]?.delta?.content ?? "");
}
Потоковая передача идёт через SSE, а сведения об использовании приходят в конце. Полная информация о параметрах доступна на странице документации, а статья о генерации промптов показывает, как подключить текстовый этап к конвейеру генерации изображений.
Устранение распространенных сбоев
| Симптом | Вероятная причина | Исправление |
|---|---|---|
| 401 Unauthorized | Неверный ключ или отсутствие Bearer в заголовке | Скопируйте ключ заново и протестируйте с помощью curl |
| 404 Not Found | Базовый URL без /v1 или удвоенный путь | Используйте ровно https://api.nanobananaapis.com/v1 |
| Модель не найдена | Инструмент по умолчанию использует имя модели поставщика | Укажите модель uncensored |
429 с rate_limited | Более 300 запросов в минуту (60 запросов на пробном) | Уменьшите частоту и повторите попытку |
429 с concurrency | Более 8 запросов одновременно (2 на пробном ключе) | Снизьте параллелизм |
| 429 с Retry-After: 5 | Временная перегрузка | Подождите пять секунд и повторите запрос |
| Запрос слишком большой | Тело запроса более 8 МБ | Уменьшите объем вложений или истории |
Имейте в виду, что потоковый запрос удерживает слот параллелизма до завершения потока, поэтому редактор, отменяющий потоки, может казаться превышающим лимит, даже когда он не занят. Логируйте заголовок X-Request-Id из неудачных вызовов; это первое, о чем попросит поддержка.
Что касается стоимости, типичное сообщение чата с 2 000 входными и 500 выходными токенами обходится в $0,00055 при тарифах $0,15 и $0,50 за 1 млн токенов, а неудачные запросы не оплачиваются. На странице цен описаны варианты пополнения от $20 до $500 и бонусные уровни.
Ключи, безопасность и доступ к данным
Каждая интеграция хранит ваш ключ в определённом месте, и некоторые делают это лучше других. В десктопном интерфейсе ключ сохраняется в локальном файле настроек. В браузерном инструменте он может быть сохранён в браузере. В редакторе он хранится в конфигурации приложения. Узнайте, где именно хранится ключ, прежде чем демонстрировать экран, коммитить dotfile или передавать ноутбук другому человеку.
Несколько правил делают управление ключами удобным. Используйте один ключ для каждого инструмента, где это возможно, чтобы заменить один ключ, не нарушая работу остальных. Никогда не вставляйте ключ в публичный трекер задач при поиске помощи; вместо этого поделитесь идентификатором запроса. Если ключ утечёт, замените его на странице ключей и обновите ваши инструменты. Промпты, отправленные через API, не используются для обучения моделей, а остальная работа с данными описана на странице конфиденциальности.
Если вы размещаете интерфейс для других пользователей, не передавайте ваш ключ в браузер. Разместите небольшой сервер между пользователями и API, добавьте свои ограничения на этом сервере и храните ключ на сервере. Ваши пользователи будут совместно использовать ваши 8 параллельных запросов, поэтому спланируйте, сколько человек может общаться одновременно.
Какой инструмент для какой задачи
Поскольку интеграция везде одинакова, выбор инструмента зависит от того, что вы создаёте.
- SillyTavern или аналогичный интерфейс чата подходит для общения с персонажами, художественных текстов и ролевых игр для взрослых, где вам нужен отполированный интерфейс и карточки персонажей без написания кода.
- LangChain подходит для конвейеров в коде: загрузчиков, шаблонов промптов, парсеров и многошаговых цепочек. Он добавляет структуру ценой ещё одной зависимости.
- Прямой вызов через SDK подходит для небольших скриптов и сервисов. Если ваша задача — один промпт на вход и один ответ на выход, пакета OpenAI достаточно, и его проще поддерживать, чем фреймворк.
- Редактор вроде Cursor подходит для чата о коде. Проверьте, какие его функции принимают пользовательский эндпоинт, прежде чем полагаться на него.
Начните с простого теста через curl, затем подключите SDK и добавьте фреймворк только тогда, когда почувствуете необходимость. Позже перейти на другой вариант просто, поскольку три значения никогда не меняются. Для первого запроса и полного списка параметров прочитайте документацию.
