تولید و ویرایش تصویر با gpt-image-2

API سازگار با OpenAI برای تولید تصویر از متن و ویرایش تصویر با gpt-image-2: فقط base_url را عوض کنید و شروع کنید، نقاط پایانی چندمنطقه‌ای، صورت‌حساب یکپارچه با کلید QCode شما

به کلید API نیاز دارید؟ ثبت‌نام ←·نقاط پایانی و Base URL ←

QCode.cc سرویس gpt-image-2 را ارائه می‌دهد که قالب درخواست و پاسخ آن با OpenAI Images API سازگار است (رفتار چند پارامتر متفاوت است — به تفاوت‌ها با API رسمی OpenAI مراجعه کنید) و دو نقطه پایانی را پوشش می‌دهد:

• تولید تصویر از متن POST /v1/images/generations — درخواست JSON، تولید تصویر فقط از متن
• ویرایش تصویر POST /v1/images/edits — بارگذاری multipart از 1 تا 8 تصویر منبع (ماسک اختیاری)، بازترسیم / تغییر / ترکیب بر اساس prompt (عرضه‌شده در می 2026)

gpt-image-2 جدیدترین مدل تصویر OpenAI است (منتشرشده در آوریل 2026) و در حال حاضر قوی‌ترین رندر متن درون تصویر میان همه مدل‌های عمومی را دارد — می‌تواند حروف انگلیسی و چینی را به‌طور مطمئن داخل تصاویر تولیدشده نمایش دهد.

ℹ️ OpenAI در 2026-09-08 مدل gpt-image-2.5 را منتشر کرد (نام‌های مدل 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 درخواست هم‌زمان استفاده می‌کنند

موارد استفاده رایج: تولید پوستر، تصویرسازی، تصاویر محصول، ماکت‌های UI، دارایی‌های شبکه‌های اجتماعی، ویرایش تصویر (بازنقاشی موضعی (inpainting) / ترکیب چند تصویر / تغییر پس‌زمینه / بازسازی با وفاداری بالا).

شروع سریع¶

تولید تصویر از متن (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 را به Base URL اضافه کنید:

همه نقاط ورود به همان سرویس و سامانه صورت‌حساب مسیریابی می‌شوند — مصرف و سهمیه یکپارچه است. هیچ نقطه ورودی، یک درخواست واحد را به 100 ثانیه محدود نمی‌کند؛ سرور برای هر درخواست تا 180 ثانیه صبر می‌کند.

qcode-img پیشوند مسیری است که به تولید و ویرایش تصویر اختصاص دارد و هم‌تراز با /api (Anthropic) و /openai/v1 (چت OpenAI) است.

مرجع API¶

هدرهای رایج درخواست¶

نقطه پایانی تولید تصویر /v1/images/generations¶

نقطه پایانی: POST {base_url}/images/generations Content-Type: 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 Content-Type: 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 به‌ازای هر تصویر است (از 2026-10-06 قیمت $0.15 به‌ازای هر تصویر بود؛ پیش از آن، صورت‌حساب بر مبنای توکن محاسبه می‌شد)

درخواست‌های ناموفق هزینه‌ای ندارند¶

هیچ درخواست ناموفقی هرگز صورت‌حساب نمی‌شود: خطاهای 4xx (از جمله رد شدن توسط بازبینی محتوا) / 5xx، مهلت‌های تمام‌شده و قطع اتصال از سمت کلاینت (بستن اتصال) صورت‌حساب نمی‌شوند.

واحد پول¶

هزینه‌ها بر حسب USD بیان می‌شوند و بر اساس سیاست واحد پول حساب کاربری QCode.cc شما (CNY / USD) تسویه می‌شوند.

تنظیمات تأخیر و مهلت¶

gpt-image-2 مدلی مبتنی بر استنتاج است و به‌طور محسوسی بیشتر از مدل‌های قدیمی متن‌به‌تصویر زمان می‌برد. یک تصویر معمولاً 20–80 ثانیه، گاهی بیش از 100 ثانیه و در موارد نادر نزدیک به 180 ثانیه زمان می‌برد.

توصیه عملی:

• مهلت پیش‌فرض SDK پایتون OpenAI بسیار کوتاه است — همیشه 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)¶

• چندزبانه: promptهای چینی، انگلیسی یا ترکیبی همه کار می‌کنند
• جزئیات بیشتر بهتر است: محیط، ترکیب‌بندی، نورپردازی، سبک، فاصله لنز / فاصله کانونی / زاویه
• از نام برندها / افراد مشهور پرهیز کنید: مدل ممکن است امتناع کند یا نتیجه تار برگرداند (سیاست محتوای 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
• صورتحساب — پلن‌ها، سهمیه‌ها، قواعد هزینه

سازمانی ←