所有整合都需要的三個值
幾乎所有關於 nanobanana api 整合的指南,最終都是在不同位置填入相同的三個欄位。該服務採用 OpenAI chat-completions 協定,因此允許你覆寫 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)
之後 Chains、提示詞模板與輸出解析器運作方式相同,因為它們只關心聊天介面。工具呼叫透過標準路徑進行,因此 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,費用為 $0.00055(每 1M token 價格為 $0.15 與 $0.50),且失敗的請求不會收費。定價頁面涵蓋了從 $20 到 $500 的儲值與獎金層級。
金鑰、安全性與資料可見性
每個整合套件都會將你的金鑰儲存在某個地方,但儲存的安全性各有不同。在桌面端前端中,金鑰存放在本機設定檔中;在基於瀏覽器的工具中,它可能會被保存在瀏覽器裡;在編輯器中,則存在於應用程式設定檔內。在共用螢幕、提交 dotfile 或將筆記型電腦交給他人之前,請先確認你使用的是哪一種方式。
幾項規則可讓管理變得輕鬆。在可能的情況下,每個工具使用一個金鑰,這樣替換單一金鑰時不會影響其他工具。在尋求協助時,不要將金鑰貼到公開的問題追蹤器中;請改用請求 ID 來分享。如果金鑰外洩,請從金鑰頁面替換它並更新你的工具。透過 API 傳送的提示詞不會用於模型訓練,更多資料處理方式請見 隱私權頁面。
如果你為其他人託管前端,不要將金鑰交付給瀏覽器。在你的使用者與 API 之間放置一個小型伺服器,在該伺服器上加入你自己的速率限制,並將金鑰保留在伺服器上。你的使用者將共用你的 8 個並行請求,因此請規劃好同時可以進行聊天的人數。
哪些工具適合哪些任務
由於整合方式在各處都相同,工具的選擇取決於你要建構的內容。
- SillyTavern 或類似的聊天前端適合成人角色扮演、小說與角色聊天,適合需要精緻介面與角色卡片且不想編寫程式碼的使用者。
- LangChain適合程式碼中的管線:載入器、提示詞範本、解析器與多步驟鏈。它以增加一個相依套件為代價來提供結構化。
- 基本 SDK 呼叫適合小型腳本與服務。如果你的任務是輸入一個提示詞並獲得一個回覆,僅使用 OpenAI 套件比使用框架更容易維護。
- Cursor 等編輯器適合程式碼相關的聊天。在依賴它之前,請檢查其哪些功能接受自訂端點。
先從簡單的 curl 測試開始,接著使用 SDK,只有在確實需要時才加入框架。後續遷移很輕鬆,因為這三個值都不會改變。關於第一個請求與完整參數列表,請閱讀文件。
