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

QCode.cc سرویس `gpt-image-2` را ارائه می‌دهد که **قالب درخواست و پاسخ آن با OpenAI Images API سازگار است** (رفتار چند پارامتر متفاوت است — به [تفاوت‌ها با API رسمی OpenAI](#differences-vs-the-official-openai-api) مراجعه کنید) و دو نقطه پایانی را پوشش می‌دهد:

- **تولید تصویر از متن** `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 برای نخستین تصویر شما:

```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 بارگذاری کنید، به‌صورت اختیاری همراه با ماسک برای بازسازی موضعی:

```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,
)

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` به‌طور قابل‌توجهی کندتر از تولید تصویر از متن قدیمی است (به [تأخیر و مهلت زمانی](#latency-timeout-settings) در ادامه مراجعه کنید).

---

## نقاط پایانی

سرویس `gpt-image-2` (هر دو `generations` و `edits`) روی همه نقاط ورود QCode.cc در دسترس است. فقط `/qcode-img/v1` را به Base URL اضافه کنید:

| موقعیت شما | base_url پیشنهادی | پروتکل | یادداشت‌ها |
|---|---|---|---|
| چین | `https://api.qcode.cc/qcode-img/v1` | HTTPS | به‌طور پیش‌فرض توصیه می‌شود |
| هنگ‌کنگ / جنوب شرق آسیا | `https://asia.qcode.cc/qcode-img/v1` | HTTPS | گره آسیا (کره / تایوان / هنگ‌کنگ، نزدیک‌ترین) |
| آمریکای شمالی / اروپا | `https://us.qcode.cc/qcode-img/v1` | HTTPS | گره لس‌آنجلس |

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

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

---
## مرجع API

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

| هدر | الزامی | مقدار |
|---|---|---|
| `Authorization` | ✓ | `Bearer cr_xxxxxxxxxxxxxxxx` (کلید API QCode.cc شما) |
| `Content-Type` | ✓ | `application/json` (تولید تصویر)<br/>`multipart/form-data` (ویرایش تصویر) |

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

**نقطه پایانی**: `POST {base_url}/images/generations`
**Content-Type**: `application/json`

بدنه درخواست:

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

فیلدها:

| فیلد | نوع | الزامی | پیش‌فرض | مقادیر |
|---|---|---|---|---|
| `model` | رشته | ✗ | `gpt-image-2` | `gpt-image-2` (همچنین `gpt-image-2-low` / `-medium` / `-high` را می‌پذیرد، معادل تنظیم `quality`؛ و نام‌های سازگاری `gpt-image-2.5` / `gpt-image-2.5-flare` / `gpt-image-2.5-sunburst`، که همگی با صورت‌حساب یکسان قابل استفاده‌اند)؛ هر نام مدل دیگری `400 unsupported_model` را برمی‌گرداند |
| `prompt` | رشته | ✓ | — | توضیح تصویر، **چندزبانه** (شامل انگلیسی و چینی) |
| `size` | رشته | ✗ | `1024x1024` | `auto` / `1024x1024` / `1024x1536` / `1536x1024` / `2048x2048`؛ مقادیر نامعتبر `422` را برمی‌گردانند. **اندازه خروجی معمولاً با `size` درخواستی مطابقت دارد؛ در برخی موارد اندازه بازگشتی متفاوت است (مثلاً 1254×1254) — ملاک، اندازه واقعی تصویر بازگشتی است** |
| `quality` | رشته | ✗ | `medium` | `low` / `medium` / `high` (`xhigh` / `max` به‌عنوان `high` در نظر گرفته می‌شوند)؛ **بر قیمت تأثیر ندارد** (به [صورت‌حساب](#billing) مراجعه کنید) |
| `n` | عدد صحیح | ✗ | 1 | تعداد تصویر در هر فراخوانی (1 – 4)؛ **> 4 مقدار 400 را برمی‌گرداند** (بدون کوتاه‌سازی بی‌صدا) |
| `background` | رشته | ✗ | `auto` | `auto` / `opaque`؛ `transparent` مقدار 400 را برمی‌گرداند (مدل نمی‌تواند کانال آلفا تولید کند) |
| `response_format` | رشته | ✗ | `b64_json` | فقط `b64_json`؛ ارسال `url` مقدار 400 را برمی‌گرداند |
| `output_compression` | عدد صحیح | ✗ | — | `0 – 100`، برای JPEG / WebP اعمال می‌شود؛ مقادیر خارج از محدوده 400 را برمی‌گردانند |
| `stream` / `partial_images` | — | ✗ | — | هنوز پشتیبانی نمی‌شود؛ ارسال آن‌ها 400 را برمی‌گرداند |

### نقطه پایانی ویرایش تصویر `/v1/images/edits`

**نقطه پایانی**: `POST {base_url}/images/edits`
**Content-Type**: `multipart/form-data` (بارگذاری فایل به form-data نیاز دارد، نه JSON)

فیلدها:

| فیلد | نوع | الزامی | پیش‌فرض | مقادیر / یادداشت‌ها |
|---|---|---|---|---|
| `model` | رشته | ✗ | `gpt-image-2` | می‌توان آن را حذف کرد؛ نقطه پایانی ویرایش تصویر همیشه از `gpt-image-2` استفاده می‌کند |
| `image` | فایل (× N) | ✓ | — | تصویر مبدأ (PNG / JPEG / WebP)؛ **1 – 8 تصویر برای ترکیب چندتصویری پشتیبانی می‌شود** (نام فیلد یکسان را تکرار کنید: `-F image=@a.png -F image=@b.png`) |
| `mask` | فایل | ✗ | — | ماسک آلفای PNG؛ **ناحیه شفاف = ناحیه‌ای که باید بازترسیم شود**؛ وضوح ماسک باید با `image` مطابقت داشته باشد (به‌طور خودکار مقیاس می‌شود)؛ برای ویرایش تک‌تصویری اعمال می‌شود |
| `prompt` | رشته | ✓ | — | دستور ویرایش (چندزبانه) |
| `size` | رشته | ✗ | `auto` | `auto` / `1024x1024` / `1024x1536` / `1536x1024` / `2048x2048`. **اندازه خروجی معمولاً با `size` درخواستی مطابقت دارد؛ در برخی موارد اندازه بازگشتی متفاوت است (مثلاً 1254×1254) — ملاک، اندازه واقعی تصویر بازگشتی است.** مقادیر نامعتبر 422 را برمی‌گردانند |
| `quality` | رشته | ✗ | `auto` | `auto` / `low` / `medium` / `high` (`xhigh` / `max` به‌عنوان `high` در نظر گرفته می‌شوند)؛ بر قیمت تأثیر ندارد |
| `n` | عدد صحیح | ✗ | 1 | تعداد تصویر در هر فراخوانی (1 – 4)؛ **> 4 مقدار 400 را برمی‌گرداند** (بدون کوتاه‌سازی بی‌صدا) |
| `background` | رشته | ✗ | `auto` | `auto` / `opaque`. **`transparent` توسط gpt-image-2 پشتیبانی نمی‌شود** (مدل نمی‌تواند کانال آلفا تولید کند؛ ارسال آن 400 را برمی‌گرداند) |
| `output_format` | رشته | ✗ | `png` | `png` / `jpeg` / `webp` |
| `output_compression` | عدد صحیح | ✗ | — | `0 – 100`، برای JPEG / WebP اعمال می‌شود (برای PNG نادیده گرفته می‌شود)؛ **مقادیر خارج از محدوده 400 را برمی‌گردانند** |
| `input_fidelity` | رشته | ✗ | — | نیازی به ارسال آن نیست: مدل همیشه تصاویر ورودی را با وفاداری بالا پردازش می‌کند؛ ارسال `low` / `high` نادیده گرفته می‌شود، هر مقدار دیگری 400 را برمی‌گرداند |
| `response_format` | رشته | ✗ | `b64_json` | فقط `b64_json` پذیرفته می‌شود (ارسال `url` مقدار 400 را برمی‌گرداند) |
| `user` | رشته | ✗ | — | شناسه کاربر نهایی که عبور داده می‌شود (برای تشخیص سوءاستفاده) |

**محدودیت‌های اندازه بارگذاری**: هر فایل ≤ 25 MB؛ مجموع فایل‌ها ≤ 50 MB (بیش از حد مجاز `413 image_too_large` را برمی‌گرداند).

### پاسخ (برای هر دو نقطه پایانی یکسان است)

```json
{
  "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 پیروی می‌کنند:

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

| HTTP | کد | معنا | صورت‌حساب‌شده |
|---|---|---|---|
| 400 | `invalid_json` / `missing_prompt` | بدنه درخواست JSON معتبر نیست / `prompt` وجود ندارد | خیر |
| 400 | `unsupported_model` | نام مدل پشتیبانی نمی‌شود (`gpt-image-2` و نام‌های سازگاری آن `gpt-image-2.5` / `-flare` / `-sunburst` پشتیبانی می‌شوند؛ `gpt-image-1`، `dall-e-3` و غیره این خطا را برمی‌گردانند) | خیر |
| 400 | `stream_not_supported` | `stream=true` یا `partial_images` ارسال شده است | خیر |
| 400 | `unsupported_background` / `unsupported_response_format` / `unsupported_n` / `unsupported_output_compression` | مقدار پارامتر پشتیبانی نمی‌شود (جدول پارامترهای هر نقطه پایانی را ببینید) | خیر |
| 400 | `invalid_multipart` / `invalid_content_type` | فرم نامعتبر در نقطه پایانی ویرایش تصویر (باید `multipart/form-data` باشد) | خیر |
| 400 | `content_policy_violation` و مشابه | بازبینی محتوا درخواست را رد کرد؛ prompt یا تصویر را تغییر دهید | خیر |
| 401 | `invalid_api_key` / `key_disabled` / `key_expired` | کلید API نامعتبر / غیرفعال / منقضی است | خیر |
| 413 | `image_too_large` | هر فایل > 25 MB، یا مجموع فایل‌ها > 50 MB | خیر |
| 422 | `unsupported_size` | مقدار `size` پشتیبانی نمی‌شود (مقادیر معتبر در جدول پارامترهای هر نقطه پایانی آمده است) | خیر |
| 429 | `crs_daily_exhausted` / `crs_total_exhausted` | بودجه روزانه / مادام‌العمر حساب کاربری شما تمام شده است | خیر |
| 429 | `image_daily_limit` | سقف روزانه 100 تصویر برای هر کلید پر شده است (بین `generations` و `edits` مشترک است؛ در صورت درخواست قابل افزایش است) | خیر |
| 429 | `concurrency_exhausted` | سقف هم‌زمانی 2 برای هر کلید پر شده است (با درخواست افزایش می‌یابد) | خیر |
| 501 | `endpoint_not_implemented` | نقطه پایانی ویرایش تصویر موقتاً برای تعمیرات بسته است | خیر |
| 503 | `image_provider_unavailable` | سرویس تصویر موقتاً در دسترس نیست؛ پاسخ شامل `Retry-After` است — آن را مطابق [مهلت زمانی و تلاش مجدد](#timeout-and-retry) مدیریت کنید | خیر |
| 503 | `service_overloaded` / `billing_backend_unavailable` | سرویس مشغول است / بک‌اند صورت‌حساب موقتاً در دسترس نیست؛ بعداً دوباره تلاش کنید | خیر |
| 504 | `upstream_timeout` | یک درخواست ویرایش در 180 ثانیه کامل نشد | خیر |

---
## نمونه‌های کد

### Python (OpenAI SDK، توصیه‌شده)

**متن به تصویر:**

```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,
)

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")
```

**ویرایش تصویر (یک تصویر + بازسازی با ماسک):**

```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,
)

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 تصویر):**

```python
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

**متن به تصویر:**

```bash
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
```

**ویرایش تصویر:**

```bash
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=@` را تکرار کنید):**

```bash
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 / مرورگر

**متن به تصویر:**

```javascript
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 مرورگر):**

```javascript
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;
```

---
## سهمیه‌ها

### پیش‌فرض‌ها

| معیار | پیش‌فرض | توضیحات |
|---|---|---|
| **تعداد روزانه تصویر** | 100 / روز / کلید | در 00:00 به وقت پکن بازنشانی می‌شود؛ **بین `generations` و `edits` مشترک است** |
| **هم‌زمانی** | 2 در حال اجرا | خطای 429 `concurrency_exhausted` را برمی‌گرداند؛ بین هر دو نقطه پایانی مشترک است |
| **اندازه بارگذاری** (فقط edits) | 25 MB برای یک فایل / 50 MB مجموع | خطای 413 `image_too_large` را برمی‌گرداند |
| **بودجه حساب کاربری** | مشترک با `dailyCostLimit` / `totalCostLimit` حساب کاربری QCode.cc شما | خطای 429 `crs_daily_exhausted` را برمی‌گرداند |

پیش‌فرض‌ها نیاز اکثریت قریب به اتفاق کاربران را پوشش می‌دهند. برای افزایش، با پشتیبانی تماس بگیرید.

### بررسی مصرف

- **داشبورد** — فراخوانی‌های چت و تصویر را با هم نشان می‌دهد (آخرین فعالیت، هزینه امروز، هزینه کل، توزیع مدل‌ها)
- **صفحه خودخدمتی**: [https://api.qcode.cc/qcode-img/usage](https://api.qcode.cc/qcode-img/usage) — کلید API خود را وارد کنید تا مصرف 30 روز گذشته، فهرست تفصیلی فراخوانی‌ها و نمودار روند ECharts را ببینید (کلید به‌صورت محلی در مرورگر شما نگهداری می‌شود و هرگز بارگذاری نمی‌شود)

---

## صورت‌حساب

### صورت‌حساب چگونه محاسبه می‌شود

`generations` و `edits` به یک شکل و **به‌ازای هر تصویر خروجی** صورت‌حساب می‌شوند:

| قلم قابل صورت‌حساب | قیمت واحد |
|---|---|
| به‌ازای هر تصویر خروجی | $0.30 |

- **$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 به وقت پکن ریست می‌شود (یا یک بسته تقویتی بخرید)، بسته پرداخت به‌ازای مصرف تمدید می‌شود؛ به [مرجع خطاها](/docs/reference/errors#402-quota-exhausted) مراجعه کنید
- **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

| معیار | OpenAI رسمی | QCode.cc |
|---|---|---|
| سازگاری SDK | — | ✅ قالب‌های درخواست / پاسخ سازگار هستند، تغییر `base_url` کافی است؛ ردیف‌های زیر تفاوت‌های رفتاری را نشان می‌دهند |
| صورتحساب | به‌ازای هر توکن | $0.30 به‌ازای هر تصویر خروجی، `n` تصویر = `n × $0.30` |
| `/v1/images/generations` (متن به تصویر) | ✅ | ✅ |
| `/v1/images/edits` (ویرایش تصویر) | ✅ | ✅ از ترکیب 1 تا 8 تصویر و ترمیم نواحی با ماسک پشتیبانی می‌کند |
| `size` | — | اندازه خروجی معمولاً با `size` مطابقت دارد؛ گاهی متفاوت است — به تصویر بازگشتی تکیه کنید |
| `quality` | — | روی قیمت تأثیر ندارد |
| `background=transparent` | — | ❌ خطای 400 برمی‌گرداند |
| `response_format=url` | — | ❌ فقط `b64_json` |
| `stream` + `partial_images` (بازگشت تدریجی) | ✅ | ⏳ هنوز پشتیبانی نمی‌شود، ارسال آن‌ها خطای 400 برمی‌گرداند |
| `/v1/images/variations` (تنوع‌های خالص) | ✅ (نقطه پایانی DALL·E) | ⏳ هنوز پشتیبانی نمی‌شود (آن را با `edits` به‌همراه یک prompt توصیفی تقریب بزنید) |
| gpt-image-2.5 (`flare` / `sunburst`) | ✅ (انتشار: 2026-09-08) | ✅ نام‌های مدل سازگاری را می‌پذیرد، **همه با صورتحساب یکسان قابل استفاده‌اند**؛ `xhigh` / `max` به‌عنوان `high` در نظر گرفته می‌شوند، قابلیت‌های مختص 2.5 (4K و غیره) هنوز پشتیبانی نمی‌شوند |

---

## محیط آزمایش آنلاین

[https://api.qcode.cc/qcode-img/](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](/en/docs/getting-started/endpoints-and-api-paths) — فهرست کامل ورودی‌های QCode.cc، مسیرهای پروتکل، آزمون سریع curl
- [صورتحساب](/en/docs/reference/billing) — پلن‌ها، سهمیه‌ها، قواعد هزینه