每个集成所需的三个值
几乎所有关于 nanobanana api 集成 的指南都归结为在不同位置填写相同的三个字段。该服务使用 OpenAI 聊天补全协议,因此允许你覆盖 OpenAI 接口的工具都可以与其通信。
| 字段 | 说明 |
|---|---|
| Base 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 测试可以消除这种疑虑。首先列出模型:
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 连接面板,并将 API 类型选择为 Chat Completion。
- 选择 自定义(兼容 OpenAI) 源。
- 粘贴
https://api.nanobananaapis.com/v1作为接口 URL。 - 在密钥字段中粘贴你的密钥。
- 输入
uncensored作为模型名称,或按连接按钮并从GET /v1/models返回的列表中选择。 - 按连接并发送测试消息。
两个调整说明。SillyTavern 会发送带有角色卡的长历史记录,因此请注意 100,000 token 的上下文窗口,它由提示词和回复共享。如果你使用同时触发多个请求的群聊,请记住完整密钥的 8 个并发请求限制(试用密钥为 2)。角色扮演和伴侣设置面向成年人;在任何提示词下,模型都不会生成涉及未成年人的性内容。
LangChain
在 Python 中,langchain-openai 包提供 ChatOpenAI,它接受自定义 Base 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 通过 ChatOpenAI 上的 configuration: { baseURL } 选项采用相同的思路。
Cursor 和其他编辑器
Cursor 等几个其他代码编辑器都有模型设置区域,你可以在其中提供自己的 OpenAI API 密钥并覆盖 Base URL。大致步骤:打开模型设置,启用自定义 OpenAI 密钥选项,将覆盖 Base URL 设置为 https://api.nanobananaapis.com/v1,粘贴你的密钥,并将 uncensored 添加为自定义模型名称。
对它能提供的功能保持现实。编辑器围绕其自己的后端和特定模型名称构建了一些功能,因此自定义接口可能仅适用于聊天或命令子集。确切选项在不同版本中会有所变化,因此请检查编辑器的当前文档。如果某项功能需要此 API 未提供的功能(如嵌入或图像输入),则无法通过此接口工作。
其他 OpenAI 兼容客户端(如 Open WebUI、Continue 和类似聊天前端)也适用相同模式:找到自定义 OpenAI 接口字段,输入三个值,然后测试。
原生 SDK 和环境变量
如果你编写自己的代码,官方 SDK 读取标准环境变量,这允许你在不触碰源文件的情况下切换接口。在 Python 和 Node SDK 中,设置 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 未授权 | 密钥错误,或标头缺少 Bearer | 重新复制密钥并使用 curl 测试 |
| 404 未找到 | Base URL 缺少 /v1,或路径重复 | 精确使用 https://api.nanobananaapis.com/v1 |
| 未找到模型 | 工具默认为供应商模型名称 | 将模型设置为 uncensored |
429 带有rate_limited | 每分钟超过 300 个请求(试用版为 60 个) | 降低频率并重试 |
429 错误对应 concurrency | 同时超过 8 个请求(试用期间为 2) | 降低并行性 |
| 429 带有 Retry-After: 5 | 临时过载 | 等待五秒后重试 |
| 请求过大 | 主体超过 8 MB | 修剪附件或历史记录 |
请记住,流式请求会占用其并发槽位直到流结束,因此放弃流的编辑器可能会看起来像达到了限制,而实际上并不忙。记录失败调用的 X-Request-Id 标头;这是支持人员首先要求的内容。
在成本方面,一条典型的聊天消息输入 2,000 个 token,输出 500 个 token,在每 100 万 token 价格为 $0.15 和 $0.50 时费用为 $0.00055,失败的请求不扣费。定价页面涵盖了从 $20 到 $500 的充值以及奖励层级。
密钥、安全与数据可见性
每个集成都会将你的密钥存储在某个位置,但存储方式有优劣之分。在桌面端前端中,密钥存储在本地设置文件中。在基于浏览器的工具中,它可能保存在浏览器中。在编辑器中,它位于应用程序配置中。在共享屏幕、提交 dotfile 或将笔记本电脑交给他人之前,请了解你使用的是哪一种。
几条规则可以让管理变得简单。在可行的情况下,每个工具使用一个密钥,这样你可以替换单个密钥而不会影响其余部分。在寻求帮助时,不要将密钥粘贴到公共问题跟踪器中;而是共享请求 ID。如果密钥泄露,请从密钥页面替换它并更新你的工具。通过 API 发送的提示词不用于训练,隐私页面描述了其余的数据处理方式。
如果你为其他人托管前端,不要将密钥发送到浏览器。在你的用户和 API 之间放置一个小服务器,在那里添加你自己的限制,并将密钥保留在服务器上。你的用户将共享你的 8 个并发请求,因此请规划好同时可以聊天的人数。
哪种工具适合哪种工作
由于集成在所有地方都是相同的,工具的选择取决于你正在构建的内容。
- SillyTavern 或类似的聊天前端适合成人向的角色聊天、小说创作和角色扮演,当你需要一个精美的界面和角色卡片而不需要编写代码时。
- LangChain适合代码中的管道处理:加载器、提示词模板、解析器和多步链。它以增加一个依赖为代价提供结构化支持。
- 简单的 SDK 调用适合小型脚本和服务。如果你的任务是一个提示词输入和一个回答输出,仅使用 OpenAI 包比使用框架更容易维护。
- Cursor 等编辑器适合代码聊天。在依赖它之前,请检查其哪些功能支持自定义接口。
先从简单的 curl 测试开始,然后是 SDK,只有在确实需要时才添加框架。稍后迁移很容易,因为这三个值不会改变。对于首次请求和完整参数列表,请阅读文档。
