ولّد تصاور بـ GPT Image 2.5 عبر API ديال APIMart

شنو كيوفّر هاد المشروع

معرض مطالبات image2.5 هو مجموعة عملية فيها 12 مطالبة دازو عبر GPT Image 2.5 وتنشرو مع الصور الناتجة عليها. كل وصفة كتسجّل المطالبة، نسخة النموذج، نسبة الأبعاد، والنتيجة، وهاد الشي كيسهّل تقييم المطالبة قبل ما تكيّفها مع التطبيق ديالك.

الأمثلة كتستعمل نقطة النهاية المتوافقة مع OpenAI ديال APIMart فـ https://api.apimart.ai/v1. المسار المرحَّل غير متزامن: التطبيق ديالك كيرسل طلب صورة، كيتوصل بمعرّف المهمة، كيتحقق من نقطة نهاية المهمة، وكيحمّل الصورة من بعد ما كتكمّل المعالجة.

أهم المزايا

• مسار توليد متوافق مع OpenAI: الطلبات كتمشي لـ POST /v1/images/generations.
• جوج نسخ مرحَّلة: استعمل version: "flare" للتوليد اليومي، ولا version: "sunburst" للتحرير والخدمة المعتمدة على المراجع.
• مستويات متعددة للإخراج: اختار 1K أو 2K أو 4K.
• تأطير مرن: استعمل auto ولا وحدة من عشر نسب أبعاد مدعومة، بما فيها 1:1 و16:9 و9:16 و4:3.
• إخراج دفعي: طلب من صورة وحدة حتى لأربع صور باستعمال n.
• دعم الصور المرجعية: قدّم حتى لـ 16 رابط URL ولا data URL فـ image_urls.
• احتساب تكلفة كل طلب: بيانات المهمة المكتملة كتضم cost وcredits_cost.
• إعادة المحاولة بشكل idempotent: الـ API كيقبل ترويسة Idempotency-Key باش يعاون يمنع تكرار الخدمة ملي كتعاود نفس الإرسال.

اختار مسار النموذج الصحيح

APIMart كيوفّر مسارات مرحَّلة ورسمية لـ GPT Image 2.5. حقول الطلب وطريقة الفوترة مختلفة بيناتهم، لذلك اختار المسار قبل ما تكتب التكامل ديالك.

المسار المرحَّل المحسوب لكل صورة

عيّن model لـ gpt-image-2.5-ext وزيد إما version: "flare" ولا version: "sunburst". هادا هو المسار المستعمل فالأمثلة ديال المعرض، وكتتحسب الفوترة ديالو على كل صورة موصّلة.

• flare: مناسب للتوليدات اليومية والمسودات الدفعية.
• sunburst: مناسب للتحرير الدقيق وللخدمات اللي خاصها تحافظ على المراجع أو العناصر أو اللوغوهات أو تسميات المنتجات.

المسار الرسمي المفوتر بالتوكنات

استعمل gpt-image-2.5-flare ولا gpt-image-2.5-sunburst مباشرة. ما تصيفطش حقل version مع هاد معرّفات النماذج. المسار الرسمي كتتحسب الفوترة ديالو بالتوكنات، وكيدعم سلّم الجودة من low حتى لـ max، وزيد عليه أبعاد البكسلات الدقيقة.

ما تخلطش بين صيغ المسارات. الاسم المستعار gpt-image-2.5-ext كيحتاج محدد نسخة، أما معرّفات النماذج الرسمية فما خاصهاش هاد المحدد.

التثبيت والإعداد

1. صايب الحساب ومَوّلو

جيب مفتاح API من صفحة مفاتيح APIMart. حسب المستودع، الخدمة ما فيهاش حصة مجانية وكتدعم التعبئة ابتداءً من $1.

2. خزّن المفتاح فمتغير بيئي

export APIMART_API_KEY="your-api-key"

تجنب تحط المفتاح مباشرة فكود التطبيق ولا ترفعو لنظام التحكم فالإصدارات.

3. ثبّت الاعتمادية ديال Python

مثال Python كيستعمل الحزمة الخارجية requests.

python -m pip install requests

إلى فضّلتي curl، تأكد باللي curl ومولّد UUID بحال uuidgen متوفرين فـ shell ديالك.

دير أول طلب صورة باستعمال curl

الطلب التالي كينشئ صورة مربعة بجودة 1K باستعمال النسخة المرحَّلة flare:

IDEMPOTENCY_KEY="$(uuidgen)"
curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header "Authorization: Bearer $APIMART_API_KEY" \
  --header "Content-Type: application/json" \
  --header "X-APIMart-Response-Version: 2026-07-27" \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --data '{
    "model": "gpt-image-2.5-ext",
    "version": "flare",
    "prompt": "ركن قراءة دافئ حدّ نافذة فنهار شتا، مصباح طاولة دافئ، وإضاءة سينمائية",
    "size": "1:1",
    "resolution": "1K",
    "n": 1
  }'

الإرسال الناجح كيرجع HTTP 202. قرا معرّف المهمة من data.id ولا استعمل data.poll_url اللي ترجع.

تحقق من المهمة

curl --request GET \
  --url "https://api.apimart.ai/v1/tasks/TASK_ID" \
  --header "Authorization: Bearer $APIMART_API_KEY" \
  --header "X-APIMart-Response-Version: 2026-07-27"

المهمة كتدوز غالباً من pending لـ processing، ومن بعد كتسالي إما بـ completed ولا failed. ملي كتكمّل، جيب الروابط المولّدة من result.images[].url.

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

بني عميلاً كاملاً بـ Python

هاد المثال كيرسل طلب واحد، كيتحقق من أخطاء HTTP، كيدير التحقق كل خمس ثواني، وكيرجع سجل المهمة المكتملة. وكيصايب مفتاح idempotency جديد مع كل توليد جديد.

import os
import time
import uuid
import requests

BASE_URL = "https://api.apimart.ai/v1"
API_KEY = os.environ["APIMART_API_KEY"]

COMMON_HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
    "X-APIMart-Response-Version": "2026-07-27",
}

def generate_image(prompt, version="flare", resolution="1K", size="1:1"):
    submit_headers = {
        **COMMON_HEADERS,
        "Idempotency-Key": str(uuid.uuid4()),
    }

    response = requests.post(
        f"{BASE_URL}/images/generations",
        headers=submit_headers,
        timeout=60,
        json={
            "model": "gpt-image-2.5-ext",
            "version": version,
            "prompt": prompt,
            "size": size,
            "resolution": resolution,
            "n": 1,
        },
    )
    response.raise_for_status()
    task_id = response.json()["data"]["id"]

    while True:
        poll_response = requests.get(
            f"{BASE_URL}/tasks/{task_id}",
            headers=COMMON_HEADERS,
            timeout=60,
        )
        poll_response.raise_for_status()
        task = poll_response.json()["data"]

        if task["status"] == "completed":
            return task
        if task["status"] == "failed":
            raise RuntimeError(f"Generation failed: {task}")

        time.sleep(5)

result = generate_image(
    "Studio product hero of a matte ceramic espresso cup on a warm stone pedestal, soft window light, 85mm lens look, minimal beige backdrop, crisp shadow"
)

print("Cost:", result.get("cost"))
for image in result["result"]["images"]:
    print("Image URL:", image["url"])
    print("Expires at:", image.get("expires_at"))

عاود المحاولة بأمان

إلى سالات مهلة الإرسال ولا وصلتي لرد قابل لإعادة المحاولة، صيفط نفس الطلب المنطقي من جديد بنفس Idempotency-Key. استعمل مفتاح جديد ملي كتكون باغي تنشئ صورة جديدة عن قصد. وإلى خاصك تعاود تنشئ مهمة مكتملة حيث تبدل المصدر ولا المرجع ديالها، استعمل حتى هو مفتاح جديد.

فهم الحقول الرئيسية فالطلب

• model: إجباري؛ استعمل gpt-image-2.5-ext فالمسار المرحَّل.
• version: flare ولا sunburst؛ القيمة الافتراضية هي flare.
• prompt: إجباري وخصّو يحتوي على نص ماشي غير المسافات.
• resolution: 1K ولا 2K ولا 4K؛ القيمة الافتراضية هي 1K.
• size: القيمة الافتراضية هي auto. النسب المدعومة هي 1:1 و16:9 و9:16 و4:3 و3:4 و3:2 و2:3 و5:4 و4:5 و21:9.
• n: عدد الصور، من وحدة حتى الربعة فالمسار المرحَّل.
• image_urls: مصفوفة اختيارية فيها حتى لـ16 رابط ديال الصور ولا data URLs.

كتب أوامر أكثر موثوقية

المعرض كيتعامل مع الأمر بحال موجز إنتاج مختصر، ماشي بحال لائحة ديال صفات عامة. البنية المفيدة كتكون: الموضوع، المادة، الإضاءة، التأطير ولا العدسة، واللمسة النهائية.

1. سمّي الموضوع: حدّد العنصر الرئيسي، الشخص، المشهد، ولا البيئة.
2. حدّد المواد الفيزيائية: استعمل عبارات بحال matte ceramic ولا frosted glass ولا clay render.
3. ضبط الإضاءة: وصف ضو الشراجم الناعم، ضو طبيعي جانبي، إضاءة استوديو عالية، ولا ضو خلفي درامي.
4. ثبّت التأطير: ذكر تكوين متمركز، تصوير مسطّح من الفوق، تكوين سينمائي واسع، ولا أي توزيع بغيتي.
5. زيد لغة العدسات: مصطلحات بحال 85mm و24mm وmacro وfocus stacked تقدر تعاون فالتوجيه ديال المنظور والتفاصيل.
6. اختار اللمسة النهائية: عبارات بحال تفاصيل تصويرية، تصوير تجاري للمنتجات، ولا حواف فيكتور واضحة كتتحكم فالمعالجة البصرية.

مثلاً:

Cosmetics packshot of a frosted glass bottle with amber serum,
water droplets on the surface, seamless pale pink backdrop,
high detail commercial product photography

استعمل الصور المرجعية

فالأعمال اللي فيها تحويل من صورة لصورة ولا اللي مبنية على مرجع، زيد مصفوفة image_urls فالطلب المرحَّل. المسار كيقبل حتى لـ16 مرجع.

{
  "model": "gpt-image-2.5-ext",
  "version": "sunburst",
  "prompt": "Preserve the product and label, replace the background with soft off-white, and add a natural cast shadow",
  "image_urls": [
    "https://example.com/product-reference.jpg"
  ],
  "size": "1:1",
  "resolution": "2K",
  "n": 1
}

استعمل روابط مرجعية مستقرة ويمكن الولوج ليها. إلى فشلات المهمة حيث سالات صلاحية رابط مرجعي، عاود استضافة الصورة وصيفط مهمة جديدة بمفتاح idempotency جديد.

عيّط للمسار الرسمي

المسار الرسمي كيستعمل معرّف مباشر للنموذج وإعداد quality عوض محدد version ديال المسار المرحَّل.

curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header "Authorization: Bearer $APIMART_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "gpt-image-2.5-sunburst",
    "prompt": "Preserve the product label, replace the background with soft off-white, add a natural cast shadow",
    "size": "1:1",
    "resolution": "1k",
    "quality": "high",
    "n": 1
  }'

شوف التوثيق الرسمي ديال المسار والتوثيق ديال المسار المُرحَّل باش تعرف تفاصيل الحقول الحالية.

نصائح متقدمة للإنتاج

فرّق بين الإرسال والمعالجة

خزّن مُعرّف المهمة اللي رجع فـطابور ولا فقاعدة بيانات، بلا ما تخلي طلب الويب محلول. يقدر عامل خدام فالخلفية يراقب المهام اللي ما كملاتش ويحفظ النتائج اللي كملات.

استعمل فترات مراقبة معتدلة

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

سجّل التكاليف الفعلية

حفظ cost ولا credits_cost من كل مهمة سالات. هاد الشي كيعطيك سجل ديال المصاريف لكل استدعاء، بلا ما تعتمد غير على التقديرات.

الـREADME كيشير لثمن مُلاحظ فالمسار المُرحَّل قدره $0.0085 لكل صورة 1K توصّلات، و$0.014 لـ2K، و$0.021 لـ4K flare. ثمن 4K sunburst ما كانش محدد فالجدول. هاد الأرقام تسجلات فـشتنبر 2026، لذلك راجع الثمن الحالي قبل ما تحدد الميزانية ولا توسّع الاستعمال.

حمّل النتائج فوراً

ما تعتبرش result.images[].url تخزين دائم. حمّل الملف قبل expires_at، ومن بعد نقلو لتخزين كتتحكم فيه التطبيق ديالك.

بدا بشوية قبل التوسّع

جرّب الـprompt بـ1K وn: 1. زِد الدقة ولا طلب مخرجات متعددة غير من بعد ما يستقرّ الموضوع والتركيب والأسلوب.

طابق نسبة الأبعاد مع الوجهة

• 1:1 للأيقونات، وبطاقات المنتجات، والأصول الاجتماعية المربعة.
• 16:9 للمشاهد السينمائية، ولوحات المعلومات، ورؤوس العروض التقديمية.
• 9:16 للتصاميم العمودية ديال الهاتف والسوشيال ميديا.
• 4:3 للرسومات التوضيحية التحريرية وتصوير الماكلة.
• 3:4 للبورتريهات وتركيبات الموضة.

حلّ المشاكل

• 401 ولا مفتاح API غير صالح: عاود نسخ المفتاح وتأكد ما فيهش مسافات ولا محارف ديال السطر الجديد. خاص الهيدر يستعمل Authorization: Bearer $APIMART_API_KEY.
• خطأ فالرصيد ولا الكريدي: زِد الفلوس للحساب؛ المستودع كيقول ما كاين حتى حصة مجانية احتياطية.
• استجابة 429: نقص التزامن، زِد مدة الانتظار، وعاود نفس الإرسال بنفس مفتاح منع التكرار.
• 400 ولا الموديل ما تلقاش: تأكد أن gpt-image-2.5-ext فيه نسخة، وأن معرّفات الموديلات الرسمية المباشرة ما فيهاش.
• حالة المهمة هي failed: شوف واش الـprompt ترفض ولا سالات صلاحية رابط مرجعي. صحّح الإدخال وصيفط مهمة جديدة بمفتاح جديد.
• رابط المخرج ما بقاش خدام: غالباً سالات صلاحية الرابط المؤقت. من دابا فصاعداً، خاصك تحمّل المخرجات اللي كملات بسرعة.

الخلاصة

كتبيّن Image2.5 Prompt Gallery سيرورة قابلة للتكرار لإنشاء الأصول بـGPT Image 2.5: اختار المسار الصحيح، كتب prompt بأسلوب مناسب للإنتاج، صيفط الطلب غير المتزامن، راقب مُعرّف المهمة، سجّل التكلفة المبلّغ عليها، وحمّل النتيجة قبل ما تسالي صلاحيتها. بدا بصورة وحدة 1K، تأكد من الجودة والفوترة، ومن بعد وسّع الاستعمال لدقات أعلى، أو دفعات، أو سيرورات sunburst مبنية على المراجع.