ولّد وحرّر الصور بـ GPT-Image-2.5 عبر APIMart

شنو كيدير بوّابة image2.5 APIMart

بوّابة image2.5 كتوفر الولوج لعائلة GPT Image 2.5 ديال التوليد والتعديل عبر واجهة APIMart API. بلا ما تدمج بيانات اعتماد وتنسيق طلبات مختلف لكل نموذج صور، كتستعمل عنوان أساسي واحد، ورمز bearer واحد، ونقطة النهاية /v1/images/generations المتوافقة مع أسلوب OpenAI.

الـAPI خدام بطريقة غير متزامنة. طلب التوليد كيرجع معرّف مهمة بدل صورة مباشرة. من بعد، التطبيق ديالك كيبقى كيسوّل نقطة نهاية المهمة حتى تكمل المعالجة ولا تفشل. المهام الناجحة فيها روابط مؤقتة للنتائج، وخصك تحمّل الصور قبل ما تسالي صلاحيتها.

APIMart هي الخدمة الموثقة فالمستودع. نقطة النهاية gpt-image-2.5-ext هي مسار ترحيل تابع لجهة خارجية، بينما gpt-image-2.5-flare وgpt-image-2.5-sunburst هما المساران اللي كيتحاسبو بالتوكنات. تأكد من الحدود والأسعار الحالية قبل أي تشغيل فالإنتاج.

المزايا الرئيسية

• عنوان أساسي واحد للـAPI: الطلبات كتستعمل https://api.apimart.ai/v1.
• جوج نسخ ديال النموذج: اختار Flare للتوليد اليومي والمسودات المجمعة، ولا Sunburst للدقة فالتعديل والأصول الموجهة للإنتاج.
• جوج طرق للفوترة: المسار المرحّل كيتحاسب على كل صورة مسلّمة، بينما المسارات الرسمية كتستعمل الفوترة حسب التوكنات.
• معالجة غير متزامنة: صيفط الطلب وسوّل GET /v1/tasks/{task_id} على التقدم.
• مستويات متعددة للنتيجة: المسار المرحّل كيدعم 1K و2K و4K.
• تركيبات مرنة: اختار من بين عشرة نسب للأبعاد ولا استعمل auto.
• توليد معتمد على المراجع: زوّد حتى لـ16 إدخال فـimage_urls لأعمال تحويل الصور أو تعديلها.
• دفعات صغيرة: طلب بين صورة وحدة وأربع صور مسلّمة باستعمال n فالمسار المرحّل.

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

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

استعمل model: "gpt-image-2.5-ext" إلا بغيتي فوترة ثابتة على كل صورة مسلّمة. اختار النسخة الأساسية باستعمال version: "flare" ولا version: "sunburst".

• flare موجه للتوليد بكميات كبيرة، والصور اليومية، والمسودات.
• sunburst موجه للتعديلات وأعمال الإنتاج المعتمدة على المراجع.

المستودع سجّل ثمن $0.0085 لكل صورة 1K مسلّمة للنسختين بجوج نهار 16 سبتمبر 2026. وسجّل حتى $0.014 لـ2K، و$0.021 لـ4K Flare، ونصح بالتحقق من الثمن الحالي لـ4K Sunburst. هاد الأرقام مرتبطة بتاريخ الملاحظة وماشي ضمانات دائمة.

المسارات الرسمية المحسوبة بالتوكنات

استعمل gpt-image-2.5-flare ولا gpt-image-2.5-sunburst مباشرة للفوترة حسب التوكنات. هاد المسارات ما فيهاش الحقل version وكتدعم سلم الجودة low وmedium وhigh وxhigh وmax. المسار الرسمي كيدعم حتى أبعاد البكسلات المضبوطة.

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

نطاق النتائج النموذجية

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

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

1. أنشئ مفتاح API

خذ مفتاح من صفحة مفاتيح API ديال APIMart. خزّنو فمتغير بيئي عوض ما تحطّو مباشرة فالكود المصدري.

export APIMART_API_KEY="your-api-key"

2. اختار عميل

cURL ما كيحتاج حتى اعتماد إضافي للمشروع غير تثبيت عادي من سطر الأوامر. بالنسبة لمثال Python، ثبّت حزمة requests:

python -m pip install requests

المستودع فيه حتى مثال JavaScript لـNode.js 18 ولا أحدث، فين fetch متوفر بشكل عام.

3. فهم رؤوس الطلب

صيفط مفتاح API فالرأس Authorization. أمثلة المسار المرحّل كتستعمل حتى رأس نسخة الاستجابة ومفتاح idempotency فريد.

• Authorization: Bearer $APIMART_API_KEY
• Content-Type: application/json
• X-APIMart-Response-Version: 2026-07-27
• Idempotency-Key: unique-request-value

عاود استعمل نفس مفتاح idempotency ملي كتعاود المحاولة لإرسال نفس الطلب. ولّد مفتاح جديد ملي كتكون باغي عن قصد مهمة جديدة لصورة جديدة.

الاستعمال الأساسي: ولّد صورة باستعمال cURL

الطلب التالي كيستعمل المسار المحسوب لكل صورة، كيختار Flare، وكيطلب صورة مربعة وحدة بجودة 1K:

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 اللي رجعات.

تفقّد المهمة

عوّض task_01EXAMPLE بمعرّف المهمة اللي رجع:

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

حالة المهمة كتدوز من pending وprocessing قبل ما توصل لـ completed ولا failed. والجواب يقدر يبيّن حتى progress وcost وcredits_cost. ملي تكمل، جيب رابط الصورة من result.images[].url وراجع expires_at.

مثال Python من البداية للنهاية

هاد المثال كيرسل صورة وحدة وكيشيّك على المهمة كل خمس ثواني حتى توصل لحالة نهائية:

import os
import time
import uuid
import requests

BASE_URL = "https://api.apimart.ai/v1"
COMMON_HEADERS = {
    "Authorization": f"Bearer {os.environ['APIMART_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,
        json={
            "model": "gpt-image-2.5-ext",
            "version": version,
            "prompt": prompt,
            "size": size,
            "resolution": resolution,
            "n": 1,
        },
        timeout=60,
    )
    response.raise_for_status()
    task_id = response.json()["data"]["id"]

    while True:
        task_response = requests.get(
            f"{BASE_URL}/tasks/{task_id}",
            headers=COMMON_HEADERS,
            timeout=60,
        )
        task_response.raise_for_status()
        task = task_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(
    "حديقة سماوية فالفجر، تصوير معماري",
    version="flare",
    resolution="1K",
    size="16:9",
)

for image in result["result"]["images"]:
    print(image["url"], image.get("expires_at"))

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

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

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

{
  "model": "gpt-image-2.5-ext",
  "version": "sunburst",
  "prompt": "خلي لاصقة المنتوج كيف ما هي، بدّل الخلفية لأبيض مائل للصفرة وناعم، وزِد ظل طبيعي",
  "image_urls": [
    "https://example.com/source-product.jpg"
  ],
  "size": "1:1",
  "resolution": "2K",
  "n": 1
}

Sunburst هو النوع اللي كيقترحو المستودع للدقة فالتعديل والخدمة المعتمدة على الصور المرجعية. استعمل روابط متاحة ولا روابط بيانات صحيحة، وخلي اللائحة داخل الحد الموثّق.

مرجع حقول الطلب للمسار المُحال

• 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: كيقبل عدد صحيح من 1 حتى لـ 4.
• image_urls: مصفوفة اختيارية فيها حتى لـ 16 رابط مرجعي ولا رابط بيانات.

استدعاء المسار اللي كيتحاسب بالتوكنات

المسار الرسمي كيستعمل نفس طريق التوليد، ولكن كيبدّل معرّف النموذج، كيحيد version، وكيزيد إعداد الجودة. هاد المثال كيختار Sunburst بجودة عالية:

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": "خلي لاصقة المنتوج كيف ما هي، بدّل الخلفية لأبيض مائل للصفرة وناعم، وزِد ظل طبيعي",
    "size": "1:1",
    "resolution": "1k",
    "quality": "high",
    "n": 1
  }'

رجع لـمرجع المسار الرسمي ومرجع المسار المُرحَّل باش تطّلع على التعريفات الحالية ديال الحقول.

نصائح متقدمة باش تدير تكاملات موثوقة

1. خلي إعادة المحاولات idempotent. حافظ على نفس مفتاح idempotency الأصلي إلا سالات مهلة الإرسال وما كنتيش متأكد واش تخلقات المهمة. مفتاح جديد يقدر يخلق عملية توليد أخرى كتتحسب عليك.
2. اعتبر التحقّق الدوري جزء عادي من سير العمل. تعامل مع الحالتين completed وfailed. بعد على التحقّق السريع بزاف؛ المثال اللي فالمستودع كيتسنى خمس ثواني بين كل عملية تحقّق.
3. استعمل رابط التحقّق اللي رجع ليك. الاستجابة فيها data.poll_url، وهاد الشي كيخليك ما تحتاجش تعاود تركّب endpoint ديال المهمة يدويّاً.
4. حمّل النتائج بسرعة. روابط الصور المولَّدة مؤقتة. نسخ كل نتيجة للتخزين ديالك قبل الوقت المحدد فـexpires_at.
5. سجّل التكلفة الفعلية. خزّن cost وcredits_cost من استجابة المهمة. بهاد الطريقة تقدر تقارن الفوترة اللي لاحظتيها مع الأسعار المنشورة.
6. تحقّق من التكلفة بطلب واحد مؤدى عليه. الأسعار والتوجيهات الترويجية يقدرو يتبدلو، لذلك دير اختبار صغير قبل ما تطلق batch كبير.
7. استعمل المسار المناسب. اختار المسار المُرحَّل إلا بغيتي فوترة متوقعة لكل صورة ودفعات حتى لأربع صور. واختار معرّف نموذج رسمي إلا كانت مستويات الجودة أو التحكم الدقيق فالبكسلات مهمّين.
8. بدّل بين النسخ بلا ما تعاود تكتب العميل. فالمسار المُرحَّل، بدّل غير version بين flare وsunburst.
9. حمي بيانات الدخول. خزن مفتاح API فمتغيرات البيئة ولا فمدير الأسرار، وما تعرّضوش أبداً فالكود اللي كيتنفذ فالمتصفح.

الخلاصة

بوابة الصور 2.5 ديال APIMart كتوفّر طريقة موحّدة للوصول لتوليد وتعديل GPT Image 2.5. بدا بـgpt-image-2.5-ext وFlare باش تحصل على توليد متوقع وبحجم كبير، وبدّل لـSunburst فالتعديل ولا فالخدمة اللي كتحتاج مراجع، واستعمل معرّفات النماذج الرسمية إلا كانت الفوترة حسب التوكنات والتحكمات الموسعة فالجودة أنسب للمهمة.

النمط الأساسي ديال التكامل بسيط: صيفط طلب الصورة، خزّن معرّف المهمة اللي رجع، دير التحقّق الدوري حتى تكمل، شوف التكلفة المصرّح بها، وحمّل كل نتيجة قبل ما تسالي صلاحية الرابط المؤقت ديالها. قبل ما توسّع الخدمة، راجع أسعار APIMart الحالية وتحقّق من المسار اللي اخترتيه بطلب صغير مؤدى عليه.