نموذج GPT Image 2.5 | وثائق API

# GPT Image 2.5

Generate images with Flare or edit reference images with Sunburst.

POST https://api.apihop.ai/openai/v1/images/generations

Use `gpt-image-2.5-flare` for fast image generation or `gpt-image-2.5-sunburst` for precise editing. Check `GET https://api.apihop.ai/v1/models` for availability with your API key.

## Request

```http
POST https://api.apihop.ai/openai/v1/images/generations
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

```json
{
  "model": "gpt-image-2.5-flare",
  "prompt": "A red ceramic cup on a white table.",
  "size": "1:1",
  "resolution": "1k",
  "quality": "low",
  "n": 1
}
```

| Parameter | Values |
| --- | --- |
| `model` | Required: `gpt-image-2.5-flare` or `gpt-image-2.5-sunburst` |
| `prompt` | Required text describing the image or edit |
| `n` | Integer from 1 to 4; default 1 |
| `size` | `auto`, aspect ratio, or pixel dimensions such as `1600x1200` |
| `resolution` | `1k` (default), `2k`, `4k`; ignored for exact pixel sizes |
| `quality` | `low`, `medium`, `high`, `xhigh`, `max`, `auto` (default) |
| `image_urls` | Up to 16 publicly accessible HTTP(S) image URLs |
| `output_format` | `png` (default), `jpeg`, `webp` |
| `output_compression` | Integer from 0 to 100 for JPEG or WebP |
| `background` | `auto`, `opaque`, `transparent`; transparent requires PNG or WebP |
| `moderation` | `low` (default), `auto` |
| `stream` | `false` (default) for JSON, `true` for SSE completion events |

Supported aspect ratios: `1:1`, `3:2`, `2:3`, `4:3`, `3:4`, `5:4`, `4:5`, `16:9`, `9:16`, `2:1`, `1:2`, `21:9`, `9:21`, `3:1`, `1:3`. Exact pixel dimensions must be multiples of 16, have no side above 3840 pixels, an aspect ratio at most 3:1, and 655,360 to 8,294,400 total pixels. For example, square `4k` output is 2880x2880, not 4096x4096.

## Reference Images

```json
{
  "model": "gpt-image-2.5-sunburst",
  "prompt": "Keep the product and its lettering. Replace the background with a white studio.",
  "image_urls": ["https://example.com/product.png"],
  "resolution": "2k",
  "quality": "xhigh"
}
```

References use this JSON generation endpoint. Upload local images to your own storage first. Base64 data URIs, multipart uploads, masks, and a separate `/images/edits` endpoint are outside this model's public contract.

## Response

The HTTP connection waits for completion; clients do not poll an upstream task. JSON responses include final image URLs and available token usage:

```json
{
  "created": 1789035000,
  "data": [{"url": "https://example.com/generated-image.png"}],
  "usage": {"input_tokens": 15, "output_tokens": 196, "total_tokens": 211}
}
```

With `stream: true`, wait for `image_generation.completed` and `[DONE]` on the same connection. Partial image previews are not guaranteed.

## Pricing

Billing uses actual text input, cached text input, image input, cached image input, and image output tokens. Both variants have the same token prices. The model catalog shows your current price and the separate OpenAI reference price. An image is not a fixed-price unit: prompt length, references, size, quality, and count affect the total. A temporary reservation is reconciled after completion. Choosing an explicit quality makes expected usage clearer.

Invalid parameters return 400; authentication failures return 401; insufficient balance returns 402. An unavailable model returns 404, rate limits return 429, and generation failures return 5xx. Do not automatically resubmit a request whose completion status is unknown.

See [Error Codes and Troubleshooting](https://apihop.ai/en/docs/api-reference/errors) for error codes, streaming failures, and retry boundaries.

استخدم gpt-image-2.5-flare لتوليد الصور بسرعة أو gpt-image-2.5-sunburst للتحرير الدقيق. تحقق من الإتاحة لمفتاح API لديك عبر GET https://api.apihop.ai/v1/models.

الطلب

http

POST https://api.apihop.ai/openai/v1/images/generations
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

json

{
  "model": "gpt-image-2.5-flare",
  "prompt": "A red ceramic cup on a white table.",
  "size": "1:1",
  "resolution": "1k",
  "quality": "low",
  "n": 1
}

المعامل	القيم
`model`	مطلوب: `gpt-image-2.5-flare` أو `gpt-image-2.5-sunburst`
`prompt`	نص مطلوب يصف الصورة أو التعديل
`n`	عدد صحيح من 1 إلى 4؛ وافتراضيا 1
`size`	`auto` أو نسبة أبعاد أو أبعاد بالبكسل مثل `1600x1200`
`resolution`	`1k` (افتراضي) أو `2k` أو `4k`؛ تهمل عند تحديد أبعاد دقيقة بالبكسل
`quality`	`low` أو `medium` أو `high` أو `xhigh` أو `max` أو `auto` (افتراضي)
`image_urls`	حتى 16 عنوان صورة HTTP(S) متاحا للعامة
`output_format`	`png` (افتراضي) أو `jpeg` أو `webp`
`output_compression`	عدد صحيح من 0 إلى 100 لتنسيق JPEG أو WebP
`background`	`auto` أو `opaque` أو `transparent`؛ تتطلب الشفافية PNG أو WebP
`moderation`	`low` (افتراضي) أو `auto`
`stream`	`false` (افتراضي) لاستجابة JSON، و`true` لأحداث اكتمال SSE

نسب الأبعاد المدعومة: 1:1 و3:2 و2:3 و4:3 و3:4 و5:4 و4:5 و16:9 و9:16 و2:1 و1:2 و21:9 و9:21 و3:1 و1:3. يجب أن تكون الأبعاد الدقيقة بالبكسل من مضاعفات 16، وألا يتجاوز أي ضلع 3840 بكسلا، وبنسبة أبعاد قصوى 3:1، وإجمالي بكسلات من 655,360 إلى 8,294,400. مثلا، الإخراج المربع بدقة 4k هو 2880x2880، وليس 4096x4096.

الصور المرجعية

json

{
  "model": "gpt-image-2.5-sunburst",
  "prompt": "Keep the product and its lettering. Replace the background with a white studio.",
  "image_urls": ["https://example.com/product.png"],
  "resolution": "2k",
  "quality": "xhigh"
}

تستخدم المراجع نقطة نهاية التوليد هذه بصيغة JSON. ارفع الصور المحلية إلى تخزينك أولا. تقع عناوين بيانات Base64 والرفع متعدد الأجزاء والأقنعة ونقطة نهاية /images/edits المستقلة خارج العقد العام لهذا النموذج.

الاستجابة

ينتظر اتصال HTTP الاكتمال؛ ولا يستطلع العملاء مهمة لدى المزود. تتضمن استجابات JSON عناوين الصور النهائية واستخدام الرموز المتاح:

json

{
  "created": 1789035000,
  "data": [{"url": "https://example.com/generated-image.png"}],
  "usage": {"input_tokens": 15, "output_tokens": 196, "total_tokens": 211}
}

مع stream: true، انتظر image_generation.completed و[DONE] على الاتصال نفسه. معاينات الصور الجزئية غير مضمونة.

الأسعار

تستخدم الفوترة رموز المدخلات النصية الفعلية والمدخلات النصية المخزنة مؤقتا ومدخلات الصور ومدخلات الصور المخزنة مؤقتا ومخرجات الصور. للنسختين أسعار الرموز نفسها. يعرض كتالوج النماذج سعرك الحالي وسعر OpenAI المرجعي المستقل. الصورة ليست وحدة بسعر ثابت: يؤثر طول التعليمة والمراجع والحجم والجودة والعدد في الإجمالي. تجري تسوية الحجز المؤقت بعد الاكتمال. اختيار جودة صريحة يجعل الاستخدام المتوقع أوضح.

تعيد المعاملات غير الصحيحة 400؛ وإخفاقات المصادقة 401؛ والرصيد غير الكافي 402. يعيد النموذج غير المتاح 404، وحدود المعدل 429، وإخفاقات التوليد 5xx. لا تعد إرسال طلب ذي حالة اكتمال مجهولة تلقائيا.

راجع رموز الأخطاء وتشخيصها لرموز الأخطاء وإخفاقات البث وحدود إعادة المحاولة.