القيم الثلاث التي يحتاجها كل تكامل
تختزل معظم الأدلة حول تكامل واجهة برمجة تطبيقات nanobanana في ملء الحقول الثلاثة نفسها في مكان مختلف. الخدمة تتحدث بروتوكول chat-completions الخاص بـ OpenAI، لذا فإن الأداة التي تتيح لك تجاوز نقطة النهاية الخاصة بـ OpenAI يمكنها التحدث معها.
| الحقل | القيمة |
|---|---|
| عنوان URL الأساسي | https://api.nanobananaapis.com/v1 |
| مفتاح API | مفتاحك، يُرسل كـ Authorization: Bearer <key> |
| معرّف النموذج | 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 واختر Chat Completion كنوع API.
- اختر مصدر Custom (متوافق مع OpenAI).
- الصق
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، مثل العديد من محررات الأكواد الأخرى، على منطقة إعدادات للنماذج حيث يمكنك تزويد مفتاح OpenAI API الخاص بك وتعديل Base URL. تقريبًا: افتح إعدادات النموذج، فعّل خيار مفتاح OpenAI المخصص، اضبط Base URL للتجاوز على https://api.nanobananaapis.com/v1، الصق مفتاحك، وأضف uncensored كاسم نموذج مخصص.
كن واقعيًا بشأن ما يمنحك إياه ذلك. تبني المحررات بعض الميزات، مثل الإكمال المضمن، حول خوادمها الخلفية وأسماء النماذج المحددة، لذا قد ينطبق نقطة النهاية المخصصة فقط على الدردشة أو مجموعة فرعية من الأوامر. تتغير الخيارات الدقيقة بين الإصدارات، لذا تحقق من وثائق المحرر الحالية. إذا كانت ميزة تتطلب شيئًا لا تقدمه هذه API، مثل التضمينات أو إدخال الصور، فلن تعمل عبر نقطة النهاية هذه.
ينطبق النمط نفسه على عملاء آخرين متوافقين مع OpenAI مثل Open WebUI و Continue وواجهات الدردشة المماثلة: ابحث عن الحقل لنقطة نهاية OpenAI المخصصة، أدخل القيم الثلاث، واختبر.
SDKs بسيطة ومتغيرات البيئة
إذا كتبت كودك الخاص، فإن SDKs الرسمية تقرأ متغيرات البيئة القياسية، مما يتيح لك تبديل نقاط النهاية دون لمس ملفات المصدر. في SDKs 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 غير مصرح | مفتاح خاطئ، أو رأس Bearer مفقود | أعد نسخ المفتاح واختبر باستخدام curl |
| 404 غير موجود | عنوان 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 لكل مليون رمز، ولا يتم تحميل تكاليف الطلبات الفاشلة. يغطي صفحة التسعير شحنات الرصيد من $20 إلى $500 وفئات المكافآت.
المفاتيح، السلامة، ومن يرى ماذا
يخزن كل تكامل مفتاحك في مكان ما، وبعضها يخزنه بشكل أفضل من الآخرين. في الواجهة الأمامية لسطح المكتب، يوجد المفتاح في ملف إعدادات محلي. في الأداة التي تعمل على المتصفح، قد يتم حفظه في المتصفح. في محرر النصوص، يعيش في إعدادات التطبيق. اعرف أيًا منها تستخدم قبل مشاركة الشاشة أو إيداع ملف نقطة أو تسليم جهاز كمبيوتر محمول لشخص آخر.
بضع قواعد تجعل هذا قابلاً للإدارة. استخدم مفتاحًا واحدًا لكل أداة حيثما أمكن، بحيث يمكنك استبدال واحد دون كسر الباقي. لا تلصق مفتاحًا في نظام تتبع المشكلات العام عند طلب المساعدة؛ شارك معرف الطلب بدلاً من ذلك. إذا تسرب مفتاح، استبدله من صفحة المفاتيح وحدّث أدواتك. الموجهات المرسلة عبر API لا تُستخدم للتدريب، ويصف صفحة الخصوصية باقي التعامل مع البيانات.
إذا كنت تستضيف واجهة أمامية لآخرين، فلا ترسل مفتاحك إلى المتصفح. ضع خادمًا صغيرًا بين مستخدميك وAPI، وأضف حدودك الخاصة هناك، واحتفظ بالمفتاح على الخادم. ثم يشارك مستخدموك طلباتك المتزامنة البالغ عددها 8، لذا خطط لعدد الأشخاص الذين يمكنهم الدردشة في آن واحد.
أي أداة تناسب كل مهمة
نظرًا لأن التكامل هو نفسه في كل مكان، فإن اختيار الأداة يعتمد على ما تقوم بإنشائه.
- SillyTavern أو واجهة دردشة مماثلة تناسب دردشة الشخصيات، والخيال، ولعب الأدوار للبالغين، حيث تريد واجهة مستخدم متقنة وبطاقات شخصيات دون كتابة كود.
- LangChain يناسب خطوط الأنابيب في الكود: محمّلات، وقوالب الموجّه، ومحللات، وسلاسل متعددة الخطوات. يضيف الهيكلية مقابل اعتماد إضافي واحد.
- مكالمة SDK بسيطة تناسب النصوص البرمجية الصغيرة والخدمات. إذا كانت مهمتك هي موجّه واحد وإجابة واحدة، فإن حزمة OpenAI وحدها أقل صعوبة في الصيانة من إطار العمل.
- محرر مثل Cursor يناسب الدردشة حول الكود. تحقق من أي من ميزاته يقبل نقطة نهاية مخصصة قبل الاعتماد عليه.
ابدأ باختبار curl العادي، ثم SDK، ثم أضف إطار عمل فقط عندما تشعر بالحاجة. الانتقال لاحقًا سهل، لأن القيم الثلاث لا تتغير أبدًا. للحصول على الطلب الأول وقائمة المعاملات الكاملة، اقرأ التوثيق.
