نقل تكامل الصور إلى SeedRouter

يتطلّب نقل واجهة صور برمجية إلى SeedRouter فحص عقد الطلب والاستجابة، لا مجرد استبدال مفتاح الواجهة والعنوان الأساسي. فـ GPT Image 2 يستخدم حقول توليد الصور المألوفة، لكن الإرسال يعيد معرّف مهمة. وعلى تطبيقك أن يحفظ ذلك المعرّف، ويستطلع الحالة حتى الاكتمال، ثم يقرأ روابط الصور الجاهزة.

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

أي الافتراضات يجب أن تتغيّر؟

حدّد الشيفرة التي تحوّل طلب صورة إلى ملف قابل للاستخدام. قد تكون اليوم تتوقّع صورة في الاستجابة الأولى، أو تفكّ ترميز حقل base64، أو ترفع الملف بصيغة multipart. ويجب فحص كل افتراض من هذه على حدة بمقابلته مع مرجع GPT Image 2 في SeedRouter.

لهذا فإن استدعاءً متزامنًا لمكتبة صور ليس بديلًا مباشرًا، حتى لو قبِل عنوانًا أساسيًا قابلًا للتهيئة. احتفظ بإعدادات النموذج التي ما زلت تحتاجها، لكن عدّل شيفرة التطبيق التي تنتظر النتيجة وتتعامل معها.

طابِق حقول الطلب قبل نقل الشيفرة

ابدأ بـ model وprompt وsize وquality وn. واستخدم gpt-image-2 معرّفًا للنموذج. أرسل أبعادًا صريحة مثل 1024x1024 أو استخدم auto؛ ولا تنقل حقل resolution منفصلًا ولا تضع نسبة أبعاد نصية مكان الحجم.

يفيد إبقاء وثيقة OpenAPI الخاصة بـ SeedRouter مفتوحة أثناء المراجعة. قارن الحقول التي يرسلها تطبيقك فعلًا، بما في ذلك القيم التي تضيفها المكتبة، بدل فحص الوسائط الظاهرة عند موضع الاستدعاء فقط. فالحقول غير المعروفة تُرفَض.

في هذا النموذج، ليست style ولا response_format ولا input_fidelity القابل للضبط حقول طلب مقبولة. احذف هذه الافتراضات بدل إخفائها داخل كائن خيارات عام. كما لا يدعم الطلب stream ولا partial_images؛ فحالة المهمة هي وسيلة هذا التكامل للإبلاغ عن التقدّم.

لإعدادات المخرجات تبعيات فيما بينها. فإذا طلبت شفافية، فاختر PNG. وأرسل output_compression مع JPEG فقط لا مع PNG. وقيمة الضغط صفر قيمة صالحة، فتجنّب فحصًا منطقيًا يستبدلها بقيمة افتراضية. هذه تفاصيل صغيرة لن يمرّ بها طلب أساسي ناجح.

استبدل افتراض الاستجابة المتزامنة

يرسل مثال Node.js التالي طلبًا واحدًا ويطبع معرّف مهمته. اضبط SEEDROUTER_API_KEY على الخادم؛ ولا تضع المفتاح أبدًا في شيفرة المتصفح ولا في متغير بيئة علني.

const response = await fetch('https://api.seedrouter.ai/v1/images/generations', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SEEDROUTER_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-image-2',
    prompt: 'A cobalt-blue ceramic mug on a pale gray tabletop.',
    size: '1024x1024',
    quality: 'low',
    n: 1,
  }),
  signal: AbortSignal.timeout(60000),
});
const task = await response.json();
if (!response.ok) {
  // Preserve a task reference if one accompanies an uncertain submission.
  if (typeof task.id === 'string') console.log('Task reference:', task.id);
  throw new Error(`Submission needs review: HTTP ${response.status}`);
}
if (typeof task.id !== 'string' || !task.id) throw new Error('Missing task ID.');
console.log(task.id); // Persist this ID with your application's image record.

طباعة المعرّف تكفي لاختبار يدوي سريع. أما في التطبيق فاحفظه قبل إعادة التحكّم إلى المستخدم. عندها يبقى سجل الصورة في حالة انتظار بينما ينتقل المستخدم إلى مكان آخر، ويستطيع فحص لاحق استرجاع النتيجة.

استخدم GET https://api.seedrouter.ai/v1/tasks/{id} بترويسة التفويض نفسها لمتابعة التقدّم. وعند completed اقرأ output.data[].url. وعند failed عالج الخطأ الموثّق واعرض حالة إخفاق مناسبة. وللاطلاع على مثال قابل للتشغيل يحفظ التقدّم، راجع الإرسال على دفعات والاستطلاع.

لا تُرفق مفتاح الواجهة بطلب تنزيل الصورة. فالتفويض يخصّ استدعاء واجهة المهام، لا عملية جلب منفصلة لرابط ملف مُعاد.

انقل المراجع والأقنعة إلى مدخلات عبر روابط

يحتاج أي مسار عمل قائم على ملفات محلية خطوة تحضير إضافية: أتِح الصورة المرجعية على رابط HTTP(S) يمكن الوصول إليه وتتحكّم أنت فيه. ومرّرها بالشكل images: [{"image_url": "https://example.com/reference.png"}] مع استبدال ذلك العنوان بعنوانك. ولا ترسل مسار ملف ولا رابط blob: ولا رابط بيانات base64 ولا معرّف Files ID.

تحقّق من أن الرابط يعمل من دون ملفات تعريف ارتباط تسجيل الدخول في متصفحك. فالرابط الذي لا يُفتح إلا داخل جلستك المسجَّلة ليس مرجعًا صالحًا لهذا الطلب. وأبقِ الصورة متاحة ما دامت المهمة قيد المعالجة؛ ولا تسحب صلاحية الوصول فور الإرسال.

يأخذ القناع الشكل mask: {"image_url": "https://example.com/mask.png"} ويشترط وجود صور مرجعية. ويجب أن يطابق أبعاد الصورة المرجعية الأولى. وراجع جميع قيود مدخلات الوسائط قبل نقل مسار تحرير قائم، ولا سيما صيغ الملفات وأحجامها.

ماذا يجب أن يغطّي اختبار قبول النقل؟

اختبر السلوك الذي يعتمد عليه تطبيقك، بما في ذلك الانقطاع. فصورة ناجحة واحدة لا تثبت سوى أن طلبًا واحدًا نجح. وهي لا تثبت أن حالة الانتظار تصمد أمام إعادة تحميل الصفحة، ولا أن إخفاق التنزيل لن يؤدي إلى توليد مكرّر.

• أرسل طلبًا نصيًا فقط واحفظ المعرّف المُعاد قبل بدء الاستطلاع.
• أوقف الاستطلاع ثم أعد تشغيله بالمعرّف نفسه وتأكّد من عدم حدوث أي طلب POST إضافي.
• عالج processing وcompleted وfailed بوصفها حالات متمايزة.
• نزّل صورة مكتملة من دون إرسال ترويسة تفويض الواجهة.
• جرّب تعديلًا بصورة مرجعية عبر رابط متاح، ثم افحص معالجة الخطأ مع رابط غير متاح.
• تحقّق من الحقول الاختيارية، بما فيها ضغط بقيمة صفر، وفق المخطط المنشور.
• أكّد أن خصومات الحساب تُقرأ من سجل الاستخدام لا من حقل تكلفة متخيَّل في استجابة المهمة.

استخدم استجابات محاكاة لاختبارات الإخفاق وانتهاء المهلة القابلة للتكرار. ولا تُجرِ اختبارًا حيًّا صغيرًا ومقصودًا إلا بعد اجتياز تلك الفحوص؛ فعمليات التوليد الحقيقية تستهلك الرصيد. وإذا كانت نتيجة الإرسال غير مؤكّدة، فتحقّق قبل إعادة المحاولة. فاستثناء محلي ليس دليلًا على أن أي مهمة لم تُقبَل.

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

هل أستطيع الاحتفاظ بمطالباتي الحالية؟

نعم، كنقطة انطلاق، ما دامت تستوفي قيود الطلب. واحتفظ ببضع مطالبات ممثّلة لغرض المقارنة، لكن لا تتوقّع صورًا متطابقة من عمليات توليد متكرّرة.

هل أحتاج مكتبة عميل جديدة؟

ليس لأمثلة هذه المقالة. فطلبات HTTP المعتادة كافية. وأي عميل تختاره يجب أن يتولّى إرسال المهمة واستطلاعها بدل انتظار صورة جاهزة فورًا.

أين أجد التكلفة النهائية؟

في سجل استخدام الحساب. وقد تتضمّن المهمة المكتملة استهلاك التوكنات، لكن استجابتها العلنية لا تحوي حقل تكلفة. ويتناول دليل الأسعار مسألة التقدير.

أكمل النقل عند حدود التطبيق

يكتمل نقل واجهة الصور حين يتعامل التطبيق مع دورة حياة النتيجة كاملةً: مهمة مقبولة، وحالة انتظار، ومخرجات جاهزة، وتنزيل، وإخفاق. اجعل التغيير الأول صغيرًا، واختبر حالات الانقطاع، ولا تنقل بقية الطلبات إلا بعد التحقّق من افتراضات مدخلاتها ومخرجاتها.