واجهة برمجة توليد الذكاء الاصطناعي عبر x402: الدفع لكل استدعاء دون حساب

يُعد x402 بروتوكول دفع مفتوحاً يحول رمز الحالة المنسي HTTP 402 إلى جدار دفع عملي: يرد الخادم على الطلب بالحالة 402 Payment Required مرفقاً بشروط دفع قابلة للقراءة آلياً، ويوقع العميل تفويض تحويل بالعملات المستقرة، ثم يعيد إرسال الطلب ويستلم نتيجته. دون حساب، ودون مفتاح API، ودون اشتراكات شهرية. نقلت شركة Coinbase البروتوكول إلى Linux Foundation في أبريل 2026، وبحلول بدء العمليات التشغيلية لمؤسسة x402 Foundation، انضمت 40 منظمة عضواً تشمل AWS وGoogle وStripe وVisa وMastercard. لم يعد هذا مجرد تجربة رقمية محدودة.

الإجابة السريعة: نقطة نهاية x402 لخدمة BananaBanana متاحة على الرابط https://bananabanana.pro/api/x402. أرسل طلب POST مع { "tool": "...", "arguments": {...} }، واستلم رد 402 بالتكلفة الدقيقة لتلك المدخلات، وادفعها بعملة USDC على شبكة Base، ثم أعد إرسال الطلب. تبدأ أسعار الصور من $0.03، والفيديو من $0.30، وتوليد الصوت من $0.01 لكل 200 حرف. لا يتم خصم تكلفة الصور والصوت إلا عند إنشاء الملف بنجاح.

الجملة الأخيرة هي النقطة المحورية التي تتجاهلها معظم المقالات حول x402، وسنركز عليها بتفصيل. تحصيل المدفوعات أمر يسير؛ لكن عدم الخصم عند فشل الطلبات هو الجوهر الحقيقي للتصميم البرمجي الرصين.

كيف تتم عملية الدفع عملياً

أربع خطوات فقط، ويتولى عميل HTTP لديك تنفيذ ثلاث منها تلقائياً:

1. يرسل وكيلك طلب POST قياسياً بصيغة JSON دون أي ترويسة دفع.
2. يرد الخادم بالحالة 402 مع مصفوفة accepts. تتضمن شروط الدفع المبلغ بالوحدات الذرية (atomic units)، وعنوان المستلم، وعقد USDC، والشبكة، ومهلة الانتهاء.
3. يوقع العميل تفويض تحويل بمعيار EIP-3009 لهذا المبلغ تحديداً، ويشفره بترميز Base64 في ترويسة X-PAYMENT.
4. يُعاد إرسال الطلب نفسه حاملاً الترويسة. يمرر الخادم التوقيع إلى الوسيط (facilitator) للتحقق منه، ثم ينفذ عملية التوليد، ويطلب من الوسيط إجراء التسوية على الشبكة (on-chain).

التوقيع ليس معاملة فورية على البلوكشين؛ بل هو تفويض خارج الشبكة (off-chain) لا يتحول إلى تحويل فعلي إلا عند تقديمه للشبكة. هذا ما يتيح نموذج المرحلتين: التحقق أولاً، ثم التوليد، وأخيراً التسوية.

ملاحظة تطبيقية: تعيد مواصفة الإصدار الثاني v2 تسمية الترويسات إلى PAYMENT-SIGNATURE وPAYMENT-RESPONSE، لكن معظم العملاء الحاليين يرسلون X-PAYMENT، ونحن نقبله بالكامل. إذا كنت تستخدم حزمة TypeScript SDK الرسمية، فسيتم التعامل مع هذا الاختلاف تلقائياً.

تكلفة الاستدعاء الواحد

تُحسب الأسعار لكل عملية توليد ويتم تحديدها بوضوح قبل أن توقع أي معاملة. تعتمد القيمة الدقيقة على المدخلات (فصورة 4K تختلف في تكلفتها عن 1K)، لذا فإن رد 402 يسعّر طلبك المحدد.

مقطع فيديو مدته 3 ثوانٍ على Omni مع الصوت يكلف $0.30، وهو الخيار الأكثر اقتصادية لإنشاء فيديو فعلي في القائمة. يوفر Veo دقة وتفاصيل أعلى، لكن تكلفة مقطع 8 ثوانٍ بدقة 1080p مع الصوت ترتفع بشكل ملحوظ إذا كان الغرض مسودة أولية.

يمكنك الاطلاع على قائمة الأسعار المحدثة مباشرة: يُرجع الطلب GET https://bananabanana.pro/api/x402 الكتالوج الكامل مجاناً دون الحاجة لأي دفع.

طلبان متتاليان: الدورة الكاملة

إليك دورة العمل الكاملة باستخدام curl، باستثناء خطوة التوقيع (التي تتولاها مكتبة عميل x402 الخاصة بك):

# 1. طلب عرض سعر. بدون ترويسة دفع: استلام تفاصيل التكلفة.
curl -s -X POST https://bananabanana.pro/api/x402 \
  -H 'Content-Type: application/json' \
  -d '{"tool":"generate_image","arguments":{"prompt":"a paper boat on still water at dawn","model":"nano-banana-pro","resolution":"2048"}}'

{
  "x402Version": 1,
  "error": "Payment required: $0.11 for generate_image.",
  "accepts": [{
    "scheme": "exact",
    "network": "base",
    "maxAmountRequired": "110000",
    "resource": "https://bananabanana.pro/api/x402",
    "payTo": "0x7c0e9abd1c48380e27ab5bfced1be54f23ce773f",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "maxTimeoutSeconds": 300,
    "extra": { "name": "USD Coin", "version": "2" }
  }]
}

وقّع هذه المعاملة وأعد إرسال الطلب مع الترويسة، وسيقدم الرد الثاني الملف المكتمل:

{
  "paid_usd": 0.11,
  "result": {
    "status": "completed",
    "images": [{ "url": "https://bananabanana.pro/api/files/..." }]
  }
}

تفصيلان تقنيان أساسيان لمطوري خوادم x402: تُحدد قيمة maxAmountRequired بالوحدات الذرية. نظراً لأن عملة USDC تحتوي على 6 منازل عشرية، فإن $0.11 تقابل 110000. كما يجب أن تتطابق قيمة extra.name بدقة مع ما ترجعه دالة name() في عقد USDC (على شبكة Base mainnet هي USD Coin، بينما على Base Sepolia هي USDC)، إذ تُستخدم هذه القيمة في حساب domain separator وفق معيار EIP-712. أي اختلاف سيؤدي إلى فشل التحقق من التوقيع دون إشعار خطأ واضح.

اختلاف آلية الفيديو: الدفع المسبق ورمز الاسترداد عند الإخفاق

تكتمل معالجة الصور والصوت خلال فترة طلب HTTP نفسه (تحقق ← توليد ← تسوية). ولا يتم الخصم إلا عند إنشاء الملف بنجاح. وفي حال الرفض بواسطة فلاتر الأمان أو انتهاء المهلة، لا يُرسل التوقيع إلى البلوكشين ولا تتكبد أي تكلفة.

أما الفيديو فيعمل بأسلوب مختلف: تستغرق المعالجة في Veo أو Omni ما بين دقيقة وعشر دقائق، ولا يمكن إبقاء اتصال HTTP مفتوحاً لهذه المدة، كما أن العملية إذا بدأت لدى Google لا يمكن إلغاؤها (حيث ترجع دالتهم interactions.cancel الرمز 501 UNIMPLEMENTED). لذلك تتم تسوية تكلفة الفيديو مقدماً، ويُرجع الخادم job_id للاستعلام عن النتيجة عبر نقطة نهاية مجانية.

ماذا يحدث إذا رُفض مقطع فيديو مدفوع من قبل فلاتر الأمان؟

تتلقى رمز استرداد (refund token) بكامل القيمة بصيغة bb_rf_… صالحاً لمدة 90 يوماً، ويمكنك استخدامه في أي طلب لاحق عبر تمريره في المعامل refund_token. إذا دفعت $1.30 لمقطع حُظر بواسطة الفلتر، فسيُخصم $1.30 من تكلفة طلبك القادم. وإذا كانت تكلفة الطلب الجديد أقل من قيمة الرمز، يُعاد الفارق في صورة رمز استرداد جديد.

هذا ليس استرداداً لعملة USDC على الشبكة، ونوضح ذلك بكل شفافية؛ إذ لا يحتفظ خادمنا بمفاتيح خاصة ولا يمكنه إرسال تحويلات خارجية، بل يقتصر دوره على قبول أو رفض التحويلات الواردة. وعدم وجود مفاتيح خاصة على الخادم يمثل ركيزة حماية أساسية لأمان خدمات x402.

أُنشئ هذا المقطع عبر نقطة النهاية المذكورة بتكلفة $0.30: نموذج Gemini Omni Flash، بمدة 3 ثوانٍ، بوصف مشهد متصل لحبر ينتشر في الماء داخل حوض زجاجي مع إضاءة جانبية هادئة وصوت محيطي منخفض التردد. الصوت مولد مباشرة من النموذج نفسه.

كيف يكتشف الوكيل نقطة النهاية

إذا كان الوكيل يعرف الرابط مسبقاً، فلا حاجة للاكتشاف. أما للوكلاء الآخرين، فتنشر الخدمة ملف البيان (manifest) على الرابط /.well-known/x402 (وكذلك /.well-known/x402.json).

يسرد البيان كل أداة كمورد مستقل مع شروط الدفع، ومعرف الشبكة وفق معيار CAIP-2، وعنوان الاستلام، والوسيط. يحدد حقل accepts في البيان السعر الأدنى للأداة وليس الحد الأقصى، مما يمنع الوكلاء من دفع مبالغ زائدة عن طريق الخطأ.

تستطلع أدلة الوكلاء نقاط النهاية أيضاً عبر إرسال طلبات POST فارغة، ويجيب خادمنا عليها بالرمز 402 متضمناً إرشادات استدعاء الأدوات.

المقارنة بين x402 والحساب التقليدي

يتصل كلا المسارين بنماذج الذكاء الاصطناعي نفسها. اختر المسار الأنسب لطبيعة وكيلك.

تمنح مكافآت الشحن ميزة مالية ملحوظة: إيداع $100 مع رمز ترويجي يمنحك رصيداً بقيمة $120 (خصم فعلي 17%)، وهو ما لا يتوفر في x402 لعدم وجود حسابات. في المقابل، لا يحتاج الوكيل المستقل ذو المحفظة إلى بريد إلكتروني، ويمكنه بدء الإنشاء بطلب واحد مباشر.

إذا كنت تفضل إدارة العمل عبر الحسابات، فإن خادم MCP يدعم Claude Code وCursor وVS Code، ويتوفر المولد عبر الويب مباشرة في المتصفح.

الأسئلة الشائعة

هل أحتاج إلى حساب على Coinbase للدفع؟

لا. أي محفظة EVM تحتوي على USDC على شبكة Base يمكنها الدفع. يتولى الوسيط التسوية بالكامل دون الحاجة لإنشاء حساب لديه.

ماذا يحدث إذا حُظر التوليد بواسطة فلاتر المحتوى؟

بالنسبة للصور والصوت لا يتم خصم أي مبلغ لأن التسوية تتم فقط عند اكتمال الملف. وبالنسبة للفيديو تتلقى رمز استرداد بالقيمة كاملة لاستخدامه في طلبات لاحقة.

ما هي الشبكات والعملات المدعومة؟

عملة USDC على شبكة Base الرئيسية (Base mainnet)، بنمط exact. يحتوي بيان /.well-known/x402 على معرف الشبكة CAIP-2 وعنوان عقد العملة.

هل يمكنني تعديل فيديو تم توليده عبر x402؟

ليس عبر x402. ترتبط ميزة التعديل بسجل الأعمال داخل الحساب (edit_video في MCP). ومن خلال x402 يمكنك دائماً توليد فيديوهات جديدة بالكامل.

كم تبلغ مدة صلاحية السعر المعروض؟

مهلة التوقيع محددة بـ 300 ثانية افتراضياً (maxTimeoutSeconds). وتتوافق الأسعار الأساسية مع الأسعار المعلنة في الموقع وتظل ثابتة.

جرب توليد صورة بقيمة $0.03 عبر نقطة النهاية المباشرة. إذا كان عميلك قادراً على توقيع تفويض EIP-3009، فأنت على بعد أربعة أسطر برمجية من استلام صورتك.