Ba giá trị mà mọi tích hợp đều cần
Gần như mọi hướng dẫn về tích hợp nanobanana api đều quy về việc điền cùng ba trường trong một vị trí khác nhau. Dịch vụ này sử dụng giao thức chat-completions của OpenAI, vì vậy một công cụ cho phép bạn ghi đè endpoint OpenAI có thể giao tiếp với nó.
| Trường | Giá trị |
|---|---|
| URL gốc | https://api.nanobananaapis.com/v1 |
| Khóa API | Khóa của bạn, được gửi dưới dạng Authorization: Bearer <key> |
| ID mô hình | uncensored |
Một lưu ý về phạm vi trước khi bạn bắt đầu. Đây là một mô hình ngôn ngữ văn bản, vì vậy nó sẽ không hoạt động ở những nơi yêu cầu tạo ảnh, giọng nói hoặc embeddings. Các phương thức được hỗ trợ là POST /v1/chat/completions và GET /v1/models. Nếu một công cụ yêu cầu một mô hình embeddings cho tìm kiếm, hãy trỏ phần đó về một nhà cung cấp khác.
Bạn lấy khóa từ trang khóa API. Tài khoản mới có thể nhận $0.50 tín dụng dùng thử chỉ với một cú nhấp chuột, không cần thẻ, có hiệu lực trong 7 ngày.
Kiểm tra endpoint trước khi chạm vào bất kỳ công cụ nào
Khi một tích hợp bị lỗi, mọi người thường đổ lỗi cho công cụ. Phần lớn thời gian khóa hoặc URL bị sai. Một lệnh kiểm tra curl trong 30 giây sẽ loại bỏ nghi ngờ đó. Đầu tiên, hãy liệt kê các mô hình:
curl https://api.nanobananaapis.com/v1/models -H "Authorization: Bearer YOUR_API_KEY"
Sau đó gửi một yêu cầu trò chuyện ngắn:
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}'
Nếu cả hai đều hoạt động, endpoint và khóa đều ổn, và bất kỳ lỗi nào sau đó đến từ cách cấu hình công cụ. Nếu lệnh gọi đầu tiên trả về 401, khóa bị sai hoặc thiếu từ Bearer trong header. Lỗi 404 thường có nghĩa là URL thiếu /v1 hoặc có thêm đường dẫn.
SillyTavern
SillyTavern là giao diện người dùng cho trò chơi nhập vai và trò chuyện nhân vật, và nó cho phép bạn thêm một endpoint tương thích OpenAI. Các nhãn menu thay đổi giữa các bản phát hành, vì vậy hãy coi các bước này là một bản đồ hơn là từ ngữ chính xác.
- Mở bảng kết nối API và chọn Chat Completion làm loại API.
- Chọn nguồn Custom (OpenAI-compatible).
- Dán
https://api.nanobananaapis.com/v1làm URL endpoint. - Dán khóa của bạn vào trường khóa.
- Nhập
uncensoredlàm tên mô hình, hoặc nhấn nút kết nối và chọn nó từ danh sách màGET /v1/modelstrả về. - Nhấn kết nối và gửi một tin nhắn kiểm tra.
Hai lưu ý tinh chỉnh. SillyTavern gửi lịch sử dài với các thẻ nhân vật, vì vậy hãy chú ý đến cửa sổ ngữ cảnh 100.000 token, được chia sẻ bởi prompt và phản hồi. Và nếu bạn sử dụng các cuộc trò chuyện nhóm kích hoạt nhiều yêu cầu cùng lúc, hãy nhớ giới hạn 8 yêu cầu đồng thời trên khóa đầy đủ (2 trên khóa dùng thử). Các thiết lập nhập vai và bạn đồng hành dành cho người lớn; mô hình sẽ không tạo nội dung tình dục liên quan đến người chưa thành niên dưới bất kỳ prompt nào.
LangChain
Trong Python, gói langchain-openai cung cấp ChatOpenAI, chấp nhận một base URL tùy chỉnh. Cài đặt nó với 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)
Các chuỗi, mẫu prompt và trình phân tích đầu ra hoạt động giống nhau sau đó, vì chúng chỉ quan tâm đến giao diện trò chuyện. Gọi công cụ đi qua đường dẫn tiêu chuẩn, vì vậy llm.bind_tools([...]) gửi tools trong yêu cầu. Kiểm tra một lệnh gọi công cụ đơn lẻ trước khi xây dựng agent xung quanh nó, và giới hạn độ song song của agent ở mức 8. Một đồ thị phân nhánh thành hai mươi nhánh sẽ gặp lỗi concurrency.
Gói JavaScript @langchain/openai lấy cùng ý tưởng thông qua tùy chọn configuration: { baseURL } trên ChatOpenAI.
Cursor và các trình soạn thảo khác
Cursor, giống như một số trình soạn thảo mã khác, có khu vực cài đặt cho mô hình nơi bạn có thể cung cấp khóa API OpenAI của riêng bạn và ghi đè base URL. Khá chính xác: mở cài đặt mô hình, bật tùy chọn khóa OpenAI tùy chỉnh, đặt base URL ghi đè thành https://api.nanobananaapis.com/v1, dán khóa của bạn và thêm uncensored làm tên mô hình tùy chỉnh.
Hãy thực tế về những gì điều này mang lại cho bạn. Các trình soạn thảo xây dựng một số tính năng, chẳng hạn như hoàn thành nội tuyến, xung quanh các backend riêng của chúng và các tên mô hình cụ thể, vì vậy một endpoint tùy chỉnh có thể chỉ áp dụng cho trò chuyện hoặc một tập hợp con các lệnh. Các tùy chọn chính xác thay đổi giữa các phiên bản, vì vậy hãy kiểm tra tài liệu hiện tại của trình soạn thảo. Nếu một tính năng yêu cầu điều gì đó mà API này không cung cấp, chẳng hạn như embeddings hoặc đầu vào hình ảnh, nó sẽ không hoạt động thông qua endpoint này.
Mẫu tương tự cũng áp dụng cho các ứng dụng khách tương thích OpenAI khác như Open WebUI, Continue và các giao diện trò chuyện tương tự: hãy tìm trường cho một endpoint OpenAI tùy chỉnh, nhập ba giá trị và kiểm tra.
Các SDK thuần túy và biến môi trường
Nếu bạn viết mã của riêng mình, các SDK chính thức đọc các biến môi trường tiêu chuẩn, cho phép bạn chuyển đổi các endpoint mà không cần chạm vào các tệp nguồn. Trong các SDK Python và Node, việc đặt OPENAI_BASE_URL và OPENAI_API_KEY là đủ.
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", ...)
Một client rõ ràng trong Node trông như thế này:
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 ?? "");
}
Truyền phát (streaming) đến qua SSE với việc báo cáo sử dụng ở cuối. Chi tiết tham số đầy đủ có trên trang tài liệu, và bài viết về tạo prompt hướng dẫn cách kết nối một bước văn bản với pipeline hình ảnh.
Khắc phục các lỗi phổ biến
| Triệu chứng | Nguyên nhân có thể | Cách khắc phục |
|---|---|---|
| 401 Không được ủy quyền | Sai khóa, hoặc header thiếu Bearer | Sao chép lại khóa và kiểm tra với curl |
| 404 Không tìm thấy | Base URL thiếu /v1, hoặc đường dẫn bị nhân đôi | Sử dụng chính xác https://api.nanobananaapis.com/v1 |
| Không tìm thấy mô hình | Công cụ mặc định sang tên mô hình của nhà cung cấp | Đặt mô hình thành uncensored |
429 với rate_limited | Quá 300 yêu cầu mỗi phút (60 trên dùng thử) | Giảm tốc độ và thử lại |
429 với concurrency | Hơn 8 yêu cầu cùng lúc (2 trên dùng thử) | Giảm độ song song |
| 429 với Retry-After: 5 | Quá tải tạm thời | Chờ năm giây và thử lại |
| Yêu cầu quá lớn | Body trên 8 MB | Cắt giảm tệp đính kèm hoặc lịch sử |
Hãy nhớ rằng một yêu cầu truyền phát giữ slot yêu cầu đồng thời của nó cho đến khi luồng kết thúc, vì vậy một trình soạn thảo hủy luồng có thể trông giống như đang chạm giới hạn khi nó không bận. Hãy ghi lại tiêu đề X-Request-Id từ các lệnh gọi bị lỗi; đây là điều đầu tiên bộ phận hỗ trợ sẽ hỏi.
Về chi phí, một tin nhắn trò chuyện điển hình với 2.000 token đầu vào và 500 token đầu ra tốn $0.00055 ở mức $0.15 và $0.50 cho 1M token, và các yêu cầu bị lỗi không bị tính phí. trang giá cả bao gồm các khoản nạp tiền từ $20 đến $500 và các cấp độ thưởng.
Khóa, bảo mật và ai xem được gì
Mỗi tích hợp lưu trữ khóa của bạn ở đâu đó, và một số lưu trữ tốt hơn những người khác. Trong một front end trên máy tính để bàn, khóa nằm trong một tệp cài đặt cục bộ. Trong một công cụ dựa trên trình duyệt, nó có thể được lưu trong trình duyệt. Trong một trình soạn thảo, nó tồn tại trong cấu hình ứng dụng. Hãy biết bạn đang sử dụng cái nào trước khi chia sẻ màn hình, cam kết một tệp dotfile hoặc đưa máy tính xách tay cho người khác.
Một số quy tắc giữ cho điều này có thể quản lý được. Sử dụng một khóa cho mỗi công cụ nơi bạn có thể, vì vậy bạn có thể thay thế một khóa đơn lẻ mà không làm hỏng những cái khác. Không bao giờ dán khóa vào một issue tracker công cộng khi xin trợ giúp; hãy chia sẻ ID yêu cầu thay thế. Nếu khóa bị rò rỉ, hãy thay thế nó từ trang khóa và cập nhật các công cụ của bạn. Các prompt gửi qua API không được sử dụng để huấn luyện, và trang quyền riêng tư mô tả phần còn lại của việc xử lý dữ liệu.
Nếu bạn lưu trữ một front end cho người khác, đừng phân phối khóa của bạn đến trình duyệt. Đặt một máy chủ nhỏ giữa người dùng của bạn và API, thêm các giới hạn của riêng bạn ở đó, và giữ khóa trên máy chủ. Người dùng của bạn sau đó chia sẻ 8 yêu cầu đồng thời của bạn, vì vậy hãy lập kế hoạch xem có bao nhiêu người có thể trò chuyện cùng lúc.
Công cụ nào phù hợp với công việc nào
Vì tích hợp giống nhau ở mọi nơi, việc lựa chọn công cụ phụ thuộc vào những gì bạn đang tạo ra.
- SillyTavern hoặc một front end trò chuyện tương tự phù hợp với trò chuyện nhân vật, tiểu thuyết và nhập vai dành cho người lớn, nơi bạn muốn một giao diện được tinh chỉnh và các thẻ nhân vật mà không cần viết mã.
- LangChain phù hợp với các pipeline trong mã: bộ tải, mẫu prompt, trình phân tích và chuỗi nhiều bước. Nó thêm cấu trúc với cái giá là một phụ thuộc nữa.
- Một lệnh gọi SDK đơn giản phù hợp với các tập lệnh nhỏ và dịch vụ. Nếu nhiệm vụ của bạn là một prompt đầu vào và một câu trả lời đầu ra, gói OpenAI đơn thuần dễ bảo trì hơn một framework.
- Một trình soạn thảo như Cursor phù hợp với trò chuyện về mã. Hãy kiểm tra xem tính năng nào của nó chấp nhận endpoint tùy chỉnh trước khi bạn dựa vào nó.
Hãy bắt đầu với bài kiểm tra curl đơn giản, sau đó đến SDK, rồi mới thêm framework khi bạn cảm thấy cần. Việc di chuyển sau này rất dễ dàng vì ba giá trị này không bao giờ thay đổi. Để xem yêu cầu đầu tiên và danh sách đầy đủ các tham số, hãy đọc tài liệu.
