x402 API دليل التكامل

بداية سريعة

أرسل طلب POST مع صورتك كالجسم الخام. ليست هناك حاجة إلى رأس مصادقة — تستخدم واجهة برمجة التطبيقات x402 للدفع.

# Step 1: discovery — returns HTTP 402 with payment details
curl -X POST https://x402.clearcanvas.app/v1/remove-background \
  -H "Content-Type: image/png" \
  --data-binary @photo.png

# Step 2: paid request — attach X-PAYMENT header with signed USDC transfer
curl -X POST https://x402.clearcanvas.app/v1/remove-background \
  -H "Content-Type: image/png" \
  -H "X-PAYMENT: <base64-signed-payload>" \
  --data-binary @photo.png \
  --output result.png

المصادقة عبر x402

x402 هو بروتوكول دفع قياسي HTTP. في الطلب الأول، تقوم واجهة برمجة التطبيقات بإرجاع HTTP 402 مع تفاصيل الدفع. قم بالتوقيع على تحويل USDC على Base باستخدام Coinbase x402 SDK، ثم أعد إرساله باستخدام رأس X-PAYMENT.

TypeScript

import fs from 'fs';
import { wrapFetchWithPayment } from '@coinbase/x402';
import { privateKeyToAccount } from 'viem/accounts';

const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
const fetch402 = wrapFetchWithPayment(fetch, account);

const res = await fetch402('https://x402.clearcanvas.app/v1/remove-background', {
  method: 'POST',
  headers: { 'Content-Type': 'image/png' },
  body: fs.readFileSync('photo.png'),
});

const buffer = await res.arrayBuffer();
fs.writeFileSync('result.png', Buffer.from(buffer));

Python

import os
import httpx
from x402.client import wrap_httpx   # pip install x402

client = wrap_httpx(private_key=os.environ["PRIVATE_KEY"])
resp = client.post(
    "https://x402.clearcanvas.app/v1/remove-background",
    content=open("photo.png", "rb").read(),
    headers={"Content-Type": "image/png"},
)
open("result.png", "wb").write(resp.content)

تنسيق الطلب

• •نقطة النهاية
• •النص: بايتات الصورة الأولية (PNG، JPEG، أو WebP)
• •نوع المحتوى: صورة/png | صورة / JPEG | صورة/ويب
• •اختياري:?format=webp لإخراج WebP

تنسيق الاستجابة

• •HTTP 200 — صورة ثنائية (PNG أو WebP)
• •HTTP 402 — الدفع مطلوب (x402 التفاصيل في النص)

معالجة الأخطاء

• •400 — صورة غير صالحة (تنسيق سيء، أو عدم تطابق البايتات السحرية، أو تم تجاوز البعد)
• •413 — الملف كبير جدًا (> 25 ميجابايت)
• •415 — نوع المحتوى غير مدعوم
• •429 — تم تجاوز الحد الأقصى للسعر (الطلبات غير المدفوعة: 30/دقيقة/IP)
• •500 — فشلت المعالجة (يمكن إعادة المحاولة: صحيح)
• •503 - المعالج غير متاح مؤقتًا (قابل لإعادة المحاولة: صحيح)

الحدود والتنسيقات

• •الحد الأقصى لحجم الملف: 25 ميجابايت
• •الأبعاد القصوى: 10,000 × 10,000 بكسل
• •الإدخال المدعوم: PNG، JPEG، WebP
• •الإخراج: PNG (افتراضي) أو WebP

شبكة

تعمل واجهة برمجة التطبيقات (API) على الشبكة الرئيسية الأساسية. تتم تسوية المدفوعات بالدولار الأمريكي الحقيقي (0.05 دولار لكل صورة). تأكد من أن محفظتك تحتوي على USDC على Base قبل تقديم الطلبات.