TokenLab
الحصول على مفتاح API
التوثيقمرجع APIالتكاملات

الصور

تعديل الصورة

تعديل صورة بناءً على وصف نصي وصورة أصلية

POST
/v1/images/edits

نظرة عامة

يقوم بإنشاء صورة معدلة أو موسعة بناءً على صورة أصلية ووصف نصي (prompt).

يدعم هذا الـ endpoint كلاً من:

  • تدفق رفع multipart/form-data المتوافق مع OpenAI والموثق أدناه.
  • طلبات JSON التي توفر image_url أو image_urls أو مراجع images الرسمية لعائلات تحويل الصورة إلى صورة (image-to-image) المدعومة.

يتم دعم gpt-image-2 هنا. وهو يقبل عمليات رفع image بصيغة multipart، وطلبات JSON التي تحتوي على image_url / image_urls، ومراجع images[] الرسمية (image_url أو file_id)، مع ما يصل إلى 16 صورة مصدر. قم بإنشاء قيم file_id من خلال /v1/files أولاً. اضبط async: true لإرجاع مهمة (task) أولاً؛ كما تستخدم نماذج تعديل FLUX/BFL الرسمية نفس تدفق استطلاع المهام (task polling).

تعديلات gpt-image-2 لا تقبل resolution؛ استخدم size لأبعاد المخرجات. يقبل background القيمة auto أو opaque؛ بينما لا يتم دعم transparent. بالنسبة للتعديلات متعددة الصور أو ذات زمن الاستجابة العالي، يفضل استخدام async: true واستطلاع المهمة المرجعة.

طلبات الصور المرجعية لـ Nano Banana (nano-banana-2 و nano-banana-2.1 و nano-banana-2-lite و nano-banana-pro) متاحة عبر /v1/images/generations مع operation: "image-to-image" و image_urls، وليس عبر هذا الـ endpoint /v1/images/edits. كما تستخدم طلبات تعديل الصور لـ nano-banana-2 و nano-banana-2.1 و nano-banana-2-lite و nano-banana-pro أيضاً /v1/images/generations مع operation: "image-edit".

تستخدم نماذج gemini-3.1-flash-image و gemini-nano-banana-2.1 و gemini-3.1-flash-lite-image و gemini-3-pro-image هذا الـ endpoint لتعديل الصور. بينما تستخدم طلبات تحويل الصورة إلى صورة الخاصة بها /v1/images/generations مع operation: "image-to-image".

تقبل نماذج تعديل الصور xAI Grok Imagine (grok-imagine-image و grok-imagine-image-quality و النموذج القديم grok-imagine-image-pro) ما يصل إلى 3 صور مصدر كحد أقصى. الطلبات التي تحتوي على أكثر من 3 صور مصدر ستفشل في التحقق من صحة المدخلات مع الخطأ 400 too_many_images.

input_fidelity ليس جزءاً من الحقول المدعومة حالياً في TokenLab لنموذج gpt-image-2؛ قم بحذفه وإلا سيعيد الطلب 400 unsupported_parameter.

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

مهلة الطلب المتزامن (Synchronous request timeout): تعيد بعض طلبات الصور الصورة النهائية بشكل مباشر وتنتظر حتى انتهاء عملية الإنشاء. يمكن أن تستغرق الطلبات عالية الدقة أو عالية الجودة حوالي دقيقة أو أكثر، لذا اضبط مهلة عميل HTTP الخاص بك على 120s على الأقل. إذا كانت استجابة الإنشاء تتضمن status: "pending" أو task_id أو poll_url، فاتبع poll_url المرجعة بدلاً من ذلك.

عناوين URL للصور البعيدة: عند الحاجة إلى مدخلات multipart، يقوم TokenLab بجلب image_url أو image_urls أو images[].image_url من JSON ويرسل البايتات كأجزاء image بصيغة multipart. يجب أن تكون عناوين URL عامة (http/https)، بدون بيانات اعتماد أو أجزاء (fragments) مضمنة، ويجب ألا تشير إلى localhost أو نطاقات IP خاصة أو محجوزة؛ يتم فحص كل إعادة توجيه (redirect) مرة أخرى. يجب أن تكون الحمولة المجلوبة صورة PNG أو JPEG أو WebP حقيقية. الحدود هي 50 MiB لكل صورة، و 200 MiB إجمالاً للصور المجلوبة عبر URL في طلب واحد، و 30s كمهلة للجلب، وما يصل إلى 3 عمليات إعادة توجيه.

بالنسبة لطلبات JSON، قدم واحداً فقط من image_url أو image_urls أو images. يجب أن يحتوي كل كائن images[] على واحد فقط من image_url أو file_id. يشمل الحد الإجمالي البالغ 200 MiB جميع الصور المصدر والقناع (mask).

imagefile

صور المصدر بصيغة multipart. كرر image لتوفير مصادر متعددة لـ GPT Image. يجب أن تكون الملفات بصيغة PNG أو JPEG أو WebP، بحد أقصى 16 صورة مصدر و 50 MiB لكل منها. تستخدم نماذج تعديل xAI Grok Imagine نفس حقول الإدخال ولكنها تحدد صور المصدر بـ 3 كحد أقصى.

promptstringمطلوب

وصف نصي للتعديل المطلوب.

maskfile | object

صورة إضافية تشير المناطق الشفافة تماماً فيها إلى المكان الذي يجب تعديل الصورة فيه. يجب أن تكون ملف PNG صالحاً، بحجم أقل من 50 MiB، ولها نفس أبعاد image.

بالنسبة لطلبات JSON، يمكن أن يكون mask أيضاً كائناً يحتوي على واحد فقط من image_url أو file_id؛ يجب أن تأتي قيم file_id من /v1/files وتظل مرتبطة بنفس إعدادات تعديل الصورة.

modelstringمطلوب

النموذج المستخدم لتعديل الصور. استخدم gpt-image-2 لتعديلات GPT Image، أو أي نموذج تعديل صور حالي آخر يتم إرجاعه بواسطة GET /v1/models?recommended_for=image.

nintegerالافتراضي: 1

عدد الصور المراد إنشاؤها (1-10، يعتمد على النموذج).

sizestring

حجم الصورة التي تم إنشاؤها. بالنسبة لـ gpt-image-2، استخدم auto أو WIDTHxHEIGHT؛ يجب أن تكون الأبعاد مضاعفات لـ 16، وأطول حافة بحد أقصى 3840px، ونسبة الطول إلى العرض بحد أقصى 3:1، وإجمالي البكسلات بين 655,360 و 8,294,400.

بالنسبة لـ gemini-3.1-flash-image و gemini-nano-banana-2.1 و gemini-3-pro-image و gemini-3.1-flash-lite-image، يقبل size حجم مخرجات من جدول أحجام النموذج أو فئة دقة: 1K أو 2K أو 4K. يرسل TokenLab الفئة كـ resolution. الفئة التي لا يدعمها النموذج، أو الفئة التي تختلف عن resolution، ستعيد 400 مع رمز الخطأ invalid_image_size_contract. الصيغة الموصى بها هي aspect_ratio مع resolution.

response_formatstring

كيفية إرجاع الصور: url أو b64_json.

  • في حال الحذف: عندما يعيد النموذج بايتات الصورة، تكون كل صورة في data[].b64_json، وأيضاً في data[].url عندما يقوم TokenLab بتخزينها. عندما يعيد النموذج رابطاً، تكون كل صورة في data[].url.
  • url: تكون كل صورة في data[].url فقط.
  • b64_json: تكون كل صورة في data[].b64_json فقط كبيانات Base64.

الروابط هي روابط نتائج وسائط TokenLab. تظل صالحة لمدة 30 يوماً. راجع الاحتفاظ بالبيانات.

asyncbooleanالافتراضي: false

اضبطه على true مع gpt-image-2 أو نماذج تعديل FLUX/BFL الرسمية لإرجاع مهمة قبل أن تكون الصورة النهائية جاهزة. تعيد التعديلات غير المتزامنة المكتملة روابط URL بغض النظر عن response_format المطلوب؛ استخدم الطلبات المتزامنة عندما تحتاج إلى b64_json.

userstring

معرف فريد يمثل المستخدم النهائي الخاص بك لمراقبة إساءة الاستخدام.

الاستجابة (Response)

createdinteger

طابع زمني (Unix timestamp) لوقت إنشاء الصور.

dataarray

مصفوفة الصور التي تم إنشاؤها.

يحتوي كل كائن على:

  • url (string): رابط نتيجة وسائط TokenLab للصورة المعدلة، صالح لمدة 30 يوماً. لا يظهر عند ضبط response_format على b64_json. عند حذف response_format، يختفي الرابط إذا لم يتمكن TokenLab من تخزين الصورة.
  • b64_json (string): بيانات الصورة بصيغة Base64. تظهر عند ضبط response_format على b64_json، أو عند حذفها وإرجاع النموذج لبايتات الصورة.

استجابة المهمة غير المتزامنة (Async Task Response)

اضبط async: true مع gpt-image-2 أو نماذج تعديل FLUX/BFL الرسمية لإنشاء مهمة بدلاً من انتظار الصورة المعدلة في الطلب. تتضمن الاستجابة status: "pending" و task_id و poll_url. قم باستطلاع /v1/tasks/{task_id} حتى تصل المهمة إلى حالة completed أو failed.

تعيد مهام التعديل غير المتزامنة روابط الصور النهائية فقط. إذا كنت بحاجة إلى بيانات صورة b64_json الخام، استخدم طلباً متزامناً.

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

الطلب

curl -X POST "https://api.tokenlab.sh/v1/images/edits" \
  -H "Authorization: Bearer sk-your-api-key" \
  -F "model=gpt-image-2" \
  -F "image=@sunlit_lounge.png" \
  -F "mask=@mask.png" \
  -F "prompt=A sunlit indoor lounge area with a pool" \
  -F "n=1" \
  -F "size=1024x1024"

الاستجابة

Response
{
  "created": 1706000000,
  "data": [
    {
      "url": "https://..."
    }
  ]
}

ملاحظات

يتم إرجاع حالات فشل جلب الصور البعيدة كأخطاء في المدخلات قبل بدء الإنشاء. عناوين URL التي لا يمكن الوصول إليها، والمهلات، واستجابات 403/404، والمضيفات الخاصة/الداخلية، وبيانات الاعتماد أو الأجزاء في URL، والمحتوى غير الصوري، والتنسيقات غير المدعومة، وتجاوز حدود الحجم، كلها تعيد 400 أو 413 وتحدد مدخل image_url / image_urls[n]. بالنسبة للأصول الخاصة أو المحمية برؤوس (headers)، قم برفع ملفات image بصيغة multipart مباشرة أو قم بإنشاء مراجع /v1/files.

يقوم Hy Image 3.5 Preview بإنشاء صور مربعة بدقة 1024 بكسل من النص وتعديل الصور المرجعية باستخدام تعليمات مكتوبة. إنه مفيد لتصميم العناصر المرئية وتحسين التكوين.

{
  "model": "hy-image-v3.5-preview",
  "prompt": "Change the table to pale blue",
  "image_url": "https://example.com/reference.png",
  "size": "1024x1024",
  "n": 1,
  "response_format": "url"
}

التفويض

BearerAuth
AuthorizationBearer <token>

مصادقة مفتاح API. قم بإنشاء أو إدارة مفاتيح API في Dashboard > API > API Keys.

الموضع: header

الترويسات

X-TokenLab-Delivery-Policy?string

سياسة التسليم لكل طلب. تتجاوز إعدادات API key و Workspace الافتراضية. يحاول النظام تلقائياً استخدام TokenLab Verified أولاً، وقد ينتقل مرة واحدة إلى Official فقط قبل المخرجات، أو قبول الطلب، أو إنشاء مورد دائم.

القيم المتاحة

  • "auto"
  • "verified"
  • "official"

جسم الطلب

الاستجابة

application/json

application/json

application/json

application/json

application/json

application/json

إنشاء صورة

السابق

إنشاء تنويع صورة

التالي