واجهة OpenAI لتوليد الصور في Python: مثال خطوة بخطوة

تتوقف معظم الشروحات الخاصة بواجهة الصور من OpenAI عند عبارة "إليك رابط". كان ذلك يعمل مع DALL-E، لكنه لا يعمل مع نماذج GPT Image، التي تعيد بيانات base64 فقط، ولهذا غالبًا ما ينهار السكربت الذي ينسخه الناس أولًا عند result.data[0].url. يبدأ هذا الشرح من سكربت يعمل، ثم يبني عليه بالأحجام ومستويات الجودة وتعديلات الأقنعة ومعاينات البثّ والدفعات غير المتزامنة وأداة صغيرة لتتبع التكلفة.

المعاملات وأسماء النماذج والأسعار الواردة أدناه مأخوذة من وثائق OpenAI الحالية لتوليد الصور وصفحة التسعير الخاصة بها، وقد قُرئت بتاريخ 2026-10-06. وحيثما يمكن أن يتغير رقم، يذكر النص ذلك.

قبل أن تكتب أي شيفرة

ثلاثة أشياء يجب أن تكون جاهزة قبل أن ينجح أول طلب: اسم النموذج، وSDK مثبّت، ومؤسسة OpenAI موثّقة. الأخيرة هي ما يوقع أغلب الحسابات الجديدة في المشكلة، لأن نماذج GPT Image تعيد خطأ وصول إلى أن يكتمل التوثيق من إعدادات وحدة التحكم للمطورين.

اختر نموذجًا

هذه نماذج GPT Image التي تسعّرها OpenAI اليوم. تعمل الخمسة أيضًا على PicassoIA، وهو مفيد لاختبار أمر نصي قبل أن تكتب أي شيفرة.

على PicassoIA يمكنك تجربة GPT Image 2.5 Flare، وGPT Image 2.5 Sunburst، وGPT Image 2، وGPT Image 1، وGPT Image 1 Mini جنبًا إلى جنب. إعداد افتراضي معقول: Flare للتوليد، وSunburst عندما تكون المهمة تعديلًا.

التثبيت والمصادقة

ثبّت SDK الرسمي:

pip install --upgrade openai pillow

نسخ الأمر النصي

أنشئ سرًّا للمشروع من لوحة OpenAI، ثم اجعله متغيّر بيئة. يقرأه SDK تلقائيًا، فلا يظهر السرّ أبدًا في ملف المصدر.

# macOS / Linux
export OPENAI_API_KEY="sk-..."

# Windows PowerShell
$env:OPENAI_API_KEY = "sk-..."

نسخ الأمر النصي

💡 نصيحة: أبقِ السرّ بعيدًا عن دفاتر الملاحظات التي تنوي مشاركتها، وبعيدًا عن سجل git. إن تسرّب، فألغِه من اللوحة وأنشئ سرًّا جديدًا.

أول صورة لك في Python

السكربت الأدنى

هذا هو الكود كله. شغّله فيظهر ملف PNG بجانب السكربت.

import base64
from pathlib import Path
from openai import OpenAI

client = OpenAI()

result = client.images.generate(
    model="gpt-image-2.5-flare",
    prompt="A ceramic bowl of ripe peaches on a linen cloth, soft window light, 50mm photograph",
    size="1536x1024",
    quality="medium",
)

image_bytes = base64.b64decode(result.data[0].b64_json)
Path("peaches.png").write_bytes(image_bytes)

نسخ الأمر النصي

تؤدي أربعة وسائط العمل. model يختار المحرك، وprompt يصف الصورة، وsize يحدد أبعاد البكسلات، وquality يوازن بين السرعة والتكلفة من جهة والتفاصيل من جهة أخرى. لكل ما عدا ذلك قيمة افتراضية معقولة، وصيغة الخرج هي PNG ما لم تطلب غيرها.

اكتب أوامر نصية تصمد

قد ينهار أمر نصي ينجح في عرض تجريبي حين يتكرر في حلقة من خمسين صورة. أربع عادات تحافظ على ثبات النتائج:

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

لماذا تأتي الاستجابة بصيغة Base64

تعيد نماذج GPT Image دائمًا base64. خيار response_format="url" الذي كان يقبله DALL-E غير مدعوم، لذلك result.data[0].url غير موجود، والصورة نفسها تصل داخل b64_json. ثلاث عادات تنتج عن ذلك:

• فكّ الترميز مرة واحدة، واكتب إلى القرص. base64.b64decode يمنحك بايتات خام يمكنك حفظها أو رفعها أو تمريرها إلى Pillow.
• استضف الملف بنفسك. إن احتاج مدوّن أو تطبيق إلى رابط عام، فادفع البايتات إلى تخزينك الخاص (S3 أو R2 أو CDN) واحفظ ذلك الرابط.
• تخطَّ القرص للمعاينات السريعة. ابنِ URI بيانات باستخدام f"data:image/png;base64,{b64}" وضعه في وسم <img>.

💡 تنقل من شيفرة قديمة؟ البحث في مشروعك عن .url وresponse_format يجد تقريبًا كل سطر يحتاج إلى تغيير.

الحجم والجودة وصيغة الخرج

تحدد هذه المعاملات ما تحصل عليه وما تكلّفه. إليك القائمة الكاملة التي تنشرها الوثائق:

بعض القواعد العملية:

• أفقي وعمودي. 1536x1024 و1024x1536 يناسبان معظم صيغ المدونات ووسائل التواصل. للحصول على 16:9 حقيقية، اطلب 2048x1152: حافتاه مضاعفان لـ 16، وعدد البكسلات يقع بوضوح داخل النطاق المسموح.
• كرّر بأقل تكلفة، وأنهِ بجودة عالية. جرّب الأوامر النصية عند quality="low"، ثم أعد تشغيل الأفضل عند high. تدفع مقابل توكنات الخرج، والجودة الأعلى تنتج منها المزيد.
• اختر الصيغة حسب الوجهة. أبقِ PNG للتعديل والشفافية، وانتقل إلى webp مع output_compression=85 للصفحات التي يجب أن تُحمَّل بسرعة.

عدّل الصور الموجودة بالأقنعة

عدّل صورة واحدة

يأخذ images.edit ملفًا مصدرًا مع أمر نصي يصف التغيير. مرّر قائمة من الملفات عندما تريد دمج عدة مراجع.

with open("living-room.png", "rb") as photo:
    edited = client.images.edit(
        model="gpt-image-2.5-sunburst",
        image=photo,
        prompt="Swap the grey sofa for a green velvet armchair, keep the window light unchanged",
    )

Path("living-room-edit.png").write_bytes(base64.b64decode(edited.data[0].b64_json))

نسخ الأمر النصي

صِف ما يجب أن يبقى كما هو بالوضوح نفسه الذي تصف به ما يجب أن يتغير. تنحرف النماذج عندما يسمّي الأمر العنصر الجديد وحده.

أضف قناعًا

يقصر القناع التعديل على منطقة واحدة. وهو ملف PNG فيه قناة ألفا، بالأبعاد نفسها للمصدر. البكسلات الشفافة تمامًا تحدد المنطقة المراد إعادة رسمها، وكل ما هو معتم يبقى محميًا. يُنشئ Pillow قناعًا كهذا في بضعة أسطر:

from PIL import Image, ImageDraw

base = Image.open("living-room.png").convert("RGBA")
mask = Image.new("RGBA", base.size, (0, 0, 0, 255))          # opaque: keep
ImageDraw.Draw(mask).rectangle((620, 380, 1180, 900), fill=(0, 0, 0, 0))  # transparent: repaint
mask.save("mask.png")

with open("living-room.png", "rb") as photo, open("mask.png", "rb") as hole:
    edited = client.images.edit(
        model="gpt-image-2.5-sunburst",
        image=photo,
        mask=hole,
        prompt="A green velvet armchair with a wooden side table, matching the room's light",
    )

نسخ الأمر النصي

القناع إرشاد، وليس قطعًا حادًا. قد تتسرب الحواف قليلًا، لذا اترك هامشًا صغيرًا حول الشيء الذي تريد استبداله.

معاينات البثّ والدفعات

صور جزئية أثناء الانتظار

قد تستغرق الصور عالية الجودة بعض الوقت. مع stream=True وpartial_images، ترسل واجهة API إطارات مسودة قبل الصورة النهائية، فتتمكن الواجهة من عرض التقدم بدلًا من مؤشر دوران.

stream = client.images.generate(
    model="gpt-image-2.5-flare",
    prompt="A vintage red bicycle leaning on a brick wall, golden hour, 35mm photograph",
    size="1536x1024",
    quality="high",
    stream=True,
    partial_images=2,
)

for event in stream:
    if event.type == "image_generation.partial_image":
        Path(f"preview-{event.partial_image_index}.png").write_bytes(base64.b64decode(event.b64_json))
    else:
        Path("final.png").write_bytes(base64.b64decode(event.b64_json))

نسخ الأمر النصي

قد تضيف المعاينات إلى عدد التوكنات، لذا قارن usage مع البثّ وبدونه قبل أن تفعّله لكل طلب.

دفعات غير متزامنة دون أخطاء معدل

لقائمة من الأوامر النصية، يحافظ AsyncOpenAI مع semaphore على عدد الطلبات الجارية تحت السيطرة:

import asyncio
from openai import AsyncOpenAI

client = AsyncOpenAI(max_retries=4, timeout=180)
gate = asyncio.Semaphore(3)

async def render(index: int, prompt: str) -> Path:
    async with gate:
        result = await client.images.generate(
            model="gpt-image-2.5-flare", prompt=prompt, size="1536x1024", quality="low",
        )
    path = Path(f"batch-{index:02d}.png")
    path.write_bytes(base64.b64decode(result.data[0].b64_json))
    return path

async def main(prompts: list[str]) -> list[Path]:
    return await asyncio.gather(*(render(i, p) for i, p in enumerate(prompts)))

نسخ الأمر النصي

يحدّ semaphore التزامن، وليس عدد الصور في الدقيقة. في مستويات الاستخدام المنخفضة يكون حد الدقيقة هو الأول الذي يصطدم به الطلب، لذا ارفع max_retries ودع SDK يتراجع تلقائيًا. وعندما لا ينتظر أحد المخرجات، تدعم هذه النماذج Batch endpoint وتحتسب توكنات الخرج بنصف السعر.

التكاليف والحدود والأخطاء

معدلات التوكنات لكل نموذج

تسعّر OpenAI هذه النماذج بالتوكنات، لا بالصورة، ولا تنشر جدولًا بسعر كل صورة للنماذج الحالية. المعدلات لكل 1 مليون توكن:

تغيّر الجودة والحجم عدد توكنات الخرج التي تستهلكها الصورة، ولهذا قد يكلّف الأمر نفسه مبالغ مختلفة كثيرًا عند low وhigh.

تتبّع الإنفاق في الشيفرة

تتضمن الاستجابة كائن usage يحمل عدد التوكنات. حوّله إلى دولارات بعد كل استدعاء ولن تُفاجأ بأي فاتورة أبدًا:

RATES = {"text_in": 5.00, "image_in": 8.00, "image_out": 30.00}  # USD per 1M tokens

def cost_usd(usage) -> float:
    details = usage.input_tokens_details
    return (
        details.text_tokens * RATES["text_in"]
        + details.image_tokens * RATES["image_in"]
        + usage.output_tokens * RATES["image_out"]
    ) / 1_000_000

print(f"Last image: ${cost_usd(result.usage):.4f}")

نسخ الأمر النصي

تعتمد حدود المعدل على مستوى استخدامك. بالنسبة إلى gpt-image-2.5-flare، تدرج صفحة النموذج هذه الحدود وقت كتابة هذا النص:

أخطاء ستواجهها

انتبه إلى الأخطاء الثلاثة المهمة في الإنتاج:

import openai

try:
    result = client.images.generate(model="gpt-image-2.5-flare", prompt=prompt, size="1536x1024")
except openai.BadRequestError as err:
    print("Rejected:", err.message)
except openai.RateLimitError:
    print("Image limit reached, slow down")
except openai.APIConnectionError:
    print("Network problem, retry later")

نسخ الأمر النصي

كيف تستخدم GPT Image 2 على PicassoIA

قبل أن تنفق ميزانية API على تجارب الأوامر النصية، جرّبها في المتصفح. يعرض GPT Image 2 على PicassoIA نصوصًا مقروءة داخل الصور، ويدعم الخلفيات الشفافة، ويقبل الصور المرجعية، ويُنشئ حتى 10 تنويعات في كل تشغيل.

جرّب الأوامر النصية دون شيفرة

1. افتح صفحة النموذج واكتب أمرك النصي. ضع بين علامتي اقتباس أي نص يجب أن يظهر داخل الصورة.
2. اضبط الجودة على low للمسودات. انتقل إلى high للتصيير النهائي.
3. اختر نسبة العرض إلى الارتفاع: تعكس 3:2 أو 2:3 1536x1024 و1024x1536، ويعطي 16:9 إطارًا عريضًا.
4. اختر صيغة الخرج. WebP هي الافتراضية، وPNG يحافظ على الشفافية نظيفة.
5. حدّد عدد الصور بين 1 و10، ثم ولّد.
6. ارفع صور المرجع إن أردت التعديل بدلًا من الإنشاء من الصفر.

تتطابق حقول النموذج مع استدعاء Python، فالوصفة التي تعمل في المتصفح تنتقل مباشرة إلى الشيفرة:

يقبل حقل اختياري بيانات اعتمادك الخاصة في OpenAI، فإن تركته فارغًا يتولى وسيط PicassoIA الطلب.

هناك عادتان إضافيتان تستحقان العناء. أولًا، صِغ الأمر النصي بنموذج لغوي: الصق فكرة أولية في GPT 5 أو Claude Sonnet 4.6 واطلب ثلاثة تنويعات فوتوغرافية تشمل العدسة والضوء والتأطير. ثانيًا، شغّل الأمر النصي نفسه عبر PicassoIA Image وSeedream 4.5 لترى أي أسلوب يناسب مشروعك. وللتعديلات التي لا تحتاج شيفرة، يتولى PicassoIA Image Editor Pro تغييرات الصور مباشرة في المتصفح.

واجهة PicassoIA البرمجية للمطورين API

إذا احتاج خط العمل لديك إلى مزوّد مختلف، فلدى PicassoIA واجهة API خاصة بالمطورين على غرار Replicate:

• العنوان الأساسي: https://api.picassoia.com/v1
• المصادقة: رمز Bearer يبدأ بـ pia_sk_
• التدفق: أنشئ تنبؤًا باستخدام POST /v1/models/{owner}/{name}/predictions، ثم استطلع GET /v1/predictions/{id}، ثم اقرأ النتيجة
• الحد: 5 تنبؤات متزامنة لكل حساب

المهام غير متزامنة، لذلك تحل حلقة الإنشاء ثم الاستطلاع محل الاستدعاء الواحد المعطِّل الذي كتبته أعلاه. تحقّق من متطلبات الخطة في صفحة API في PicassoIA قبل أن تبني عليها.

أنشئ صورك الخاصة اليوم

أصبح لديك الآن خط عمل جاهز: ثبّت SDK، وأكّد توثيق المؤسسة، واطلب صورة، وفكّ ترميز base64، واضبط size وquality، وعدّل بقناع، وشغّل المعاينات، واجمع الطلبات ضمن الحدود، وسجّل الإنفاق. أسرع طريقة لتحسين النتائج هي الكمية. اكتب عشرة أوامر نصية، وشغّلها عند low، واحتفظ بأفضل اثنين، وأعد تصيير هذين عند high.

إذا أردت اختبار الأوامر النصية قبل لمس API، فافتح GPT Image 2 على PicassoIA، وأنشئ عدة تنويعات، وقارنها بنماذج أخرى في مكتبة نماذج PicassoIA. وبعد أن تحصل على صور ثابتة تعجبك، يمكن لمجموعة التأثيرات في PicassoIA أن تضيف حركة وأسلوبًا فوقها. اختر موضوعًا يهمك، واكتب أمرًا نصيًا واحدًا مفصّلًا، وانظر ما الذي ستحصل عليه.