الصور
تعديل الصورة
تعديل صورة بناءً على مطالبة وصورة مصدرية
نظرة عامة
ينشئ صورة معدلة أو موسعة بناءً على صورة أصلية ومطالبة.
يدعم هذا الـ endpoint كلا من:
- مسار الرفع
multipart/form-dataالمتوافق مع OpenAI والموضح أدناه - طلبات JSON التي توفر
image_url، أوimage_urls، أو مراجعimagesالرسمية لعائلات image-to-image المدعومة
النموذج gpt-image-2 مدعوم هنا. يقبل عمليات رفع image عبر multipart، وimage_url / image_urls عبر JSON، ومراجع images[] الرسمية (image_url أو file_id)، بما يصل إلى 16 صورة مصدرية. أنشئ قيم file_id عبر /v1/files أولاً. اضبط async: true لإرجاع مهمة أولاً؛ يستخدم كل نموذج يدرج async ضمن معلمات الدعم الخاصة به، مثل gpt-image-2 ونماذج تعديل FLUX، نفس مسار استطلاع المهام.
لا تقبل تعديلات 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 أيضًا الـ endpoint /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 لتعديل الصور. وتستخدم طلبات image-to-image الخاصة بها الـ endpoint /v1/images/generations مع operation: "image-to-image".
تقبل نماذج تعديل الصور xAI Grok Imagine عددًا محدودًا من الصور المصدرية: يقبل grok-imagine-image-2.0 ما يصل إلى 5 صور كحد أقصى، ويقبل grok-imagine-image ما يصل إلى 3 صور كحد أقصى. الطلبات التي تحتوي على صور مصدرية أكثر مما يقبله النموذج تفشل في التحقق من صحة المدخلات مع الخطأ 400 too_many_images. تستخدم طلبات image-to-image الخاصة بها هذا الـ endpoint أيضًا.
توضح تفاصيل كل نموذج (GET /v1/models/{model}، راجع الحصول على النموذج) الـ endpoint لكل عملية في tokenlab.request_format_summary.request_endpoint_by_operation، والحقول المقبولة والحدود في tokenlab.request_format_details.operation_constraints. تؤدي العملية المرسلة إلى endpoint غير صحيح إلى إرجاع 400 unsupported_endpoint.
المعلمة input_fidelity ليست جزءًا من الحقول المدعومة حاليًا في TokenLab لـ gpt-image-2؛ يجب حذفها وإلا سيرجع الطلب 400 unsupported_parameter.
جسم الطلب
مهلة الطلب المتزامن: تُرجع بعض طلبات الصور الصورة النهائية مضمنة وتنتظر اكتمال التوليد. قد تستغرق الطلبات عالية الدقة أو عالية الجودة ما يقرب من دقيقة أو أكثر، لذا اضبط مهلة عميل HTTP على 120s على الأقل. إذا كانت استجابة الإنشاء تتضمن status: "pending" أو task_id أو poll_url، فقم باستطلاع GET /v1/tasks/{task_id} بدلاً من ذلك.
عناوين URL للصور البعيدة: عند الحاجة إلى مدخلات multipart، يقوم TokenLab بجلب image_url أو image_urls أو images[].image_url من JSON وإرسال البايتات كأجزاء image ضمن multipart. يجب أن تكون عناوين URL عامة وتستخدم http/https، بدون بيانات اعتماد مضمنة أو fragments، ويجب ألا تؤدي إلى نطاقات IP محلية (localhost) أو خاصة أو محجوزة؛ ويتم فحص كل عملية إعادة توجيه مجددًا. يجب أن تكون الحمولة المج Validate صورة حقيقية بتنسيق PNG أو JPEG أو WebP. الحدود هي 50 MiB لكل صورة، و200 MiB إجمالاً للصور المجذوبة عبر URL في طلب واحد، ومهلة جلب تبلغ 30s، وما يصل إلى 3 عمليات إعادة توجيه.
بالنسبة لطلبات JSON، قدم واحدًا فقط من image_url أو image_urls أو images. يجب أن يحتوي كل كائن في images[] على واحد فقط من image_url أو file_id. يشمل الحد الإجمالي البالغ 200 MiB جميع الصور المصدرية والقناع (mask).
الصور المصدرية بتنسيق multipart. كرر image لتقديم مصادر متعددة لـ GPT Image. يجب أن تكون الملفات بتنسيق PNG أو JPEG أو WebP، حتى 16 صورة مصدرية وبحجم 50 MiB لكل منها. تستخدم نماذج تعديل xAI Grok Imagine نفس حقول المدخلات ولكنها تحد من الصور المصدرية: 5 صور كحد أقصى لـ grok-imagine-image-2.0 و3 كحد أقصى لنماذج تعديل xAI الأخرى.
وصف نصي للتعديل المطلوب، حتى 32,000 حرف. مطلوب لكل نموذج تدرج تفاصيله المعلمة prompt. الأدوات التي لا تتطلب مطالبة، مثل stability-upscale-fast، يتم استدعاؤها بدونها.
صورة إضافية تشير مناطقها الشفافة بالكامل إلى المكان الذي يجب تعديل الصورة فيه. يجب أن تكون ملف PNG صالحًا، وأقل من 50 MiB، ولها نفس أبعاد image.
بالنسبة لطلبات JSON، قد يكون mask أيضًا كائنًا يحتوي على واحد فقط من image_url أو file_id؛ يجب أن تأتي قيم file_id من /v1/files وتظل مرتبطة بنفس تكوين تعديل الصورة.
النموذج المستخدم لتعديلات الصور. استخدم gpt-image-2 لتعديلات GPT Image، أو نموذجًا حاليًا آخر لتعديل الصور يُرجع بواسطة GET /v1/models?recommended_for=image.
1عدد الصور المراد توليدها (1-10، يعتمد على النموذج).
حجم الصورة المُولدة. بالنسبة لـ 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.
طريقة إرجاع الصور: url أو b64_json.
- في حال الحذف: عندما يرجع النموذج بايتات الصورة، تكون كل صورة في
data[].b64_json، وتكون أيضًا فيdata[].urlعندما يقوم TokenLab بتخزينها. وعندما يرجع النموذج رابطًا، تكون كل صورة فيdata[].url. url: تكون كل صورة فيdata[].urlفقط.b64_json: تكون كل صورة فيdata[].b64_jsonفقط كبيانات Base64.
الروابط هي عناوين URL لنتائج الوسائط في TokenLab. تظل صالحة لمدة 30 يومًا. راجع الاحتفاظ بالبيانات.
falseاضبطه على true لإرجاع مهمة قبل أن تصبح الصورة النهائية جاهزة. فقط النماذج التي تدرج async ضمن معلماتها المدعومة تقبله، على سبيل المثال gpt-image-2؛ لأي نموذج آخر يرجع الطلب 400 unsupported_async_mode. تُرجع التعديلات غير المتزامنة المكتملة عناوين URL بغض النظر عن response_format المطلوب؛ استخدم الطلبات المتزامنة عندما تحتاج إلى b64_json.
معرف فريد يمثل المستخدم النهائي لأغراض مراقبة إساءة الاستخدام.
الاستجابة
طابع زمني بتنسيق Unix لوقت إنشاء الصور.
مصفوفة من الصور المُولدة.
يحتوي كل كائن على:
url(string): عنوان URL لنتيجة الوسائط في TokenLab للصورة المعدلة، صالح لمدة 30 يومًا. غير موجود عندما يكونresponse_formatهوb64_json. عند حذفresponse_format، يكون غير موجود إذا تعذر على TokenLab تخزين الصورة.b64_json(string): بيانات الصورة بتنسيق Base64. موجود عندما يكونresponse_formatهوb64_json، أو عند حذفه وإرجاع النموذج لبايتات الصورة.
أعداد الـ Tokens (input_tokens وoutput_tokens وtotal_tokens وتفاصيلها) للنماذج المسعرة بالـ Token مثل gpt-image-2، عند توفرها.
استجابة المهمة غير المتزامنة
اضبط async: true على نموذج يدعم ذلك لإنشاء مهمة بدلاً من انتظار الصورة المعدلة في الطلب. تتضمن الاستجابة status: "pending" وtask_id وpoll_url. استطلع /v1/tasks/{task_id} حتى تصل المهمة إلى completed أو failed.
تُرجع مهام التعديل غير المتزامنة عناوين URL للصور النهائية فقط. إذا كنت بحاجة إلى بيانات الصورة الخام بتنسيق 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"الاستجابة
{
"created": 1706000000,
"data": [
{
"url": "https://..."
}
]
}ملاحظات
يتم إرجاع حالات فشل جلب الصور البعيدة كأخطاء في المدخلات قبل بدء التوليد. تؤدي عناوين URL غير القابلة للوصول، والمهلات، واستجابات 403/404، والمضيفين الداخليين/الخاصين، وبيانات الاعتماد أو الـ fragments في عنوان URL، والمحتوى غير الصوري، والتنسيقات غير المدعومة، وانتهاكات حدود الحجم إلى إرجاع 400 أو 413 وتحديد مدخل image_url / image_urls[n]. الكود هو invalid_image_url، أو unsupported_image_content_type، أو too_many_images، أو مع 413، image_too_large أو image_input_too_large. بالنسبة للأصول الخاصة أو المحمية برؤوس (headers)، قم برفع ملفات image عبر multipart مباشرةً أو أنشئ مراجع /v1/files.
أرسل ترويسة Idempotency-Key لإعادة محاولة الطلب بأمان بعد انتهاء المهلة؛ راجع إعادة المحاولة بأمان باستخدام مفتاح idempotency.
يقوم النموذج Hy Image 3.5 Preview بتعديل صورة مرجعية بناءً على تعليمات مكتوبة. وهو يقبل فقط size بالقيمة 1024x1024 وn بالقيمة 1:
{
"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 مصادقة مفتاح API. قم بإنشاء أو إدارة مفاتيح API في Dashboard > API > API Keys.
الموضع: header
الترويسات
سياسة التسليم لكل طلب. تتجاوز إعدادات API key و Workspace الافتراضية. يحاول النظام تلقائياً استخدام TokenLab Verified أولاً، وقد ينتقل مرة واحدة إلى Official فقط قبل المخرجات، أو قبول الطلب، أو إنشاء مورد دائم.
القيم المتاحة
- "auto"
- "verified"
- "official"
مفتاح اختياري يجعل طلب الصورة آمناً لإعادة المحاولة إذا قام الطلب بإنشاء مهمة. أرسل قيمة فريدة جديدة، مثل UUID، لكل طلب. إعادة المحاولة بنفس المفتاح ونفس نص الطلب تُرجع تلك المهمة ولا تقوم بإنشاء أو إرسال أو احتساب تكلفة مهمة ثانية. بالنسبة للطلب الذي يُرجع الصورة مباشرة، قد تُرجع إعادة المحاولة بنفس المفتاح حالة المهمة بدلاً من الصورة، أو تُرجع 409 مع idempotent_response_not_replayable. يتم رفض نص الطلب المختلف الذي يستخدم مفتاحاً تم قبوله مسبقاً؛ ولا يوجد ضمان لرمز الحالة أو رمز الخطأ في هذه الحالة. يتم تجاهل المفتاح الذي يتجاوز 255 حرفاً، وعندها لا يتمتع الطلب بحماية idempotency. راجع إعادة المحاولة بأمان باستخدام مفتاح idempotency.
1 <= length <= 255الاستجابة
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json