Tiga nilai yang dibutuhkan setiap integrasi
Hampir setiap panduan tentang integrasi api nanobanana berfokus pada mengisi tiga bidang yang sama di tempat yang berbeda. Layanan ini menggunakan protokol chat-completions OpenAI, sehingga alat yang memungkinkan Anda mengganti endpoint OpenAI dapat berkomunikasi dengan layanan ini.
| Bidang | Nilai |
|---|---|
| URL dasar | https://api.nanobananaapis.com/v1 |
| Kunci API | Kunci Anda, dikirim sebagai Authorization: Bearer <key> |
| ID model | uncensored |
Satu catatan ruang lingkup sebelum Anda memulai. Ini adalah model bahasa teks, sehingga tidak akan berfungsi di tempat yang mengharapkan pembuatan gambar, suara atau embedding. Metode yang didukung adalah POST /v1/chat/completions dan GET /v1/models. Jika alat meminta model embedding untuk pencarian, arahkan bagian itu ke penyedia lain.
Anda mendapatkan kunci dari halaman kunci API. Akun baru dapat mengklaim $0,50 kredit uji coba dengan satu klik, tanpa kartu, berlaku selama 7 hari.
Uji endpoint sebelum menyentuh alat apa pun
Saat integrasi gagal, orang menyalahkan alatnya. Sebagian besar waktu kunci atau URL-nya salah. Uji coba curl selama tiga puluh detik menghilangkan keraguan itu. Pertama, daftar model-modelnya:
curl https://api.nanobananaapis.com/v1/models -H "Authorization: Bearer YOUR_API_KEY"
Kemudian kirim permintaan obrolan singkat:
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}'
Jika keduanya berhasil, endpoint dan kunci baik-baik saja, dan kesalahan selanjutnya berasal dari cara alat dikonfigurasi. Jika panggilan pertama mengembalikan 401, kunci salah atau hilang kata Bearer di header. 404 biasanya berarti URL hilang /v1 atau memiliki jalur tambahan.
SillyTavern
SillyTavern adalah antarmuka depan untuk roleplay dan obrolan karakter, dan memungkinkan Anda menambahkan endpoint OpenAI-kompatibel. Label menu berubah antar rilis, jadi perlakukan langkah-langkah sebagai peta daripada kata-kata yang tepat.
- Buka panel koneksi API dan pilih Chat Completion sebagai tipe API.
- Pilih sumber Custom (Kompatibel OpenAI).
- Tempelkan
https://api.nanobananaapis.com/v1sebagai URL endpoint. - Tempelkan kunci Anda di bidang kunci.
- Masukkan
uncensoredsebagai nama model, atau tekan tombol sambungkan dan pilih dari daftar yang dikembalikan olehGET /v1/models. - Tekan sambungkan dan kirim pesan uji.
Dua catatan penyetelan. SillyTavern mengirim riwayat panjang dengan kartu karakter, jadi perhatikan jendela konteks 100.000 token, yang dibagi oleh prompt dan balasan. Dan jika Anda menggunakan obrolan grup yang memicu beberapa permintaan sekaligus, ingat batas 8 permintaan konkurensi pada kunci penuh (2 pada kunci uji coba). Pengaturan roleplay dan pendamping adalah untuk orang dewasa; model tidak akan menghasilkan konten seksual yang melibatkan anak di bawah umur di bawah prompt apa pun.
LangChain
Di Python, paket langchain-openai menyediakan ChatOpenAI, yang menerima base URL khusus. Instal dengan 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)
Rantai, template prompt, dan parser output bekerja dengan cara yang sama setelahnya, karena mereka hanya peduli tentang antarmuka obrolan. Pemanggilan alat melalui jalur standar, jadi llm.bind_tools([...]) mengirim tools dalam permintaan. Uji satu panggilan alat sebelum Anda membangun agen di atasnya, dan batasi konkurensi agen hingga 8. Grafik yang bercabang menjadi 20 cabang akan memicu kesalahan concurrency.
Paket JavaScript @langchain/openai mengambil ide yang sama melalui opsi configuration: { baseURL } pada ChatOpenAI.
Cursor dan editor lain
Cursor, seperti beberapa editor kode lainnya, memiliki area pengaturan untuk model di mana Anda dapat menyediakan kunci API OpenAI Anda sendiri dan menimpa base URL. Sekitar: buka pengaturan model, aktifkan opsi kunci OpenAI kustom, atur base URL pengganti ke https://api.nanobananaapis.com/v1, tempel kunci Anda, dan tambahkan uncensored sebagai nama model kustom.
Jadilah realistis tentang apa yang ini berikan. Editor membangun beberapa fitur, seperti penyelesaian baris, di sekitar backend mereka sendiri dan nama model tertentu, sehingga endpoint khusus mungkin hanya berlaku untuk obrolan atau subset perintah. Opsi yang tepat berubah antar versi, jadi periksa dokumentasi editor saat ini. Jika fitur memerlukan sesuatu yang tidak ditawarkan API ini, seperti embedding atau input gambar, itu tidak akan berfungsi melalui endpoint ini.
Pola yang sama berlaku untuk klien kompatibel OpenAI lainnya seperti Open WebUI, Continue dan antarmuka depan obrolan serupa: temukan bidang untuk endpoint OpenAI khusus, masukkan tiga nilai, dan uji.
SDK Biasa dan variabel lingkungan
Jika Anda menulis kode sendiri, SDK resmi membaca variabel lingkungan standar, yang memungkinkan Anda mengganti endpoint tanpa menyentuh file sumber. Di SDK Python dan Node, pengaturan OPENAI_BASE_URL dan OPENAI_API_KEY sudah cukup.
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", ...)
Klien eksplisit di Node terlihat seperti ini:
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 ?? "");
}
Streaming tiba melalui SSE dengan penggunaan token dilaporkan di akhir. Detail parameter lengkap ada di halaman dokumentasi, dan artikel tentang pembuatan prompt menunjukkan cara menghubungkan langkah teks ke pipa gambar.
Memperbaiki kegagalan umum
| Gejala | Penyebab yang mungkin | Perbaikan |
|---|---|---|
| 401 Tidak Diizinkan | Kunci salah, atau header Bearer hilang | Salin ulang kunci dan uji dengan curl |
| 404 Tidak Ditemukan | Base URL tanpa /v1, atau jalur ganda | Gunakan tepat https://api.nanobananaapis.com/v1 |
| Model tidak ditemukan | Alat secara default menggunakan nama model vendor | Atur model ke uncensored |
429 dengan rate_limited | Lebih dari 300 permintaan per menit (60 pada trial) | Perlambat dan coba lagi |
429 dengan concurrency | Lebih dari 8 permintaan sekaligus (2 pada uji coba) | Turunkan paralelisme |
| 429 dengan Retry-After: 5 | Beban berlebih sementara | Tunggu lima detik dan coba lagi |
| Permintaan terlalu besar | Body di atas 8 MB | Potong lampiran atau riwayat |
Perhatikan bahwa permintaan streaming memegang slot konkurensinya hingga streaming berakhir, sehingga editor yang meninggalkan streaming dapat terlihat seperti mencapai batas ketika tidak sibuk. Log header X-Request-Id dari panggilan yang gagal; itu adalah hal pertama yang akan diminta dukungan.
Dari segi biaya, pesan obrolan khas dengan 2.000 token masuk dan 500 keluar biayanya $0.00055 pada $0.15 dan $0.50 per 1 juta token, dan permintaan gagal tidak dikenakan biaya. Halaman harga mencakup isi saldo dari $20 hingga $500 dan tingkat bonus.
Kunci, keamanan, dan siapa melihat apa
Setiap integrasi menyimpan kunci Anda di suatu tempat, dan beberapa menyimpannya lebih baik daripada yang lain. Di antarmuka depan desktop, kunci berada dalam file pengaturan lokal. Di alat berbasis browser, kunci mungkin disimpan di browser. Di editor, kunci berada dalam konfigurasi aplikasi. Ketahui mana yang Anda gunakan sebelum membagikan layar, melakukan komit file dotfile, atau menyerahkan laptop kepada orang lain.
Beberapa aturan menjaga ini dapat dikelola. Gunakan satu kunci per alat jika memungkinkan, sehingga Anda dapat mengganti satu kunci tanpa merusak sisanya. Jangan pernah menempelkan kunci ke pelacak masalah publik saat meminta bantuan; bagikan ID permintaan sebagai gantinya. Jika kunci bocor, ganti dari halaman kunci dan perbarui alat Anda. Prompt yang dikirim melalui API tidak digunakan untuk pelatihan, dan halaman privasi menjelaskan sisa penanganan data.
Jika Anda meng-hosting antarmuka depan untuk orang lain, jangan kirim kunci Anda ke browser. Letakkan server kecil di antara pengguna Anda dan API, tambahkan batas Anda sendiri di sana, dan simpan kunci di server. Pengguna Anda kemudian berbagi 8 permintaan paralel Anda, jadi rencanakan berapa banyak orang yang dapat mengobrol sekaligus.
Alat mana cocok untuk pekerjaan mana
Karena integrasinya sama di mana-mana, pilihan alat bergantung pada apa yang Anda buat.
- SillyTavern atau antarmuka depan obrolan serupa cocok untuk obrolan karakter, fiksi, dan roleplay untuk orang dewasa, di mana Anda menginginkan antarmuka yang dipoles dan kartu karakter tanpa menulis kode.
- LangChain cocok untuk pipa dalam kode: pemuat, template prompt, parser, dan rantai multi-langkah. Ini menambahkan struktur dengan biaya satu dependensi tambahan.
- Panggilan SDK dasar cocok untuk skrip kecil dan layanan. Jika tugas Anda adalah satu prompt masuk dan satu jawaban keluar, paket OpenAI saja lebih sedikit harus dikelola dibandingkan kerangka kerja.
- Editor seperti Cursor cocok untuk obrolan tentang kode. Periksa fitur mana yang menerima endpoint kustom sebelum Anda bergantung padanya.
Mulailah dengan tes curl dasar, lalu SDK, lalu tambahkan kerangka kerja hanya ketika Anda merasa perlu. Pindah kemudian mudah, karena tiga nilai tidak pernah berubah. Untuk permintaan pertama dan daftar parameter lengkap, baca dokumentasi.
