Nano Banana API

الإمكانيات

الأسعار والأرصدة

Each image costs 2 credits, including all supported resolutions and formats. Credits are reserved on acceptance, settled on success and refunded on failure. Generation times out after 30 minutes; refund_failed means refund recovery is pending.

Request idempotency is not supported. Each valid POST creates a new billable task. If a submission outcome is uncertain, query the returned taskId; retrying POST can create another task.

المصادقة

أنشئ مفتاح API في لوحة التحكم. يظهر المفتاح الكامل مرة واحدة فقط. احتفظ به في خادمك وأرسله كرمز حامل (Bearer token) مع كل طلب.

https://api.seevio.ai

Authorization: Bearer sk_live_your_api_key
Content-Type: application/json

قم بتعيين متغير البيئة SEEVIO_API_KEY قبل تشغيل هذه الأمثلة. يتم تشغيل أمثلة JavaScript على خادمك باستخدام Node.js؛ وتستخدم أمثلة Python حزمة requests.

جسم الطلب (Request body)

معلمات الإدخال

Aspect ratio defaults to auto. Unknown fields, including output quantity, are rejected. Each request generates exactly one image.

البدء السريع

أرسل هذا الطلب البسيط، واحفظ الـ taskId المسترجع، ثم استخدم مثال الاستعلام عن المهمة أدناه. قيمة الرصيد في استجابة الإنشاء تمثل المبلغ المحجوز.

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "nano-banana",
  "input": {
    "prompt": "A minimalist ceramic teapot on a stone pedestal, soft studio lighting",
    "aspect_ratio": "1:1",
    "output_format": "png",
    "generation_type": "text-to-image"
  }
}'

مثال على استجابة إنشاء المهمة

{
  "taskId": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "credits": 2
}

تحويل النص إلى صورة

Generate one image asynchronously per request. Supports text-to-image and image-to-image generation with your Seevio API key.

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "nano-banana",
  "input": {
    "prompt": "A minimalist ceramic teapot on a stone pedestal, soft studio lighting",
    "aspect_ratio": "1:1",
    "output_format": "png",
    "generation_type": "text-to-image"
  }
}'

تحويل صورة إلى صورة

For image editing, set generation_type to image-to-image and provide image_urls. All other parameters use the same contract.

استبدل عناوين URL الخاصة بالوسائط في example.com بملفات HTTPS الخاصة بك والمتاحة للعامة. عناوين URL التجريبية مخصصة لتوضيح هيكلية الطلب وليست أصولاً صالحة للتنزيل.

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "nano-banana",
  "input": {
    "prompt": "Change the teapot to matte sage green. Preserve its shape and the studio lighting.",
    "aspect_ratio": "1:1",
    "output_format": "png",
    "generation_type": "image-to-image",
    "image_urls": [
      "https://example.com/teapot.png"
    ]
  }
}'

الاستعلام عن مهمة

استبدل معرف المثال بـ taskId المسترجع من عملية الإنشاء. تعيد الاستعلامات فقط المهام المملوكة لمستخدم مفتاح API؛ وتعيد المعرفات غير المعروفة أو التي لا يمكن الوصول إليها خطأ HTTP 404.

استعلم كل 10–20 ثوانٍ كخطوة أولى، وتراجع مؤقتًا عند تلقي HTTP 429، وتوقف عندما تصبح الحالة completed أو failed. يُفضل استخدام خطاطيف الويب (webhooks) في بيئة الإنتاج. يقوم كل مثال كود أدناه باستعلام واحد.

curl --fail-with-body https://api.seevio.ai/v1/tasks/3f2aK9mR7xQp4TnZ8bLc6YwH \
  -H "Authorization: Bearer $SEEVIO_API_KEY"

في قائمة الانتظار

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "nano-banana",
  "credits": 2,
  "status": "queued",
  "billing_status": "reserved",
  "failed_reason": null,
  "data": {
    "results": [],
    "image_expires_at": null,
    "processing_time": null
  }
}

اكتملت

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "nano-banana",
  "credits": 2,
  "status": "completed",
  "billing_status": "charged",
  "failed_reason": null,
  "data": {
    "results": [
      "https://cdn.seevio.ai/api/images/example.png"
    ],
    "image_expires_at": "2026-10-12T00:00:00.000Z",
    "processing_time": 12
  }
}

فشلت

عندما ترجع نتيجة الاستعلام status=failed، فهذا يعني أن عملية الإنشاء قد انتهت دون نجاح. يمكنك قراءة سبب الفشل من failed_reason وحالة الفوترة من billing_status لمعرفة تفاصيل عملية الاسترداد. في هذا المثال، تعني refunded أنه تمت إعادة الرصيد المحجوز. يحتفظ الحقل credits بالقيمة الأصلية المحجوزة، ولا تتضمن الاستجابة أي بيانات في data.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171200,
  "model": "nano-banana",
  "credits": 2,
  "status": "failed",
  "billing_status": "refunded",
  "failed_reason": "Image generation failed."
}

Result links are provided for 30 days after storage. After expiry, results is empty.

خطاطيف الويب (Webhooks)

اضبط callback_url في طلب الإنشاء لتلقي طلب JSON POST عند اكتمال المهمة أو فشلها. يجب إرجاع استجابة بترميز 2xx في غضون 15 ثانية. تتم إعادة المحاولة للإرسال الفاشل؛ لذا يرجى معالجة الطلبات المتكررة بشكل متطابق (idempotently) باستخدام معرف المهمة.

يجب أن تدعم نقطة نهاية الاستدعاء الذاتي (Callback endpoint) استقبال طلبات من نوع POST مع نص طلب بتنسيق JSON ‏(Content-Type: application/json).

إنشاء مهمة مع تعيين خطاف الويب (callback)

curl --fail-with-body https://api.seevio.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEVIO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "model": "nano-banana",
  "input": {
    "prompt": "A minimalist ceramic teapot on a stone pedestal, soft studio lighting",
    "aspect_ratio": "1:1",
    "output_format": "png",
    "generation_type": "text-to-image"
  },
  "callback_url": "https://example.com/webhooks/seevio"
}'

Callbacks use the task query response structure; refunded failure notifications also include top-level credits_refunded. Use id to identify the task and status to distinguish completed from failed. Notifications may repeat: process them idempotently by id and status. Callbacks are unsigned; verify the task with the authenticated query endpoint. Delivery failure does not refund a successful task.

اكتملت المهمة: بيانات الاستدعاء الذاتي الناجح

يشير created_at إلى وقت إنشاء الحدث، وtask_created_at إلى وقت إنشاء المهمة، بالثواني وفق Unix. تعرض الأمثلة الحقول الموصى بها؛ وقد تتضمن الاستجابات حقولاً إضافية.

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171212,
  "model": "nano-banana",
  "credits": 2,
  "status": "completed",
  "billing_status": "charged",
  "failed_reason": null,
  "data": {
    "results": [
      "https://cdn.seevio.ai/api/images/example.png"
    ],
    "image_expires_at": "2026-10-12T00:00:00.000Z",
    "processing_time": 12
  },
  "task_created_at": 1789171200
}

فشلت المهمة: بيانات استدعاء ذاتي غير ناجح

{
  "id": "3f2aK9mR7xQp4TnZ8bLc6YwH",
  "created_at": 1789171212,
  "model": "nano-banana",
  "credits": 2,
  "status": "failed",
  "billing_status": "refunded",
  "failed_reason": "Image generation failed.",
  "task_created_at": 1789171200,
  "credits_refunded": 2
}

مثال للمستقبل (Receiver)

export async function POST(request: Request) {
  const callbackData = await request.json();

  if (callbackData.status === "completed") {
    const imageUrls = callbackData.data.results;
    // Save the image URLs and mark this task as completed in your application.
    console.log(callbackData.id, imageUrls);
  }

  if (callbackData.status === "failed") {
    const { failed_reason, credits_refunded } = callbackData;
    // Record the failure reason and refunded credits for this task.
    console.error(callbackData.id, failed_reason, credits_refunded);
  }

  return new Response(null, { status: 200 });
}

يقرأ نموذج Next.js هذا نص استجابة JSON للتعامل مع المهام المكتملة والفاشلة مباشرةً. يُرجى إضافة ميزة الحفظ الدائم وتجنب تكرار معرفات المهام (Task-ID) في تطبيقك، مع جدولة المهام البطيئة في قائمة انتظار قبل تأكيد الاستدعاء الذاتي.

الأخطاء

تحتوي أخطاء HTTP على كائن خطأ يضم الرمز (code) والرسالة (message). يمكن للمهمة المقبولة بنجاح أن تفشل لاحقًا؛ لذا استعلم عن المهمة أو تعامل مع خطاك الراجع للفشل.

{
  "error": {
    "code": "invalid_request",
    "message": "input.prompt is required."
  }
}

Errors use error.code and error.message: 400 invalid_request, 401 invalid_api_key, 402 insufficient_credits, 403 forbidden, 404 not_found, 429 rate_limited, 500 internal_error. Insufficient provider balance is not a customer 402 error.

حدود معدل الطلبات

إنشاء المهام: يتيح كل مفتاح واجهة برمجة تطبيقات (API key) ما يصل إلى 100 طلب في الدقيقة افتراضيًا. حدود معدل الطلبات المخصصة غير متوفرة حاليًا.

الاستعلام عن المهام: يتيح كل مفتاح واجهة برمجة تطبيقات (API key) ما يصل إلى 120 طلبًا في الدقيقة افتراضيًا. ويتم احتساب طلبات الاستعلام وطلبات إنشاء المهام بشكل منفصل.

Image and video creation requests share the same API key rate limit.

يتضمن خطأ HTTP 429 الرأس Retry-After: 60 لعمليات الإنشاء، والرأس Retry-After: 5 للاستعلامات. استخدم التراجع التدريجي وتجنب الاستقصاء بمعدل أكبر من اللازم.

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 60

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded."
  }
}