كيفية استخدام واجهة برمجة تطبيقات GPT-Image-2.6

تولّد واجهة GPT-Image-2.6 API الصور وتحرّرها من خلال نموذجين من OpenAI، هما gpt-image-2.6-flare وgpt-image-2.6-sunburst. أرسل طلبًا نصيًا (prompt) إلى POST /v1/images/generations مع مفتاح API الخاص بك، ثم فك ترميز b64_json من الاستجابة. يضيف الإصدار 2.6 وضع العلامات (markup) على الصور، وإخراج SVG وGIF، ومعامل complexity.

يغطي هذا الدليل المصادقة، وأول عملية توليد، وتحريرًا بالعلامات، وتصدير SVG، وإعدادات quality وcomplexity. يقتصر على الجديد فحسب، لذا اقرأ دليل gpt-image-2.5 API للاطلاع على البثّ (streaming) وأداة Responses API، واطّلع على شرح ChatGPT Images 2.6 للإصدار الكامل. أنشأنا كل طلب أدناه استنادًا إلى وثائق OpenAI بتاريخ 5 نوفمبر 2026. لم نجرّبها باستخدام مفتاح حقيقي، لذا اختبرها قبل أن تُطلق مشروعك.

نظرة سريعة على GPT-Image-2.6 API

الأسعار مأخوذة من صفحة أسعار OpenAI. يكلف كلا النموذجين المقدار نفسه لكل رمز، لذا اختر بناءً على السرعة ودقة التحرير.

Flare أم Sunburst: أي نموذج ينبغي أن تستدعيه؟

استدعِ Flare للتكرار السريع والتوليد اليومي. تقول OpenAI إنه يمكنه إرجاع صورة في غضون ست ثوانٍ عند جودة low، وإنه يحسّن التخطيط للملصقات وصور المنتجات. استدعِ Sunburst للأعمال التفصيلية والتحريرات المتكررة، حيث تدّعي OpenAI تناسقًا أفضل عند جودة medium أو high.

هذه ادعاءات OpenAI، وليست معايير مستقلة. يشرح مقارنتنا بين Flare وSunburst للإصدار 2.5 هذا التفريق.

المصادقة والإعداد

تحتاج إلى ثلاثة أشياء قبل أول استدعاء:

1. أنشئ مفتاح API في لوحة تحكم OpenAI وصدّره باسم OPENAI_API_KEY.
2. أكمل التحقق من مؤسسة API إذا كانت مؤسستك بحاجة إلى ذلك. تقول OpenAI إنه قد يكون عليك فعل ذلك قبل أن تتمكن من استخدام نماذج GPT Image.
3. ثبّت jq لأمثلة curl، أو حزمة openai للغة Python.

إذا كان تطبيقك يخدم مستخدمين أفرادًا، فأرسل أيضًا قيمة safety_identifier مُجزّأة لا تتجاوز 128 حرفًا. فهي تحل محل معامل user المهجور.

ولّد صورتك الأولى

يستخدم هذا الطلب Flare عند جودة low، وهي مناسبة للمسودات.

curl --fail-with-body --silent --show-error \
  https://api.openai.com/v1/images/generations \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.6-flare",
    "prompt": "A minimal poster for a developer meetup, with the words SHIP IT in bold type",
    "size": "1024x1536",
    "quality": "low",
    "complexity": "low"
  }' | jq -er '.data[0].b64_json' | base64 --decode > poster.png

الاستدعاء نفسه في Python:

import base64
from pathlib import Path
from openai import OpenAI

client = OpenAI()

result = client.images.generate(
    model="gpt-image-2.6-sunburst",
    prompt="A product shot of a ceramic mug on a walnut desk, soft morning light",
    size="1536x1024",
    quality="medium",
    extra_body={"complexity": "low"},
)

Path("mug.png").write_bytes(base64.b64decode(result.data[0].b64_json))

نمرّر complexity عبر extra_body كي لا يعتمد الاستدعاء على إتاحة إصدار SDK لديك له كوسيط مُسمّى. تُرجع نماذج GPT Image دائمًا base64، لذا لا ترسل response_format، ولا تبحث عن حقل url.

ينصّ دليل OpenAI على قراءة كائن usage في الاستجابة لقياس استخدام الرموز. لكن مرجع API يصف هذا الحقل بأنه خاص بـgpt-image-1 فقط، مع أن استجابة نموذجه تتضمنه، لذا تأكد من ظهوره في استجابات 2.6 لديك قبل أن تبني عليه تتبّع التكلفة.

حرّر صورة باستخدام العلامات (markup)

تخبر العلامات النموذج بمكان إجراء التغيير. ترسل الصورة الأصلية، وملف PNG شفافًا يحتوي على دوائرك أو رسوماتك، وطلبًا نصيًا يصف التحرير.

curl --fail-with-body --silent --show-error \
  https://api.openai.com/v1/images/edits \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.6-flare",
    "images": [{"image_url": "https://your-bucket.example/kitchen.png"}],
    "markup": {"image_url": "https://your-bucket.example/vase-overlay.png"},
    "prompt": "Recolor the vase inside the red circle to solid cobalt blue. Keep everything else unchanged. Remove the red circle.",
    "quality": "medium",
    "complexity": "low"
  }' | jq -er '.data[0].b64_json' | base64 --decode > vase.png

تستخدم طلبات JSON مصفوفة images وكائن markup يحتوي على أحد الحقلين فقط: image_url أو file_id. يمكن أن يكون image_url رابط HTTPS أو رابط بيانات base64. أما طلبات multipart فتستخدم رفع ملف بدلًا من ذلك، ويحتوي دليل توليد الصور على نسخة Python من ذلك.

للطبقة الشفافة (overlay) قواعد صارمة:

• بعد ضبط الاتجاه، يجب أن تطابق عرض الصورة الأولى وارتفاعها.
• يجب أن تحتوي على بكسلات شفافة، لذا لا تسطّحها فوق الصورة.
• تُطبّق على الصورة الأولى المُدخلة. وأي صور أخرى تعمل كمراجع.
• يمكن لكل صورة من الصورتين أن تحتوي على 16,777,216 بكسل كحد أقصى، ولا يمكن أن يتجاوز ملف الطبقة الشفافة 50 ميغابايت.
• لا يمكنك الجمع بين markup وmask أو prompt_rewriter.

أخبر النموذج بإزالة التعليق التوضيحي، كما يفعل مثال OpenAI نفسه. تكلفة العلامات كتكلفة أي تحرير آخر. لا تقبلها Responses API، لذا استخدم قناعًا (mask) هناك.

تصدير SVG

اضبط output_format على svg في نقطة نهاية التوليد للأيقونات والشعارات والرسومات التي تحتاج إلى مسارات قابلة للتحرير.

curl --fail-with-body --silent --show-error \
  https://api.openai.com/v1/images/generations \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.6-sunburst",
    "prompt": "A flat two-color wheat logo for a bakery called Field and Flour",
    "output_format": "svg",
    "quality": "medium",
    "n": 1
  }' | jq -er '.data[0].b64_json' | base64 --decode > logo.svg

تُصيّر واجهة API أولًا صورة مرجعية، ويتحكم quality بها، ثم تكتب ملف SVG انطلاقًا منها. البايتات المفكوكة ترميزها UTF-8 بصيغة XML، من دون سكربتات أو موارد خارجية أو صور نقطية مُضمّنة.

تنطبق أربعة قيود:

• يجب أن تكون قيمة n مساوية لـ1.
• البثّ، والصور الجزئية، وoutput_compression، وprompt_rewriter لا تعمل.
• لا تستطيع نقطة نهاية التحرير إخراج SVG، ولن تقبل ملف SVG كإدخال نقطي.
• يحدّد كائن svg الاختياري نموذج التأليف، لكن فقط إذا كان حسابك يدعم اختيار نموذج SVG. وإلا فاحذفه.

تدفع مرتين: سعر الصورة للصورة المرجعية، وسعر نموذج التأليف لرموزه. يدرج مرجع API كائن svg_usage منفصلًا لهذا الجزء الثاني، لذا سجّله.

ولّد ملف GIF

تُرجع واجهة API ملف GIF جاهزًا، لا ورقة رسوم متحركة (sprite sheet). أضف ثلاثة حقول إلى طلب التوليد:

{
  "model": "gpt-image-2.6-flare",
  "prompt": "A small orange robot waves, blinks and returns to its starting pose. Make it loop.",
  "output_format": "gif",
  "frame_count": 9,
  "frame_duration_ms": 200,
  "size": "auto"
}

فكّ ترميز b64_json بالطريقة نفسها واحفظه بامتداد .gif. تحقق من أمرين أولًا:

• حد الإطارات. يقول الدليل إن frame_count يتراوح من 2 إلى 64. بينما يقول مرجع API إنه من 2 إلى 16. ابقَ عند 16 أو أقل حتى تجرّب قيمًا أعلى.
• الوصول. يذكر المرجع أن إخراج GIF يتطلب الوصول إلى المعاينة الأولية لـGIF للنموذج المختار، في حين لا يذكر الدليل ذلك. قد يكون طلب GIF المرفوض مسألة وصول، لا خللًا في الحِمل المُرسل.

لا يدعم إخراج GIF البثّ أو الصور الجزئية أو output_compression المخصّص، ولا يمكن لنقطة نهاية التحرير إرجاعه. لا تنشر OpenAI صيغة فواتير خاصة بـGIF، لذا أجرِ اختبارًا صغيرًا وتحقق من فاتورتك قبل أن تتوسّع.

اضبط quality وcomplexity

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

اضبط complexity في كل طلب. القيمة الافتراضية هي high، ومع ذلك توصي OpenAI بـlow لمعظم عمليات التحرير. يحذّر الدليل من أن الإعدادات الأعلى قد تضيف زمن استجابة أطول وتُدخل تغييرات غير مرغوب فيها.

تحدد الجودة أيضًا فاتورة إخراجك. يستخدم هذا الجدول حاسبة OpenAI لصورة بحجم 1024x1024، مأخوذ بتاريخ 5 نوفمبر، ويستبعد رموز الإدخال:

الفارق بين medium وhigh يقارب سنتًا واحدًا، لذا قارن بينهما. لا تُدرج تبويب Batch في صفحة الأسعار الإصدار 2.6 بعد، لذا لا تفترض أن خصم الدفعات الخاص بـ2.5 ينطبق.

تعامل مع الأخطاء ومهلات الوقت

صنّف حالات الفشل بناءً على ما إذا كانت إعادة المحاولة قد تفيد:

استخدم error.code كفحصك المستقر، وسجّل معرّف الطلب. يحمل moderation_details حقلي moderation_stage وcategories العام، وهما ينتميان إلى سجلاتك، لا إلى الرسائل الموجّهة للمستخدم. اضبط مهلات العميل فوق دقيقتين، لأن OpenAI تقول إن الطلبات النصية المعقدة قد تستغرق هذه المدة.

دع وكيل البرمجة لديك يختبره باستخدام Apidog CLI

يمكن لوكيل البرمجة لديك تحويل هذه الطلبات والقيود إلى مجموعة اختبارات باستخدام Apidog CLI. أعِدّها مرة واحدة:

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_TOKEN>
apidog skill install

ثم أعطِ Claude Code أو Codex أو Cursor طلبًا نصيًا واحدًا:

In Apidog project <id>, add POST /v1/images/generations and POST /v1/images/edits
on https://api.openai.com. Read the bearer token from OPENAI_API_KEY.
Create test cases for gpt-image-2.6-flare at low quality and low complexity:
1. PNG generation: assert status 200 and data[0].b64_json exists.
2. SVG generation: assert status 200 and output_format equals svg.
3. GIF with frame_count 6: assert status 200 and output_format equals gif.
4. SVG with n set to 2: assert a 4xx status and that error.message exists.
5. GIF with frame_count 17: record the status, because OpenAI's docs disagree.
Put them in a test suite named "GPT-Image-2.6", run it against environment
<envId>, and summarize every failure.

يقرأ الوكيل كل مخطط (schema)، ويتحقق من صلاحية حِمله، ثم يكتب المجموعة ويشغّلها:

apidog cli-schema get endpoint-create
apidog cli-schema validate endpoint-create --file endpoint.json
apidog endpoint create --project <id> --file endpoint.json
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <id> --file case.json
apidog cli-schema validate test-suite-create --file suite.json
apidog test-suite create --project <id> --file suite.json
apidog test-suite run <suiteId> --project <id> -e <envId> \
  --env-var "OPENAI_API_KEY=$OPENAI_API_KEY" --on-error continue -r cli,json

تحسم الحالة 5 حد الإطارات لحسابك، وتوضح الحالة 3 ما إذا كان لديك وصول إلى GIF. تُجري الحالات الناجحة عمليات توليد حقيقية قابلة للفوترة، لذا أبقِ الجودة منخفضة. استبدل -r junit لتشغيل المجموعة في خط أنابيب CI، واطّلع على دليل إعداد Claude Code لتفاصيل الوكيل.

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

ما أسماء نماذج GPT-Image-2.6 API؟ gpt-image-2.6-flare وgpt-image-2.6-sunburst. لا يدرج مرجع API أي لقطات مؤرّخة لهما بعد، بخلاف نموذجي 2.5.

كم تكلفة GPT-Image-2.6 API؟ تكلف رموز الصور 8$ لكل مليون رمز إدخال و30$ لكل مليون رمز إخراج. تكلف صورة بحجم 1024x1024 نحو 0.025$ من الإخراج عند low ونحو 0.053$ عند high، قبل احتساب رموز الإدخال.

هل ينبغي أن أنتقل من gpt-image-2.5؟ انتقل إذا كنت تحتاج إلى SVG أو GIF أو complexity. اختبر تكاليفك أولًا: فصورة low تستخدم نحو 4.2 ضعف الرموز التي كانت تستخدمها على 2.5، ولا توجد أسعار Batch مُدرجة لنماذج 2.6 بعد.

هل يمكنني استخدام complexity على نقطة نهاية التحرير؟ نعم. توصي OpenAI بـlow لمعظم عمليات التحرير.

هل يمكنني تحويل صورة مرفوعة إلى GIF عبر واجهة API؟ لا. لا تُرجع نقطة نهاية التحرير GIF أو SVG، لذا تبدأ كلتا الصيغتين من طلب نصي على نقطة نهاية التوليد.

هل تُرجع واجهة API رابطًا؟ لا. تُرجع نماذج GPT Image دائمًا base64 في b64_json، لذا فكّ ترميزه وخزّن الملف بنفسك.