كيفية استخدام API gpt-image-2.5 (فلير وسانبيرست) مع Curl وبايثون و Node

أطلقت OpenAI إصدار ChatGPT Images 2.5 في 8 سبتمبر 2026، مع نموذجين جديدين لواجهة برمجة التطبيقات (API): gpt-image-2.5-flare وgpt-image-2.5-sunburst. يقع كلاهما خلف نفس نقاط النهاية مثل gpt-image-2، لذلك إذا اتبعت دليل API الخاص بـ gpt-image-2 الخاص بنا، فإن معظم التعليمات البرمجية الخاصة بك ستبقى بعد تبديل معرف النموذج. ما تغير هو سلم الجودة وكيف تسمح لك واجهة برمجة تطبيقات الاستجابات (Responses API) باختيار نموذج لكل استدعاء أداة.

يغطي هذا الدليل مسار المطور فقط: عمليات التوليد، والتعديلات متعددة الأجزاء مع صورة مرجعية وقناع، وأداة Responses API، والتدفق (streaming)، وقراءة usage للتكلفة الفعلية. لمعرفة ما يعنيه هذا الإصدار لمستخدمي ChatGPT، اقرأ نظرة عامة على ChatGPT Images 2.5؛ منشور إطلاق OpenAI يقدم إطار المنتج. كل رقم أدناه يأتي من وثائق OpenAI أو صفحة التسعير أو الآلة الحاسبة كما قرئت في 9 سبتمبر 2026.

نظرة عامة على واجهة برمجة تطبيقات gpt-image-2.5

تتطابق معدلات التوكن الواحد مع gpt-image-2؛ ولا تزال تكلفة الصورة الواحدة تتغير لأن عدد التوكنات لكل مستوى جودة قد تغير.

المتطلبات الأساسية

• حساب مطور OpenAI على مستوى مدفوع. تتطلب نقاط نهاية الصور المستوى 1 أو أعلى، مما يعني إضافة طريقة دفع؛ ولا يحتسب اشتراك ChatGPT. يغطي دليل مفتاح API الخاص بـ OpenAI الخاص بنا المفاتيح المحددة بالمشروع.
• حزمة تطوير البرامج (SDK) الرسمية لـ openai لـ Python أو Node.
• طريقة لمعاينة استجابات الصور. يطبع curl base64، وهو أمر مؤلم للتكرار؛ يعرض Apidog الصورة المفككة مباشرة، وينقل القسم الأخير سير العمل إلى هناك.

قم بتصدير المفتاح مرة واحدة:

export OPENAI_API_KEY="sk-proj-..."

توليد صورة باستخدام curl

استخدم Flare أولاً؛ تصفها صفحة نموذج OpenAI بأنها "الخيار الافتراضي لمعظم التطبيقات".

curl https://api.openai.com/v1/images/generations \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "Product photo of a matte black mechanical keyboard, studio lighting, no text",
    "size": "1536x1024",
    "quality": "medium",
    "output_format": "webp",
    "background": "transparent"
  }'

تحتوي الاستجابة على مصفوفة data بها b64_json واحد لكل صورة، بالإضافة إلى كائن usage يحتوي على input_tokens وoutput_tokens. احتفظ بـ usage؛ إنه إشارة التكلفة الدقيقة الوحيدة التي تحصل عليها. ملاحظات المعلمات من دليل توليد الصور: output_format افتراضياً هو png وتقول OpenAI "استخدام jpeg أسرع من png"؛ output_compression (0-100) ينطبق على jpeg وwebp فقط؛ background: "transparent" يفشل على jpeg.

بايثون: توليد ثم تعديل بصورة مرجعية

استدعاء SDK يعكس محتوى curl. قم بفك تشفير b64_json واكتب البايتات.

import base64
from openai import OpenAI

client = OpenAI()

gen = client.images.generate(
    model="gpt-image-2.5-flare",
    prompt="Clean API analytics dashboard mockup, dark theme, latency chart top right",
    size="1536x1024",
    quality="high",
    output_format="png",
)
open("dashboard.png", "wb").write(base64.b64decode(gen.data[0].b64_json))
print(gen.usage.output_tokens, "output tokens")

التعديلات هي حيث تبرز نماذج 2.5؛ يذكر منشور الإطلاق أنها "أفضل في تعديل ما طلبته فقط، مع الحفاظ على باقي التفاصيل كما هي"، وتضع OpenAI Sunburst للتحكم "الأكثر إحكامًا عبر التعديلات". نقطة نهاية التعديلات متعددة الأجزاء: صورة مرجعية، قناع اختياري، ومطالبة. حيث يكون القناع شفافًا، يعيد النموذج الرسم؛ وفي كل مكان آخر يحتفظ بالصورة الأصلية.

edit = client.images.edit(
    model="gpt-image-2.5-sunburst",
    image=open("dashboard.png", "rb"),
    mask=open("chart-area-mask.png", "rb"),
    prompt="Replace the latency chart with a bar chart of error rates per endpoint; keep everything else",
    size="1536x1024",
    quality="high",
)
open("dashboard-v2.png", "wb").write(base64.b64decode(edit.data[0].b64_json))
print(edit.usage.input_tokens, "input tokens (includes the reference image)")

احذف mask وسيقرر النموذج ما يجب تغييره من المطالبة وحدها. يتم فوترة الصورة المرجعية كتوكنات إدخال صورة بسعر 8 دولارات لكل مليون؛ لا تنشر OpenAI عدد توكنات الإدخال لكل صورة، لذا اقرأ usage.input_tokens.

Node و TypeScript: كتابة b64_json على القرص

import fs from "node:fs/promises";
import OpenAI from "openai";

const client = new OpenAI();

const res = await client.images.generate({
  model: "gpt-image-2.5-flare",
  prompt: "Hero image for API docs: floating JSON cards over a teal gradient, no text",
  size: "1536x1024",
  quality: "medium",
  output_format: "jpeg",
  output_compression: 80,
});

const b64 = res.data?.[0]?.b64_json;
if (!b64) throw new Error("no image returned");
await fs.writeFile("hero.jpg", Buffer.from(b64, "base64"));

ثبّت gpt-image-2.5-flare-2026-09-08 في الإنتاج للحفاظ على استقرار المخرجات بينما يتحرك الاسم المستعار.

واجهة برمجة تطبيقات الاستجابات (Responses API): توليد الصور كأداة

هنا، يقرأ نموذج رئيسي مطالبتك، ويراجعها، ويستدعي أداة image_generation. يمكنك اختيار نموذج الصورة عن طريق تعيين model داخل تعريف الأداة؛ يجب أن يكون model على المستوى الأعلى نموذجًا رئيسيًا، وتستخدم وثائق أداة OpenAI gpt-6-astra. يغطي دليل Responses API الخاص بنا شكل الطلب. يأخذ حقل action قيم auto (افتراضي)، generate، أو edit؛ قم بتعيين edit عند تمرير صورة مرجعية وترغب في تعديلها، وليس إعادة تفسيرها.

import base64

with open("product.png", "rb") as f:
    ref = base64.b64encode(f.read()).decode()

first = client.responses.create(
    model="gpt-6-astra",
    input=[{"role": "user", "content": [
        {"type": "input_text", "text": "Put this bottle on a white marble surface with soft daylight"},
        {"type": "input_image", "image_url": f"data:image/png;base64,{ref}"},
    ]}],
    tools=[{"type": "image_generation", "model": "gpt-image-2.5-sunburst", "action": "edit"}],
)
calls = [o for o in first.output if o.type == "image_generation_call"]
open("bottle-marble.png", "wb").write(base64.b64decode(calls[0].result))

second = client.responses.create(
    model="gpt-6-astra",
    previous_response_id=first.id,
    input="Same scene, but add a second bottle behind it, slightly out of focus",
    tools=[{"type": "image_generation", "model": "gpt-image-2.5-sunburst", "action": "edit"}],
)

المتابعة باستخدام previous_response_id تحافظ على الصورة الأولى في السياق، لذا فإن "المشهد نفسه" يتم حله دون إعادة تحميل الملف. يتم فوترة توكنات النموذج الرئيسي بالإضافة إلى توكنات الصورة، وتعني إعادة كتابة المطالبة أنه لا يمكنك إعادة إنتاج المخرجات من نص المطالبة وحده.

تدفق الصور الجزئية

تقبل كلتا واجهتي برمجة التطبيقات partial_images (من 0 إلى 3). تكلف كل صورة جزئية 100 توكن إخراج إضافي، لذا تضيف ثلاث صور 300 توكن، أو 0.009 دولار لكل صورة. الأمر يستحق العناء لواجهة مستخدم تعرض التقدم؛ ويعد إهدارًا في مهمة دفعية.

stream = client.images.generate(
    model="gpt-image-2.5-flare",
    prompt="Isometric illustration of an API gateway routing requests to three services",
    size="1024x1024",
    quality="medium",
    stream=True,
    partial_images=2,
)
for event in stream:
    if event.type.endswith("partial_image"):
        open(f"gateway-partial-{event.partial_image_index}.png", "wb").write(
            base64.b64decode(event.b64_json))
    elif event.type.endswith("completed"):
        open("gateway.png", "wb").write(base64.b64decode(event.b64_json))

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

قراءة الاستخدام وتحويل التوكنات إلى دولارات

تحذير OpenAI الخاص: "معدلات التوكن المتساوية لا تعني تكلفة متساوية لكل صورة: قد يختلف استهلاك التوكن حسب النموذج وإعداد الجودة." تقدم الآلة الحاسبة في دليل توليد الصور هذه التقديرات لتوكنات إخراج الصورة وحدها، بمعدل 30 دولارًا لكل مليون على صفحة التسعير:

لاحظ إعادة التسمية. يستخدم high في 2.5 1,756 توكن، وهي ميزانية medium القديمة في gpt-image-2؛ يستخدم max 7,024 توكن، وهي ميزانية high القديمة. حافظ على quality: "high" خلال عملية الترحيل وكل صورة ستصبح أرخص بحوالي 4 مرات بميزانية medium القديمة؛ بالنسبة لميزانية high القديمة، انتقل إلى max. يقدم مقارنة Flare vs Sunburst vs gpt-image-2 لدينا الحساب الشهري الكامل.

أرقام الآلة الحاسبة هي تقديرات. التكلفة الحقيقية تأتي من الاستجابة:

OUTPUT_RATE = 30 / 1_000_000  # دولار لكل توكن إخراج صورة
usd = gen.usage.output_tokens * OUTPUT_RATE
print(f"{gen.usage.output_tokens} tokens = ${usd:.4f}")

سجلها لكل طلب؛ وفقًا لـ OpenAI، يمكن أن ينتج حجم غير مربع أكبر عددًا أقل من التوكنات مقارنةً بحجم مربع أصغر. سؤال مفتوح واحد: علامة تبويب الدفعات (Batch) في صفحة التسعير تسرد gpt-image-2 فقط، لذا تعامل مع دعم Batch API لـ 2.5 على أنه غير مؤكد.

الأخطاء، حدود المعدل، والمهلات

• 429 حد المعدل. تراجع مع تذبذب واحترم Retry-After. لا تنشر صفحات نموذج 2.5 حدودًا لكل مستوى. للمرجعية، يعمل gpt-image-2 من المستوى 1 بمعدل 5 صور في الدقيقة و 100 ألف توكن في الدقيقة، ويتوسع إلى المستوى 5 بمعدل 250 صورة في الدقيقة و 8 ملايين توكن في الدقيقة.
• insufficient_quota. لا توجد أرصدة أو لا يزال في المستوى المجاني. أضف الفواتير؛ لا تعاود المحاولة.
• رفض الاعتدال. أدت المطالبة أو الصورة المرجعية إلى تشغيل الفلتر. أعد صياغة بدلاً من إعادة المحاولة؛ moderation: "low" يخفف العتبة.
• المهلات. توثق OpenAI أن "المطالبات المعقدة قد تستغرق ما يصل إلى دقيقتين للمعالجة". اضبط مهلات العميل أعلى من ذلك؛ يعمل Sunburst لفترة أطول من Flare عن قصد.

اختبار Flare و Sunburst جنبًا إلى جنب في Apidog

التكرار الطرفي على مطالبات الصور بطيء لأنه لا يمكنك رؤية المخرجات، وقيمة quality الخاطئة تكلف أموالاً حقيقية في كل إرسال. Apidog هو عميل واجهة برمجة تطبيقات ومنصة اختبار: يرسل الاستدعاءات ويتحقق من الاستجابات؛ وتقوم خوادم OpenAI بالمعالجة.

1. تخزين المفتاح مرة واحدة. أضف OPENAI_API_KEY كمتغير بيئة وارجع إليه كـ Bearer {{OPENAI_API_KEY}} في رأس التخويل؛ لا يصل المفتاح أبدًا إلى طلب محفوظ.
2. بيئتان، طلب واحد. أنشئ بيئات باسم flare وsunburst، لكل منهما متغير MODEL، وعيّن "model": "{{MODEL}}" في النص. قم بالتبديل، وأعد الإرسال، وقارن الصور وusage جنبًا إلى جنب. للتعديلات، استخدم نصًا من نوع form-data مع image وmask كحقول ملفات.
3. فك تشفير b64_json في معالج لاحق. يقوم نص برمجي قصير بسحب data[0].b64_json، وفك تشفيره، وحفظ الملف، بحيث ينتج كل إرسال صورة قابلة للعرض بجانب JSON الخام.
4. تأكيد التكلفة، ثم جدولتها. تأكد من أن usage.output_tokens يبقى ضمن الميزانية، على سبيل المثال 2,000 لتصيير high بحجم 1536x1024، وقم بتشغيل الطلب كاختبار تراجع موقوت. إذا قام شخص ما برفع الجودة إلى max أو إذا غيرت لقطة معينة عدد التوكنات، فسيفشل الاختبار قبل أن تأتي الفاتورة.

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

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

هل أحتاج إلى تغيير كود gpt-image-2 الخاص بي لاستخدام 2.5؟ قم بتبديل معرف النموذج وأعد التحقق من quality. نقاط النهاية، المصادقة، وشكل الاستجابة لم تتغير، ولكن high الآن يشير إلى ميزانية توكن أصغر. لا يزال دليل API الخاص بـ gpt-image-2 يغطي النموذج الأقدم.

Flare أم Sunburst لواجهة برمجة التطبيقات؟ ابدأ بـ Flare. تضعها OpenAI كخيار افتراضي بـ "تأخر زمني أقل بنسبة 50٪" من gpt-image-2 بنفس سعر التوكن الواحد. انتقل إلى Sunburst عندما تكون دقة التعديل أكثر أهمية من السرعة، مثل صور المنتجات المبنية من صور مرجعية. يتشاركان نفس عدد التوكنات في الآلة الحاسبة، لذا المقايضة هي الوقت، وليس المال.

هل يمكنني استخدام هذه النماذج في إكمال المحادثات (Chat Completions)؟ لا. يعيش توليد الصور في Image API وأداة image_generation الخاصة بـ Responses API. لا تعرضها إكمال المحادثات.

هل هناك طريقة مجانية لتجربة 2.5 عبر واجهة برمجة التطبيقات؟ لا يوجد مستوى API مجاني دائم، وتتطلب نقاط نهاية الصور المستوى 1. أرخص مسار حقيقي هو quality: "low" عند 196 توكن، أي حوالي 0.006 دولار لكل صورة بحجم 1024x1024. تطبيق المستهلك هو مسألة أخرى؛ راجع كيفية استخدام ChatGPT Images 2.5 مجانًا.

إلى أين نذهب بعد ذلك

ابدأ باستدعاء curl، وتأكد من usage.output_tokens مقابل جدول الآلة الحاسبة، ثم انقل الطلب إلى عميل حيث يمكنك رؤية الصورة. مقالة سيمون ويلسون تظهر كيف يحافظ Sunburst على الرسم البياني سليمًا مع إضافة موضوع؛ اختبر سلوك التعديل هذا على صورك المرجعية قبل الالتزام.