اقرأ هذا أولاً: ما هي هذه الـ API وما لا تكونه
إذا وصلت إلى هنا تتساءل كيفية استخدام واجهة nano banana api لإنتاج الصور، فالإجابة الصادقة هي أن هذا الخدمة لا يمكنها القيام بذلك. "Nano Banana" هو اسم يربطه الناس عادةً بنموذج لتوليد الصور، وتوليد الصور غير مُقدَّم هنا. ما تقدمه nanobananaapis.com هو الوصول إلى نموذج لغوي نصي عبر نقطة نهاية متوافقة مع OpenAI.
لا يزال ذلك يناسب العديد من سير العمل المتعلقة بالصور، لأن أدوات الصور لا تكون أفضل من النص الذي تُغذّيه بها. يمكن للنموذج النصي كتابة الموجّهات، وتنويعها، والتحقق منها مقابل دليل الأسلوب، وإنتاج التسميات التوضيحية ونصوص بديل النص البديل (alt text)، وإعداد النصوص التي تربط خط الأنابيب معًا. تشرح هذه الصفحة استخدام ذلك. إذا كنت بحاجة إلى الصور فقط، فأنت تريد خدمة صور بدلاً من ذلك، ويمكنك ربطها بهذه الخدمة.
النموذج هو نموذج مفتوح الأوزان واحد، يُشغّله مزود مستقل، ومُضبط للإجابة بدون رفض المحتوى للاستخدام القانوني للبالغين. إنه ليس الواجهة الرسمية لأي مورد كبير. الحد الصارم الوحيد: لا يوجد محتوى جنسي يتضمن القاصرين.
الخطوة 1: احصل على مفتاح
سجّل باستخدام Google، أو باستخدام بريد إلكتروني وكلمة مرور، ثم افتح صفحة مفتاح API. سترى زرًا بنقرة واحدة للحصول على $0.50 من الرصيد التجريبي. صالح لمدة 7 أيام، ولا يتطلب بطاقة، ومحدود بنسخة واحدة لكل شخص. يسمح المفتاح التجريبي بـ 2 طلب متزامن و60 طلبًا في الدقيقة، وهو كافٍ لتجربة الميزات.
انسخ المفتاح واحتفظ به خارج مستودعك. في وحدة التحكم (shell) يمكنك تخزينه هكذا:
export NANOBANANA_KEY="paste-your-key-here"
الخطوة 2: إرسال طلبك الأول
ثلاثة قيم تهمك: عنوان URL الأساسي، ومعرف النموذج، وراسم التفويض (Authorization header). يتبع كل شيء تنسيق مكملات الدردشة الخاص بـ OpenAI. إليك أول استدعاء باستخدام curl:
curl https://api.nanobananaapis.com/v1/chat/completions -H "Authorization: Bearer $NANOBANANA_KEY" -H "Content-Type: application/json" -d '{
"model": "uncensored",
"messages": [
{"role": "user", "content": "Write one detailed image prompt for a foggy harbor at dawn."}
],
"max_tokens": 200
}'
نفس الشيء في Python باستخدام الحزمة الرسمية openai:
import os
from openai import OpenAI
client = OpenAI(
base_url="https://api.nanobananaapis.com/v1",
api_key=os.environ["NANOBANANA_KEY"],
)
r = client.chat.completions.create(
model="uncensored",
messages=[{"role": "user", "content": "Write one detailed image prompt for a foggy harbor at dawn."}],
)
print(r.choices[0].message.content)
وفي Node:
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.nanobananaapis.com/v1",
apiKey: process.env.NANOBANANA_KEY,
});
const r = await client.chat.completions.create({
model: "uncensored",
messages: [{ role: "user", content: "Write one detailed image prompt for a foggy harbor at dawn." }],
});
console.log(r.choices[0].message.content);
تحقق من رؤوس الاستجابة مرة واحدة. يُظهر X-Balance-USD رصيدك المتبقي، ويُعرّف X-Request-Id المكالمة إذا احتجت إلى مساعدة. تذكر صفحة التوثيق كل المعاملات المدعومة.
الخطوة 3: تحويل الأفكار إلى موجّهات منظمة
أكثر حيلة مفيدة لخط أنابيب الصور هي جعل النموذج يعيد بيانات منظمة بدلاً من النص الحر. وضع JSON يفعل ذلك. تصف المخطط في رسالة النظام، ويتم تحليل الرد مباشرة في كودك، بحيث تصبح قائمة بالأفكار الأولية جدولًا للموجّهات بحقول ثابتة.
import json, os
from openai import OpenAI
client = OpenAI(
base_url="https://api.nanobananaapis.com/v1",
api_key=os.environ["NANOBANANA_KEY"],
)
SYSTEM = (
"You write prompts for an image model. Reply with JSON only: "
'{"prompts": [{"subject": str, "style": str, "lighting": str, "negative": str, "full": str}]}'
)
def expand(idea: str, n: int = 3):
r = client.chat.completions.create(
model="uncensored",
response_format={"type": "json_object"},
temperature=0.9,
messages=[
{"role": "system", "content": SYSTEM},
{"role": "user", "content": f"Give {n} distinct prompts for: {idea}"},
],
)
return json.loads(r.choices[0].message.content)["prompts"]
for p in expand("a lighthouse keeper's kitchen in winter"):
print(p["full"])
ارفع درجة الحرارة عندما تريد التنوع وخفضها للاتساق. يتم تمرير معلمة seed، لذا يمكنك تثبيتها عندما تحتاج إلى إعادة إنتاج دفعة سابقة. قم دائمًا بتغليف json.loads داخل كتلة try وأعد إرسال الطلب مرة واحدة إذا فشل التحليل، لأن أي نموذج لغوي يمكن أن يخطئ.
يحتوي الموقع أيضًا على شرح ذي صلة بخصوص جانب الصور: توليد الموجّهات ومعالجتها بعد الإنشاء. يغطي كيفية ارتباط خطوة النص بالمولد.
مهام أخرى يؤديها النموذج النصي بشكل جيد في سير عمل الصور
- أوراق الأنماط. احتفظ برسالة نظام واحدة تحتوي على قواعد النمط الثابتة الخاصة بك، وأرسل كل موضوع جديد من خلالها، بحيث يبقى السلسلة بأكملها متسقًا بصريًا.
- التسميات التوضيحية ونصوص بديلة. بعد وجود الصور، صفها بكلمات قليلة لكل منها. مرر وصفك الخاص للصورة كمدخل؛ لا يمكن للنموذج رؤية الصور، لأن الـ API تقبل النص فقط.
- قوائم اللقطات والسيناريوهات. بالنسبة للقصة المصورة أو الفيديو القصير، صِغ قائمة المشاهد، التعليق الصوتي، والإيقاعات على الشاشة كنص.
- نقد الموجّه. الصق موجّهًا يعطي نتائج سيئة واطلب ثلاث إعادة صياغة مع شرح التغييرات.
- الأدب الخيالي وعمل الشخصيات للبالغين. أوراق الشخصيات، الخلفيات والحوار للقصص وتطبيقات الرفيق، مع عدم رفض النموذج للمواضيع القانونية للبالغين.
للأعمال الطويلة، بث المخرجات باستخدام stream: true حتى يتمكن واجهة المستخدم من عرض النص عند وصوله. دعم استدعاء الدوال أيضًا، مما يسمح للنموذج بقرار متى يستدعي دالةك الخاصة، مثل دالة ترسل موجّهًا إلى خدمة الصور التي تستخدمها.
الحدود وتكلفة التشغيل
اعرف الأرقام قبل أن تبني دفعة. مفتاح كامل يسمح بـ 8 طلبات متزامنة و300 طلب في الدقيقة. نافذة السياق هي 100,000 رمز تغطي الموجّه والإكمال، وحجم جسم الطلب الأقصى هو 8 MB، والمعلمة max_tokens اختيارية. تجاوز المعدل يعيد HTTP 429 مع الكود rate_limited أو concurrency؛ انتظر وأعد المحاولة.
التسعير هو $0.15 لكل مليون رمز مدخل و$0.50 لكل مليون رمز مخرج. قل أنك تولد 500 مجموعة موجّهات، كل منها يحتوي على إدخال 400 رمز وإخراج 600 رمز:
- الإدخال: 500 x 400 = 200,000 رمز x $0.15 / 1M = $0.03
- الإخراج: 500 x 600 = 300,000 رمز x $0.50 / 1M = $0.15
- المجموع: $0.18
لذلك يغطي رصيد التجربة بقيمة $0.50 حوالي 1,300 مجموعة من هذا الحجم. للاستخدام العادي، قم بشحن أي مبلغ صحيح من $20 إلى $500، بالعملات المشفرة فقط (USDT على TRC20، USDC على Base). المكافآت هي 5% من المبالغ التي تبدأ من $50، و10% من المبالغ التي تبدأ من $100، و15% من المبالغ التي تبدأ من $200. انظر صفحة الأسعار للحصول على الجدول. الرصيد لا ينتهي.
الاقتران مع خدمة صور
يتكون الإعداد المعتاد من مرحلتين. تستخدم مرحلة النص هذا الـ API لإنتاج الموجّهات. ترسل مرحلة الصور تلك الموجّهات إلى أي مولّد صور تستخدمه، وهذا المولّد لديه حسابه الخاص، وأسعاره الخاصة وقواعده الخاصة، والتي يجب أن تقرأها على موقعه. احتفظ بالمرحلتين في دوال منفصلة، حتى تتمكن من تغيير أي جانب دون إعادة كتابة الآخر.
نصيحة عملية: احفظ كل موجّه مع البذرة ودرجة الحرارة التي استخدمتها لإنشائه. عندما تظهر صورة بشكل جيد، يمكنك تتبعها إلى النص الدقيق الذي أنتجها، وعندما يخيب أمل مجموعة، يمكنك معرفة ما إذا كان الخطأ في الفكرة، أو كاتب الموجّه، أو نموذج الصور. كما يمنحك طريقة رخيصة لمقارنة رسالتي نظام بتشغيل كل منهما على نفس قائمة الأفكار وحكم على مجموعتي الموجّهات جنبًا إلى جنب.
سكربت صغير من البداية للنهاية
لربط الأجزاء معًا، إليك نص برمجي قصير يقرأ ملفًا يحتوي على أفكار أولية، ويوسع كل فكرة إلى موجّهات باستخدام وضع JSON، ثم يكتب النتيجة إلى ملف يمكن لأداة الصور الخاصة بك قراءته. يتعامل مع نمط فشل واحد قد يسبب لك مشكلة: الرد الذي ليس بصيغة JSON صالحة.
import json, os
from openai import OpenAI
client = OpenAI(
base_url="https://api.nanobananaapis.com/v1",
api_key=os.environ["NANOBANANA_KEY"],
)
def one(idea: str):
for _ in range(2):
r = client.chat.completions.create(
model="uncensored",
response_format={"type": "json_object"},
messages=[
{"role": "system", "content": 'Reply with JSON only: {"prompt": str}'},
{"role": "user", "content": f"Write a vivid, specific image prompt for: {idea}"},
],
max_tokens=250,
)
try:
return json.loads(r.choices[0].message.content)["prompt"]
except (json.JSONDecodeError, KeyError):
continue
return None
ideas = [line.strip() for line in open("ideas.txt") if line.strip()]
out = {i: one(i) for i in ideas}
json.dump(out, open("prompts.json", "w"), indent=2)
شغّله على خمس أفكار أولاً واقرأ النتائج بالعين. عدّل رسالة النظام حتى تتطابق الموجّهات مع الأسلوب الذي تريده، ثم قم بالتوسع. نظرًا لأن كل طلب هنا صغير، فإن ألف فكرة تنتهي بسرعة وتكلف سنتات.
الأخطاء التي يرتكبها المبتدئون
- توقع الصور. الاستجابة هي دائمًا نص. إذا حاولت كودك حفظ صورة ثنائية من الرد، فسيفشل، لأنه لا توجد صورة.
- البحث عن اسم نموذج مختلف. يوجد نموذج واحد فقط، ومعرفه هو
uncensored. نسخ اسم نموذج بائع من دليل يعطي خطأ "غير موجود". - نسيان رسالة النظام. بدونها، ليس للنموذج توجيه للنمط ويتشرد بين الموجّهات القصيرة والطويلة. ضع قواعدك هناك.
- إرسال الأسرار في الموجّهات. الموجّهات لا تُستخدم للتدريب، لكن لا يزال يتعين عليك تجنب لصق كلمات المرور أو المفاتيح الخاصة في أي إدخال للنموذج.
- تشغيل مئة طلب في وقت واحد. المفتاح الكامل يسمح بـ 8 في الوقت نفسه. استخدم مجموعة أو إشارة، وأضف إعادة محاولة لـ 429.
إذا تصرف شيء بشكل غريب، فإن صفحة الدعم هي المكان للسؤال، ومعرف الطلب من رؤوس الاستجابة يجعل السؤال أسهل بكثير في الإجابة.
