توليد الصور وتحريرها باستخدام gpt-image-2

واجهة API متوافقة مع OpenAI لتوليد الصور من النص وتحرير الصور عبر gpt-image-2: جاهزة للاستخدام بمجرد تبديل base_url، ونقاط نهاية متعددة المناطق، وفوترة موحّدة باستخدام مفتاح QCode الخاص بك

تحتاج مفتاح API؟ أنشئ حسابًا ←·نقاط النهاية وعناوين Base URL ←

يوفّر QCode.cc خدمة gpt-image-2 تتوافق صيغ الطلب والاستجابة فيها مع OpenAI Images API (تختلف بعض سلوكيات المعاملات — راجع الاختلافات عن OpenAI API الرسمي)، وتغطي نقطتي نهاية:

• توليد الصور من النص POST /v1/images/generations — طلب JSON، لتوليد الصور من النص وحده
• تحرير الصور POST /v1/images/edits — رفع multipart من 1 إلى 8 صور مصدر (قناع اختياري)، وإعادة الرسم / التعديل / التركيب وفقًا للـ prompt (صدرت في مايو 2026)

gpt-image-2 هو أحدث نموذج صور من OpenAI (صدر في أبريل 2026) ويقدّم حاليًا أقوى عرض للنص داخل الصور بين جميع النماذج العامة — إذ يستطيع عرض الأحرف الإنجليزية والصينية داخل الصور المولّدة بموثوقية.

ℹ️ أصدرت OpenAI الإصدار gpt-image-2.5 في 2026-09-08 (أسماء النماذج في API gpt-image-2.5-flare / gpt-image-2.5-sunburst). تقبل هذه الخدمة gpt-image-2.5 وgpt-image-2.5-flare وgpt-image-2.5-sunburst بوصفها أسماء نماذج متوافقة، بحيث يعمل العملاء المهيّؤون مسبقًا للأسماء الجديدة كما هي. جميع هذه الأسماء تعمل، وفوترتها متطابقة؛ وتُعامَل فئتا الجودة xhigh / max كأنهما high، ولا تُدعم بعدُ قدرات الإصدار 2.5 وحدها مثل 4K / الدقات الحرة.

ما يضيفه QCode.cc:

• يعمل مع OpenAI SDK — غيّر base_url وانتهى الأمر؛ تتطابق بنية الطلب والاستجابة مع OpenAI (بما في ذلك نقطة نهاية التحرير multipart)؛ وتختلف بعض سلوكيات المعاملات، راجع جدول الاختلافات في النهاية
• وصول متعدد المناطق: توجيه ذكي عالمي (api) / آسيا (كوريا / تايوان / هونغ كونغ) / أمريكا الشمالية وأوروبا (لوس أنجلوس) — اختر نقطة الدخول الأقرب إلى شبكتك
• مفتاح API واحد: أعد استخدام مفتاح cr_ الحالي من QCode.cc — الحصة والحساب نفسهما المستخدمان مع Claude Code وCodex
• عرض استخدام موحّد: تُدمج استدعاءات الصور واستدعاءات المحادثة في لوحة التحكم، إضافةً إلى صفحة استخدام ذاتية الخدمة مخصّصة
• حصة مشتركة عبر نقاط النهاية: تتشارك generations وedits الحد نفسه لكل مفتاح البالغ 100 صورة في اليوم وحد الطلبات المتزامنة البالغ 2

حالات الاستخدام الشائعة: توليد الملصقات، والرسوم التوضيحية، وصور المنتجات، ونماذج واجهة المستخدم التصورية، وأصول وسائل التواصل الاجتماعي، وتحرير الصور (الرسم الموضعي / تركيب عدة صور / تبديل الخلفية / الترميم عالي الدقة).

البدء السريع¶

تحويل النص إلى صورة (generations)¶

ثلاثة أسطر من Python لصورتك الأولى:

from openai import OpenAI
import base64

client = OpenAI(
    base_url="https://api.qcode.cc/qcode-img/v1",
    api_key="cr_YOUR_QCODE_API_KEY",
    timeout=180.0,  # typically 20-80s per image, occasionally over 100s; set at least 180s
)

result = client.images.generate(
    model="gpt-image-2",
    prompt="A cyberpunk Tokyo street at night, neon reflecting in rain puddles",
    size="1024x1024",
    quality="low",
    n=1,
)

with open("output.png", "wb") as f:
    f.write(base64.b64decode(result.data[0].b64_json))

تحرير الصورة (edits)¶

ارفع صورة موجودة مع prompt، واختياريًا مع قناع لإعادة الرسم الموضعي:

from openai import OpenAI
import base64

client = OpenAI(
    base_url="https://api.qcode.cc/qcode-img/v1",
    api_key="cr_YOUR_QCODE_API_KEY",
    timeout=180.0,
)

result = client.images.edit(
    model="gpt-image-2",
    image=open("cat.png", "rb"),
    mask=open("mask.png", "rb"),          # optional: PNG alpha; transparent area = repaint region
    prompt="put a tiny crown on the cat",
    size="1024x1024",
    quality="high",
)

with open("edited.png", "wb") as f:
    f.write(base64.b64decode(result.data[0].b64_json))

⚠️ اضبط المهلة دائمًا صراحةً على ≥ 180 ثانية: القيمة الافتراضية في OpenAI SDK قصيرة جدًا. استدلال gpt-image-2 أبطأ بكثير من تحويل النص إلى صورة التقليدي (راجع زمن الاستجابة والمهلة أدناه).

نقاط النهاية¶

تتوفر خدمة gpt-image-2 (سواء generations أو edits) على كل مدخل من QCode.cc. ما عليك سوى إلحاق /qcode-img/v1 بالعنوان الأساسي:

توجّه جميع المداخل إلى الخدمة نفسها ونظام الفوترة نفسه؛ الاستخدام والحصة موحّدان. لا يفرض أي مدخل حدًا قدره 100 ثانية على الطلب الواحد؛ ينتظر الخادم حتى 180 ثانية لكل طلب.

qcode-img هو بادئة المسار المخصصة لإنشاء الصور وتحريرها، بالتوازي مع /api (Anthropic) و/openai/v1 (دردشة OpenAI).

مرجع API¶

ترويسات الطلب الشائعة¶

نقطة نهاية التوليد /v1/images/generations¶

نقطة النهاية: POST {base_url}/images/generations نوع المحتوى: application/json

جسم الطلب:

{
  "model": "gpt-image-2",
  "prompt": "A small ceramic vase with sunflower, photorealistic",
  "size": "1024x1024",
  "quality": "low",
  "n": 1
}

الحقول:

نقطة نهاية التعديلات /v1/images/edits¶

نقطة النهاية: POST {base_url}/images/edits نوع المحتوى: multipart/form-data (يتطلب رفع الملفات form-data، وليس JSON)

الحقول:

حدود حجم الرفع: الملف الواحد ≤ 25 MB؛ الإجمالي عبر الملفات ≤ 50 MB (تجاوز الحد يُرجع 413 image_too_large).

الاستجابة (نفسها لكلا نقطتي النهاية)¶

{
  "created": 1777135432,
  "data": [
    {
      "b64_json": "iVBORw0KGgo...(base64 PNG/JPEG/WebP, 1-3 MB)",
      "revised_prompt": "A small ceramic vase with sunflower..."
    }
  ]
}

• b64_json: بيانات صورة بترميز base64؛ اعرضها مباشرة باستخدام <img src="data:image/<format>;base64,...">
• revised_prompt: النسخة المحسّنة من prompt الأصلي الخاص بك من قبل النموذج (اختياري عرضها)

استجابات الأخطاء¶

تتبع الأخطاء مخطط OpenAI القياسي:

{
  "error": {
    "type": "rate_limit_error",
    "code": "image_daily_limit",
    "message": "Daily image generation count limit reached..."
  }
}

أمثلة على الشيفرة¶

Python (OpenAI SDK، موصى به)¶

تحويل النص إلى صورة:

from openai import OpenAI
import base64

client = OpenAI(
    base_url="https://api.qcode.cc/qcode-img/v1",
    api_key="cr_YOUR_QCODE_API_KEY",
    timeout=180.0,
)

result = client.images.generate(
    model="gpt-image-2",
    prompt="A cyberpunk Tokyo street at night, neon reflecting in rain puddles",
    size="1024x1024",
    quality="low",
    n=1,
)

img_bytes = base64.b64decode(result.data[0].b64_json)
with open("output.png", "wb") as f:
    f.write(img_bytes)
print("Saved output.png")

تحرير الصورة (صورة واحدة + الترميم بالقناع):

from openai import OpenAI
import base64

client = OpenAI(
    base_url="https://api.qcode.cc/qcode-img/v1",
    api_key="cr_YOUR_QCODE_API_KEY",
    timeout=180.0,
)

result = client.images.edit(
    model="gpt-image-2",
    image=open("cat.png", "rb"),
    mask=open("mask.png", "rb"),
    prompt="put a tiny crown on the cat",
    size="1024x1024",
    quality="high",
    extra_body={"output_format": "png"},
)

img = base64.b64decode(result.data[0].b64_json)
with open("edited.png", "wb") as f:
    f.write(img)

تحرير الصورة (تركيب متعدد الصور، من 2 إلى 8 صور):

result = client.images.edit(
    model="gpt-image-2",
    image=[
        open("scene.png", "rb"),       # 1st image: scene background
        open("product.png", "rb"),     # 2nd image: product to place
    ],
    prompt="Place the product naturally into the scene, match the lighting and shadows.",
    size="1536x1024",
    quality="high",
)

curl¶

تحويل النص إلى صورة:

curl https://api.qcode.cc/qcode-img/v1/images/generations \
  -H "Authorization: Bearer cr_YOUR_QCODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A cyberpunk Tokyo street at night",
    "size": "1024x1024",
    "quality": "low",
    "n": 1
  }' \
  | jq -r ".data[0].b64_json" | base64 -d > output.png

تحرير الصورة:

curl https://api.qcode.cc/qcode-img/v1/images/edits \
  -H "Authorization: Bearer cr_YOUR_QCODE_API_KEY" \
  -F "model=gpt-image-2" \
  -F "image=@cat.png" \
  -F "mask=@mask.png" \
  -F "prompt=put a tiny crown on the cat" \
  -F "size=1024x1024" \
  -F "quality=high" \
  -F "output_format=png" \
  | jq -r ".data[0].b64_json" | base64 -d > edited.png

تركيب متعدد الصور (يكفي تكرار -F image=@):

curl https://api.qcode.cc/qcode-img/v1/images/edits \
  -H "Authorization: Bearer cr_YOUR_QCODE_API_KEY" \
  -F "model=gpt-image-2" \
  -F "image=@scene.png" \
  -F "image=@product.png" \
  -F "prompt=Place the product naturally into the scene" \
  -F "size=1536x1024" \
  -F "quality=high"

JavaScript / Node.js / المتصفح¶

تحويل النص إلى صورة:

const r = await fetch("https://api.qcode.cc/qcode-img/v1/images/generations", {
  method: "POST",
  headers: {
    "Authorization": "Bearer cr_YOUR_QCODE_API_KEY",
    "Content-Type":  "application/json",
  },
  body: JSON.stringify({
    model: "gpt-image-2",
    prompt: "A cyberpunk Tokyo street at night",
    size: "1024x1024",
    quality: "low",
    n: 1,
  }),
});
const json = await r.json();
const dataUrl = "data:image/png;base64," + json.data[0].b64_json;
document.querySelector("img").src = dataUrl;

تحرير الصورة (FormData في المتصفح):

const fd = new FormData();
fd.append("model", "gpt-image-2");
fd.append("image", imageFile);              // File object from <input type="file">
fd.append("mask", maskFile);                // optional
fd.append("prompt", "put a tiny crown on the cat");
fd.append("size", "1024x1024");
fd.append("quality", "high");
fd.append("output_format", "png");

const r = await fetch("https://api.qcode.cc/qcode-img/v1/images/edits", {
  method: "POST",
  headers: { "Authorization": "Bearer cr_YOUR_QCODE_API_KEY" },
  // Don't set Content-Type manually — FormData sets multipart/form-data with the boundary
  body: fd,
});
const json = await r.json();
const dataUrl = "data:image/png;base64," + json.data[0].b64_json;
document.querySelector("img").src = dataUrl;

الحصص¶

القيم الافتراضية¶

تغطي القيم الافتراضية الغالبية العظمى من المستخدمين. تواصل مع الدعم لرفعها.

استعلام الاستخدام¶

• لوحة التحكم — تعرض استدعاءات الدردشة والصور معًا (آخر نشاط، تكلفة اليوم، التكلفة الإجمالية، توزيع النماذج)
• صفحة الخدمة الذاتية: https://api.qcode.cc/qcode-img/usage — أدخل مفتاح API الخاص بك لعرض استخدام آخر 30 يومًا، وقائمة الاستدعاءات المفصلة، واتجاه ECharts (يُحفظ المفتاح محليًا في متصفحك، ولا يُرفع أبدًا)

الفوترة¶

كيف تعمل الفوترة¶

تُفوتر generations وedits بالطريقة نفسها، لكل صورة إخراج:

• $0.30 لكل صورة إخراج: توليد n من الصور يكلّف n × $0.30
• size / quality / عدد صور الإدخال / mask / طول prompt لا تؤثر في السعر
• gpt-image-2، وgpt-image-2-low / -medium / -high، والأسماء المتوافقة gpt-image-2.5 / -flare / -sunburst تشترك كلها في السعر نفسه
• اعتبارًا من 2026-10-07، السعر $0.30 لكل صورة (كان $0.15 لكل صورة اعتبارًا من 2026-10-06؛ وقبل ذلك كانت الفوترة لكل token)

لا تُحتسب الإخفاقات¶

أي طلب فاشل لا تُحتسب فوترته أبدًا: لا تُحتسب 4xx (بما في ذلك رفض مراجعة المحتوى) / 5xx، ولا حالات انتهاء المهلة، ولا انقطاعات العميل (الاتصالات المغلقة).

العملة¶

تُحدَّد التكاليف بالدولار الأمريكي USD وتُسوَّى وفق سياسة العملة لحساب QCode.cc الخاص بك (CNY / USD).

إعدادات زمن الاستجابة والمهلة¶

gpt-image-2 نموذج قائم على الاستدلال ويستغرق وقتًا أطول بشكل ملحوظ من نماذج تحويل النص إلى صورة القديمة. تستغرق الصورة الواحدة عادةً 20–80 ثانية، وأحيانًا أكثر من 100 ثانية، وفي حالات نادرة تقترب من 180 ثانية.

نصائح عملية:

• مهلة OpenAI Python SDK الافتراضية أقصر من اللازم — عيّن timeout=180.0 أو قيمة أعلى صراحةً دائمًا
• لا توجد مهلة افتراضية لـ fetch في المتصفح؛ إذا استخدمت AbortController فامنحه 180 ثانية على الأقل
• إذا مرّ الطلب عبر وكيل عكسي / بوابة خاصة بك، فارفع مهلة القراءة فيها إلى ≥ 180 ثانية

المهلة وإعادة المحاولة¶

• 503 image_provider_unavailable: خدمة الصور غير متاحة مؤقتًا، ولا يتم تحصيل أي مبلغ. انتظر وفقًا لما تحدده ترويسة الاستجابة Retry-After (بالثواني)، ثم أعد المحاولة بتراجع أسي (30 s → 60 s → 120 s) بحد أقصى 3 محاولات؛ إذا استمر الفشل، فتواصل مع الدعم
• 504 upstream_timeout / المهلة من جانب العميل: تجاوز توليد واحد 180 ثانية. لا بأس بإعادة المحاولة مباشرةً؛ وإذا استمرت المهلات، فبسّط الـ prompt أو قلّل عدد صور الإدخال
• 429 crs_daily_exhausted / crs_total_exhausted: استُنفدت حصة الحساب، وتُعالج بالطريقة نفسها المتبعة في نقاط نهاية الدردشة: تُصفَّر الخطة الشخصية عند 00:00 بتوقيت بكين (أو اشترِ باقة التعزيز)، وتُجدَّد باقة الدفع حسب الاستخدام؛ راجع مرجع الأخطاء
• 429 image_daily_limit / concurrency_exhausted: انتظر وفقًا لترويسة Retry-After؛ وإذا استمر ذلك، فتواصل مع الدعم
• لا تُحتسب تكلفة الطلبات الفاشلة، لذا لا تؤدي إعادة المحاولة أبدًا إلى تحصيل مبلغ مضاعف

نصائح صياغة الـ prompt¶

تحويل النص إلى صورة (generations)¶

• متعدد اللغات: تعمل الـ prompts بالصينية أو الإنجليزية أو المختلطة جميعها
• مزيد من التفاصيل أفضل: البيئة، والتكوين، والإضاءة، والأسلوب، ومسافة العدسة / البعد البؤري / الزاوية
• تجنّب أسماء العلامات التجارية / الأشخاص المشهورين: قد يرفض النموذج أو يعيد نتائج ضبابية (سياسة محتوى OpenAI)
• النص داخل الصورة: يتميز gpt-image-2 في عرض النص الإنجليزي / الصيني داخل الصور (عناوين الملصقات، والشعارات، واللافتات) — ضع النص الحرفي في الـ prompt فقط، دون صياغة خاصة
• مراجعة المحتوى: يعيد الـ prompt الذي يخالف سياسة المحتوى الرمز 400 (مثل content_policy_violation) ولا تُحتسب تكلفته

مثال:

A vintage poster in Bauhaus style, bold black text "MORNING COFFEE" centered,
warm orange and cream color palette, geometric shapes, slightly textured paper background

تحرير الصورة (edits)¶

• يحدد القناع «أين»، لا «ماذا»: المنطقة الشفافة = المنطقة المراد إعادة رسمها، والمنطقة المعتمة محفوظة. يصف الـ prompt ما يجب رسمه. يجب أن تطابق دقة القناع دقة image (يعيد النظام تحجيمها).
• مع مدخلات الصور المتعددة، سمِّ دور كل صورة في الـ prompt — مثل «الصورة الأولى هي المشهد، والصورة الثانية هي المنتج المراد وضعه فيه» — يقرأ gpt-image-2 المدخلات بالترتيب.
• لا حاجة لتمرير input_fidelity: يعالج gpt-image-2 صور الإدخال دائمًا بدقة عالية، مع الحفاظ تلقائيًا على الوجوه / الشعارات / النصوص / تفاصيل المنتج (يُتجاهل تمرير low / high، وأي قيمة أخرى تُرجع 400).
• من دون قناع، يُعاد رسم الصورة كاملة وفقًا للـ prompt (تُحفظ البنية الدلالية، لكن قد تتغير كل منطقة).

مثال:

# Local inpaint: add a crown, keep the rest unchanged
prompt = "Put a tiny golden crown on the cat's head. Keep everything else unchanged."
mask = (alpha PNG with only the head area transparent)

الفروق مقابل API OpenAI الرسمي¶

ساحة التجربة عبر الإنترنت¶

https://api.qcode.cc/qcode-img/ — جرّبه في متصفحك:

• وضعا تحويل النص إلى صورة وتحرير الصورة مهيآن بصريًا (الرفع، ورسم القناع، واختيار background / output_format، إلخ.)
• أدخل مفتاح API الخاص بك + prompt لتوليد الصورة فورًا
• مبدّل واجهة المستخدم بين الإنجليزية والصينية
• يستخدم جودة low افتراضيًا
• يتضمن مرجع API كاملًا ضمن الصفحة (تبويبات curl / Python / JavaScript + جدول المعاملات + رموز الأخطاء)
• تنزيل بنقرة واحدة بصيغة PNG / JPEG / WebP

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

س: ماذا أفعل بشأن 503 image_provider_unavailable؟ ج: خدمة الصور غير متاحة مؤقتًا، ولا تُفوتر الطلبات الفاشلة. انتظر وفقًا لما توجّهك إليه ترويسة Retry-After ثم أعد المحاولة (تراجع أُسّي يبدأ من 30 ثانية، بحد أقصى 3 محاولات). إذا استمر الفشل، فتواصل مع الدعم.

س: هل تدعم gpt-image-2.5 (flare / sunburst)؟ ج: يمكنك استخدام أسماء النماذج gpt-image-2.5 وgpt-image-2.5-flare وgpt-image-2.5-sunburst مباشرةً — كل هذه الأسماء تعمل، مع فوترة مطابقة؛ تُعامَل فئتا الجودة xhigh / max كما high، والقدرات الخاصة بـ 2.5 فقط مثل 4K غير مدعومة بعد.

س: لماذا يختلف حجم الإخراج عن size الذي أرسلته؟ ج: يطابق حجم الإخراج size المطلوب عادةً؛ وفي بعض الحالات يختلف الحجم المعاد (مثل 1254×1254)، لذا اعتمد على الحجم الفعلي للصورة المعادة. إذا كنت تحتاج إلى حجم دقيق، فاقتصّ الصورة أو غيّر مقياسها محليًا.

س: هل يؤثر quality في السعر؟ ج: لا يؤثر quality في السعر — سواء كان low أو high، فالسعر $0.30 لكل صورة إخراج.

س: هل تُفوتر الطلبات الفاشلة؟ ج: لا. لا تُفوتر 4xx / 5xx، ولا المهلات، ولا حالات رفض مراجعة المحتوى، ولا انقطاعات العميل.

الوثائق ذات الصلة¶

• نقاط النهاية ومسارات API — قائمة كاملة بمدخلات QCode.cc، ومسارات البروتوكول، واختبار curl السريع
• الفوترة — الخطط، والحصص، وقواعد التكلفة

المؤسسات ←