> ## Documentation Index > Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt > Use this file to discover all available pages before exploring further. # OpenAI Images Generations API 申请及使用 > OpenAI generation API guide - Ace Data Cloud OpenAI Images Generations API 目前支持多种图像生成模型，包括经典的 `dall-e-3`、文字渲染能力更强的 `gpt-image-1`、最新一代的 **`gpt-image-2`**，以及通过同一接口接入的 **`nano-banana` / `nano-banana-2-lite` / `nano-banana-2` / `nano-banana-pro`** 系列模型。它们都能根据文本描述生成高质量的图像。 本文档主要介绍 OpenAI Images Generations API 操作的使用流程，利用它我们可以轻松使用 OpenAI 系列的图像生成功能。 ## 申请流程 要使用 OpenAI Images Generations API，首先到 [Ace Data Cloud 控制台](https://platform.acedata.cloud/console/applications) 获取您的 API Token，留作备用。 ![](https://cdn.acedata.cloud/5hmkdg.jpg) 如果你尚未登录或注册，会自动跳转到登录页面邀请你注册和登录，完成后会自动返回当前页面。 **一个 API Token 即可调用平台所有服务，无需为每个服务单独申请。** 首次申请会赠送免费额度，可免费体验；额度不足时可在 [控制台](https://platform.acedata.cloud/console/coin) 充值通用余额。 > 📘 完整文档：[OpenAI Images Generations API →](https://platform.acedata.cloud/documents/openai-images-generations) ## GPT-Image-2 模型 `gpt-image-2` 是 OpenAI 推出的新一代图像生成模型，相比 `dall-e-3` 和 `gpt-image-1`，在以下方面有明显提升： * **指令遵循能力更强**：能够准确理解复杂构图、计数、位置关系等结构化指令。 * **文字渲染更清晰**：海报、菜单、信息图、标志等场景下的英文与数字几乎不会出现错乱。 * **风格表现更丰富**：原生支持电影感人像、复古海报、儿童插画、产品摄影、信息图等多种风格。 * **原生多比例 + 高分辨率支持**：覆盖 5 种比例（1:1、4:3、3:4、16:9、9:16）共 3 档分辨率（1K / 2K / 4K）。 调用方式与其它模型完全一致，只需将 `model` 字段设置为 `gpt-image-2` 即可。返回结果中的 `url` 是一个永久托管在 `platform.cdn.acedata.cloud` 上的图片链接，可以直接在浏览器中打开或嵌入到网页中。 ### 官方中转 / 逆向变体（`:official` / `:reverse`） `gpt-image-2` 默认走逆向线路。通过模型名后缀可以显式选择线路： * **`gpt-image-2:official`**：官方中转线路。支持 `n > 1`（一次返回多张）与真实 2K / 4K 分辨率，**按每张图片计费，单价为默认 `gpt-image-2` 的 2 倍**。当前仅由 openai-hk 渠道提供，线路不可用时直接返回错误，不会降级到逆向线路。 * **`gpt-image-2:reverse`**：与默认 `gpt-image-2` 完全等价（逆向线路），用于显式声明走逆向线路、价格不变。 > 下文“关于 `n` 参数”的限制只适用于默认 / 逆向线路；`gpt-image-2:official` 支持 `n > 1` 并按张计费。 ### 支持的 `size` 取值 `gpt-image-2` 只检查 `size` 的格式，只要不是 `auto` 或空串，就需要匹配 `WIDTHxHEIGHT`（例如 `1024x1024`、`2048x1152`、`800x600`）；任何其他形态会返回 400。**所有尺寸（1K / 2K / 4K / 自定义）按单张统一扣费，不按尺寸加价。** 上游对自定义尺寸的硬约束：宽高均为 16 的倍数、长边 ≤ 3840、总像素数 ≤ 8,294,400。超出范围会被上游拒绝并以 4xx 返回。 | 比例 | 1K 推荐 | 2K 推荐 | 4K 推荐 | | ---- | ----------- | ----------- | ----------- | | 1:1 | `1024x1024` | `2048x2048` | `2880x2880` | | 4:3 | `1536x1024` | `2048x1536` | `3264x2448` | | 3:4 | `1024x1536` | `1536x2048` | `2448x3264` | | 16:9 | `1792x1024` | `2048x1152` | `3840x2160` | | 9:16 | `1024x1792` | `1152x2048` | `2160x3840` | > 你也可以传 `size: "auto"` 或者**省略 `size` 字段**，此时由模型自行选择默认尺寸。 > 1K 档下上游输出不保证严格像素对齐——你传 `1024x1024` 可能拿到 `1254x1254`，比例保持一致。如果你重新把它当作 `size` 传进来，计费不变。 > 4K 单次调用通常需要 4–8 分钟，建议配合后文的 `callback_url` 异步回调使用。 > **关于 `n` 参数** > `gpt-image-2` 目前**不支持 `n > 1`**：该参数会被静默忽略，无论传 `n=1` 还是 `n=10`，单次请求都只会返回 1 张图，并且只按 1 张计费。如果你需要一次拿到多张候选图，请**自行并发发起多次请求**（建议同时传不同的 `prompt` 或不同的 `seed`，否则得到的几张图可能高度相似）。该限制同样适用于 `gpt-image-1` / `gpt-image-1.5`，以及 `nano-banana` / `nano-banana-2-lite` / `nano-banana-2` / `nano-banana-pro` 系列。`dall-e-2` 是目前唯一原生支持 `n > 1` 的模型；`dall-e-3` 仅支持 `n = 1`。 下面通过几个不同方位的真实示例来直观感受 `gpt-image-2` 的能力。 ### 场景一：电影感人像 提示词中可以使用电影术语（35mm 胶片、浅景深、霓虹光等）来精准控制氛围与质感。 Python 样例调用代码： ```python theme={null} import requests url = "https://api.acedata.cloud/openai/images/generations" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "model": "gpt-image-2", "prompt": "صورة سينمائية لامرأة شابة واقفة في متجر صغير في الليل، مضاءة بواسطة لافتات نيون وردية وزرقاء من خلال النافذة. تم تصويرها على فيلم 35 مم، عمق ميدان ضحل، حبيبات خفيفة، مزاج حزين.", "size": "1024x1536" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` النتيجة كما يلي: ```json theme={null} { "success": true, "task_id": "ab58a5df-6f46-4874-bff6-93169e2849a3", "created": 1777048800, "data": [ { "revised_prompt": "صورة سينمائية لامرأة شابة واقفة في متجر صغير في الليل، مضاءة بواسطة لافتات نيون وردية وزرقاء من خلال النافذة. تم تصويرها على فيلم 35 مم، عمق ميدان ضحل، حبيبات خفيفة، مزاج حزين.", "url": "https://platform.cdn.acedata.cloud/gpt-image/ab58a5df-6f46-4874-bff6-93169e2849a3_0.png" } ] } ``` الصورة الناتجة كما يلي:

### المشهد الثاني: ملصق سفر عتيق (مع نص) `gpt-image-2` يظهر استقرارًا في الطباعة ورسم الخطوط، مما يجعله مناسبًا جدًا لإنشاء الملصقات، القوائم، بطاقات التهنئة وغيرها من التصاميم التي تحتوي على نصوص. ```python theme={null} payload = { "model": "gpt-image-2", "prompt": "ملصق سفر عتيق لساحل أمالفي، إيطاليا. رسم توضيحي بأسلوب آرت ديكو لمنازل صفراء الليمون تتدفق على جانب الجرف إلى بحر تركواز، مع قارب شراعي أبيض صغير في الميناء. النص الجريء في الأعلى يقرأ أمالفي وفي الأسفل إيطاليا 1958. لوحة ألوان محدودة: كريمة، زرقاء البحر، صفراء الليمون، تيراكوتا. نسيج خفيف من حبيبات الورق.", "size": "1024x1536" } ``` الصورة في حقل `url` من النتيجة كما يلي:

يمكن رؤية أن النموذج لم يستعد فقط أسلوب الملصق البصري لآرت ديكو بدقة، بل تم عرض نص العنوان `أمالفي` و `إيطاليا 1958` بوضوح وصحيح. ### المشهد الثالث: تركيب معقد وعدد تستخدم عبارة الطلب التالية لاختبار قدرة النموذج على اتباع التعليمات الهيكلية مثل "الكمية" و"الموقع". ```python theme={null} payload = { "model": "gpt-image-2", "prompt": "رف كتب خشبي يتكون من ثلاثة رفوف: على الرف العلوي، يجب أن يكون هناك كتاب واحد. على الرف الثاني، يجب أن يكون هناك ثلاثة كتب. على الرف السفلي، يجب أن يكون هناك سبعة كتب. إضاءة دافئة ناعمة، فوتوغرافية، جو مكتبة مريح.", "size": "1024x1024" } ``` الصورة الناتجة كما يلي:

يمكن رؤية أن عدد الكتب على الرفوف الثلاثة (1 / 3 / 7) يتطابق تمامًا مع عبارة الطلب، وهو ما كان من الصعب تحقيقه بثبات في عصر `dall-e-3`. ### المشهد الرابع: أسلوب الرسوم التوضيحية (أفقي) من خلال تحديد وسيلة الفن وكلمات مفتاحية للمشاعر، يمكن توجيه النموذج لإنتاج رسومات توضيحية بأسلوب معين. ```python theme={null} payload = { "model": "gpt-image-2", "prompt": "رسم توضيحي ناعم وشعري لكتاب أطفال يظهر ثعلب صغير يقرأ كتابًا تحت فطر متوهج في غابة مضاءة بالقمر. نسيج مائي ورصاص، ألوان باستيل لطيفة، جو حالمي، إحساس مرسوم باليد.", "size": "1536x1024" } ``` الصورة الأفقية الناتجة كما يلي: ![](https://platform.cdn.acedata.cloud/gpt-image/6cd57e69-d237-4cc1-a666-759a93964a08_0.png) ### غير متزامن واستدعاء `gpt-image-2` يتطلب عادةً 60-90 ثانية لكل استدعاء، إذا كنت لا ترغب في الحفاظ على اتصال طويل، يمكنك استخدام آلية الاستدعاء غير المتزامن `callback_url` التي سيتم تقديمها لاحقًا في هذه المقالة، حيث تكون عملية الاستدعاء متطابقة مع النماذج الأخرى. ## سلسلة نماذج Nano Banana سلسلة `nano-banana` هي نماذج توليد الصور المعتمدة على Gemini، وقد تم دمجها من خلال نفس واجهة `/openai/images/generations`، دون الحاجة لتغيير نقطة النهاية، فقط قم بتغيير `model` إلى أي من النماذج في الجدول أدناه. | النموذج | التكلفة (Credits / مرة) | المشهد المناسب | | -------------------- | ----------------------- | --------------------------------------------------------- | | `nano-banana` | 0.14 | توليد صور عادية، الأسرع والأقل تكلفة | | `nano-banana-2-lite` | 0.14 | نموذج صور خفيف Gemini 3.1، يدعم فقط 1K، زمن استجابة منخفض | | `nano-banana-2` | 0.28 | جودة وتفاصيل محسنة بشكل ملحوظ | | `nano-banana-pro` | 0.35 | الرائد في السلسلة، أفضل في التركيب، التفاصيل، والنصوص | > **مهم: نطاق دعم المعلمات** > Nano Banana متصل عبر طبقة التكيف مع بروتوكول OpenAI، مقارنةً بـ `gpt-image-*`، يدعم فقط المعلمات التالية: `model`، `prompt`، `size`. > > * سيتم تحويل `size` وفقًا للجدول أدناه إلى `aspect_ratio` داخلي، الأحجام غير المدرجة ستتحول إلى `1:1`: > * `1024x1024` / `512x512` / `256x256` → `1:1` > * `1792x1024` → `16:9` > * `1024x1792` → `9:16` > * لا تدعم المعلمات `n`، `quality`، `style`، `response_format`، `background`، `output_format`، وما إلى ذلك؛ إذا تم إدخالها، سيتم تجاهلها. > * هيكل الاستجابة يتبع تنسيق OpenAI (`data[].url`)، لكن `created` ثابت عند `0`، ولن يتم إرجاع `b64_json`، و`revised_prompt` دائمًا يساوي `prompt` الأصلي. ### الاستدعاء الأساسي ```python theme={null} import requests url = "https://api.acedata.cloud/openai/images/generations" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "model": "nano-banana", "prompt": "تفاحة حمراء صغيرة على طاولة بيضاء، فوتوغرافية", "size": "1024x1024" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` النتيجة كما يلي: ```json theme={null} { "created": 0, "data": [ { "url": "https://platform.cdn.acedata.cloud/nanobanana/6870b330-65c4-436c-bb80-819fdae7a7a4.png", "revised_prompt": "تفاحة حمراء صغيرة على طاولة بيضاء، فوتوغرافية" } ] } ``` يمكن الوصول إلى الصورة المولدة مباشرة من خلال حقل `url` المعاد:

### الترقية إلى النموذج الرائد `nano-banana-pro` ما عليك سوى تغيير `model` إلى `nano-banana-pro`، مع بقاء بقية المعلمات كما هي: ```python theme={null} payload = { "model": "nano-banana-pro", "prompt": "لوحة تجريدية", "size": "1024x1024" } ``` مثال على الاستجابة: ```json theme={null} { "created": 0, "data": [ { "url": "https://platform.cdn.acedata.cloud/nanobanana/6227fcc9-3442-4aa3-a76c-4a4441a99649.png", "revised_prompt": "لوحة تجريدية" } ] } ```

### استدعاء غير متزامن آلية استدعاء `callback_url` غير المتزامن فعالة أيضًا مع nano-banana، وتدفق الاستدعاء متطابق تمامًا مع النماذج الأخرى، انظر القسم أدناه [استدعاء غير متزامن](#استدعاء-غير-متزامن). ## الاستخدام الأساسي يمكنك الآن ملء المحتوى المقابل في الواجهة، كما هو موضح في الصورة:

عند استخدام هذه الواجهة لأول مرة، نحتاج على الأقل إلى ملء ثلاثة محتويات، أحدها هو `authorization`، يمكنك اختياره مباشرة من القائمة المنسدلة. المعلمة الأخرى هي `model`، حيث أن `model` هو نوع النموذج الذي نختار استخدامه من موقع OpenAI DALL-E، وهنا لدينا نموذج واحد رئيسي، يمكنك الاطلاع على النماذج التي نقدمها. المعلمة الأخيرة هي `prompt`، حيث أن `prompt` هو الكلمة المفتاحية التي ندخلها لتوليد الصورة. يمكنك أيضًا ملاحظة وجود كود استدعاء مطابق على الجانب الأيمن، يمكنك نسخ الكود وتشغيله مباشرة، أو يمكنك النقر على زر "Try" للاختبار.

كود استدعاء Python كمثال: ```python theme={null} import requests url = "https://api.acedata.cloud/openai/images/generations" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "model": "dall-e-3", "prompt": "أوتير بحرية صغيرة لطيفة" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` بعد الاستدعاء، نجد أن النتيجة المعادة كما يلي: ```json theme={null} { "created": 1721626477, "data": [ { "revised_prompt": "صورة رائعة تعرض أوتير بحرية صغيرة، ولدت بلون بني، مع عيون ساحرة واسعة. إنها مستلقية بشكل رائع على ظهرها، تتجدف في مياه البحر الهادئة. يبدو فراؤها الكثيف والناعم مبللاً ولامعًا، مما يعكس جوهر موطنها. الكائن الصغير يلعب بفضول مع صدفة بحرية باستخدام كفوفه الصغيرة، ويبدو بريئًا وساحرًا تمامًا في بيئته الطبيعية.", "url": "https://dalleprodsec.blob.core.windows.net/private/images/5d98aa7c-80c6-4523-b571-fc606ad455b9/generated_00.png?se=2024-07-23T05%3A34%3A48Z&sig=GAz%2Bi3%2BkHOQwAMhxcv22tBM%2FaexrxPgT9V0DbNrL4ik%3D&ske=2024-07-23T08%3A41%3A10Z&skoid=e52d5ed7-0657-4f62-bc12-7e5dbb260a96&sks=b&skt=2024-07-16T08%3A41%3A10Z&sktid=33e01921-4d64-4f8c-a055-5bdaffd5e33d&skv=2020-10-02&sp=r&spr=https&sr=b&sv=2020-10-02" } ] } ``` تتضمن النتيجة المعادة عدة حقول، كما هو موضح أدناه: * `created`، معرف الصورة المولدة، يستخدم لتحديد هذه المهمة بشكل فريد. * `data`، يحتوي على معلومات نتائج توليد الصورة. حيث أن `data` تحتوي على معلومات محددة حول الصورة المولدة، ورابط `url` هو رابط التفاصيل للصورة المولدة، كما هو موضح في الصورة.

## معلمة جودة الصورة `quality` سنقوم الآن بشرح كيفية إعداد بعض المعلمات التفصيلية لنتائج توليد الصورة، حيث تحتوي معلمة جودة الصورة `quality` على نوعين، الأول `standard` يشير إلى توليد صورة قياسية، والآخر `hd` يشير إلى أن الصورة المولدة تحتوي على تفاصيل أكثر دقة وتناسق أكبر. سنقوم بتعيين معلمة جودة الصورة إلى `standard`، الإعداد المحدد كما هو موضح في الصورة أدناه:

يمكنك أيضًا ملاحظة وجود كود استدعاء مطابق على الجانب الأيمن، يمكنك نسخ الكود وتشغيله مباشرة، أو يمكنك النقر على زر "Try" للاختبار.

كود استدعاء Python كمثال: ```python theme={null} import requests url = "https://api.acedata.cloud/openai/images/generations" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "model": "dall-e-3", "prompt": "أوتير بحرية صغيرة لطيفة", "quality": "standard" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` بعد الاستدعاء، نجد أن النتيجة المعادة كما يلي: ```json theme={null} { "created": 1721636023, "data": [ { "revised_prompt": "أوتير بحرية صغيرة لطيفة مستلقية بشكل مرح على ظهرها في الماء، مع فراء يبدو لامعًا وناعمًا. واحدة من كفوفها الصغيرة تمتد بفضول، ولديها تعبير عن الفرح والدفء على وجهها وهي تنظر إلى السماء. جسمها محاط بف bubbles من دورانها المرح في الماء. نسيم لطيف يلعب مع فرائها مما يجعلها تبدو أكثر سحرًا. المشهد يعكس هدوء وسحر الحياة البحرية.", "url": "https://dalleprodsec.blob.core.windows.net/private/images/a93ee5e7-3abd-4923-8d79-dc9ef126da46/generated_00.png?se=2024-07-23T08%3A13%3A55Z&sig=wTXGYvUOwUIkaB2CxjK9ww%2FHjS8OwYUWcYInXYKwcAM%3D&ske=2024-07-23T11%3A32%3A05Z&skoid=e52d5ed7-0657-4f62-bc12-7e5dbb260a96&sks=b&skt=2024-07-16T11%3A32%3A05Z&sktid=33e01921-4d64-4f8c-a055-5bdaffd5e33d&skv=2020-10-02&sp=r&spr=https&sr=b&sv=2020-10-02" } ] } ``` تتوافق النتيجة المعادة مع محتوى الاستخدام الأساسي، ويمكنك رؤية الصورة المولدة بمعلمة جودة الصورة `standard` كما هو موضح في الصورة أدناه:

与上述相同操作，仅需将图片质量参数设置为 `hd` ，可以得到如下图所示的图片：

可以看到 `hd` 比 `standard` 生成的图片具有更精细的细节和更大的一致性。 ## 图片大小尺寸参数 `size` 我们还可以设置生成图片的尺寸大小，我们可以进行下面的设置。 下面设置图片的尺寸大小为 `1024 * 1024` ，具体设置如下图：

同时您可以注意到右侧有对应的调用代码生成，您可以复制代码直接运行，也可以直接点击「Try」按钮进行测试。

Python 样例调用代码： ```python theme={null} import requests url = "https://api.acedata.cloud/openai/images/generations" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "model": "dall-e-3", "prompt": "A cute baby sea otter" "size": "1024x1024" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` 调用之后，我们发现返回结果如下： ```json theme={null} { "created": 1721636652, "data": [ { "revised_prompt": "A delightful depiction of a baby sea otter. The small mammal is captured in its natural habitat in the ocean, floating on its back. It has thick brown fur that is sleek and wet from the sea water. Its eyes are closed as if it is enjoying a moment of deep relaxation. The water around it is calm, reflecting the peacefulness of the scene. The background should hint at a diverse marine ecosystem, with visible strands of kelp floating on the surface, suggesting the baby otter's preferred environment.", "url": "https://dalleprodsec.blob.core.windows.net/private/images/9d625ac6-fd2b-42a9-84a6-8c99eb357ccf/generated_00.png?se=2024-07-23T08%3A24%3A24Z&sig=AXtYXowEakGxfRp8LhC2DwqL%2F07LhEDW40oCP%2BdTO8s%3D&ske=2024-07-23T18%3A00%3A45Z&skoid=e52d5ed7-0657-4f62-bc12-7e5dbb260a96&sks=b&skt=2024-07-16T18%3A00%3A45Z&sktid=33e01921-4d64-4f8c-a055-5bdaffd5e33d&skv=2020-10-02&sp=r&spr=https&sr=b&sv=2020-10-02" } ] } ``` 返回的结果与基本使用的内容一致，可以看到图片的尺寸大小为 `1024 * 1024` 的生成图片如下图所示：

与上述相同操作，仅需将图片的尺寸大小为 `1792 * 1024` ，可以得到如下图所示的图片： ![](https://cdn.acedata.cloud/4pilae.png) 可以看到图片的尺寸大小很明显不一样，另外还可以设置更多尺寸大小，详情信息参考我们官网文档。 ## 图片风格参数 `style` 图片风格参数 `style` 包含俩个参数，第一种 `vivid` 表示生成的图片是更加生动的，另一种 `natural` 表示生成的图片更加的自然一点。 下面设置图片风格参数为 `vivid` ，具体设置如下图：

同时您可以注意到右侧有对应的调用代码生成，您可以复制代码直接运行，也可以直接点击「Try」按钮进行测试。

Python 样例调用代码： ```python theme={null} import requests url = "https://api.acedata.cloud/openai/images/generations" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "model": "dall-e-3", "prompt": "A cute baby sea otter", "style": "vivid" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` 调用之后，我们发现返回结果如下： ```json theme={null} { "created": 1721637086, "data": [ { "revised_prompt": "A baby sea otter with soft, shiny fur and sparkling eyes floating playfully on calm ocean waters. This adorable creature is trippingly frolicking amidst small, gentle waves under a bright, clear, sunny sky. The tranquility of the sea contrasts subtly with the delightful energy of this young otter. The critter gamely clings to a tiny piece of driftwood, its small paws adorably enveloping the floating object.", "url": "https://dalleprodsec.blob.core.windows.net/private/images/6e48f701-7fd3-4356-839e-a2f6f0fe82d9/generated_00.png?se=2024-07-23T08%3A31%3A37Z&sig=4percxqTbUR1j3BQmkhvj%2FAhHzInKI%2FqiTo1MP69coI%3D&ske=2024-07-27T10%3A39%3A55Z&skoid=e52d5ed7-0657-4f62-bc12-7e5dbb260a96&sks=b&skt=2024-07-20T10%3A39%3A55Z&sktid=33e01921-4d64-4f8c-a055-5bdaffd5e33d&skv=2020-10-02&sp=r&spr=https&sr=b&sv=2020-10-02" } ] } ``` 返回的结果与基本使用的内容一致，可以看到图片风格参数为 `vivid` 的生成图片如下图所示：

与上述相同操作，仅需将图片风格参数为 `natural` ，可以得到如下图所示的图片：

可以看到 `vivid` 比 `natural` 生成的图片具有更加生动逼真。 ## 图片链接的格式参数 `response_format` 最后一个图片链接的格式参数 `response_format` 也有俩种，第一种 `b64_json` 是对图片链接进行 Base64 编码，另一种 `url` 就是普通的图片链接，可以直接查看图片。 下面设置图片链接的格式参数为 `url` ，具体设置如下图：

同时您可以注意到右侧有对应的调用代码生成，您可以复制代码直接运行，也可以直接点击「Try」按钮进行测试。

Python 样例调用代码： ```python theme={null} import requests url = "https://api.acedata.cloud/openai/images/generations" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "model": "dall-e-3", "prompt": "عجل بحر لطيف", "response_format": "url" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` بعد الاستدعاء، وجدنا أن النتيجة كانت كما يلي: ```json theme={null} { "created": 1721637575, "data": [ { "revised_prompt": "صورة ساحرة لعجل بحر صغير. يُرى العجل وهو يستريح بهدوء على ظهره وسط الأمواج الزرقاء اللطيفة. فراء العجل الصغير مزيج جذاب من درجات البني الرمادي الناعم، يلمع برفق في ضوء الشمس الخافت. يلمس كفاه الصغيرتان، مرفوعتان قليلاً نحو السماء كما لو كانا يلعبان مع شيء غير مرئي. عيونه الدائرية المعبرة واسعة بدافع الفضول، تتلألأ بالحياة والبراءة. استخدم أسلوباً واقعياً لاستحضار موطن العجل الطبيعي ومظهره الخارجي الرقيق بشكل جذاب.", "url": "https://dalleprodsec.blob.core.windows.net/private/images/87792c5f-8b6d-412e-81dd-f1a1baa19bd2/generated_00.png?se=2024-07-23T08%3A39%3A47Z&sig=zzRAn30TqIKHdLVqZPUUuSJdjCYpoJdaGU6BeoA76Jo%3D&ske=2024-07-23T13%3A32%3A13Z&skoid=e52d5ed7-0657-4f62-bc12-7e5dbb260a96&sks=b&skt=2024-07-16T13%3A32%3A13Z&sktid=33e01921-4d64-4f8c-a055-5bdaffd5e33d&skv=2020-10-02&sp=r&spr=https&sr=b&sv=2020-10-02" } ] } ``` تتوافق النتيجة مع المحتوى الأساسي المستخدم، ويمكن رؤية أن رابط الصورة بتنسيق المعامل `url` هو رابط الصورة المولدة [رابط الصورة](https://dalleprodsec.blob.core.windows.net/private/images/87792c5f-8b6d-412e-81dd-f1a1baa19bd2/generated_00.png?se=2024-07-23T08%3A39%3A47Z\&sig=zzRAn30TqIKHdLVqZPUUuSJdjCYpoJdaGU6BeoA76Jo%3D\&ske=2024-07-23T13%3A32%3A13Z\&skoid=e52d5ed7-0657-4f62-bc12-7e5dbb260a96\&sks=b\&skt=2024-07-16T13%3A32%3A13Z\&sktid=33e01921-4d64-4f8c-a055-5bdaffd5e33d\&skv=2020-10-02\&sp=r\&spr=https\&sr=b\&sv=2020-10-02) وهذا يمكن الوصول إليه مباشرة، ومحتوى الصورة كما هو موضح في الصورة أدناه:

مع نفس العملية المذكورة أعلاه، يكفي تغيير تنسيق رابط الصورة إلى `b64_json` للحصول على نتيجة رابط الصورة المشفرة بـ Base64، والنتيجة المحددة كما هو موضح في الصورة أدناه: ```json theme={null} { "created": 1721638071, "data": [ { "b64_json": "iVBORw0..............v//AQEAAP4AAAD+AAADAQAAAwEEA/4D//8Q/Pbw64mKbVTFoQAAAABJRU5ErkJggg==", "revised_prompt": "صورة ساحرة لعجل بحر صغير. العجل يطفو برفق على بحر أزرق هادئ، يستمتع بأشعة الشمس الذهبية الدافئة المتدفقة من سماء صافية فوقه. فراء العجل بني غامق غني، ويبدو ناعماً ورقيقاً للغاية. عيون العجل مشرقة ومعبرة، مليئة بالفضول والفرح الطفولي. لديه آذان صغيرة منتصبة وأنف يشبه الزر مما يضيف إلى جاذبيته العامة. في البحر من حوله، يمكن رؤية قطرات الماء المتلألئة، التي تضيء بأشعة الشمس، المنظر بالتأكيد رائع." } ] } ``` ## ردود غير متزامنة نظرًا لأن واجهة برمجة تطبيقات OpenAI Images Generations قد تستغرق وقتًا طويلاً لتوليد الصور، إذا لم يكن هناك استجابة من واجهة برمجة التطبيقات لفترة طويلة، ستظل طلبات HTTP متصلة، مما يؤدي إلى استهلاك موارد النظام الإضافية، لذا توفر هذه الواجهة أيضًا دعمًا للردود غير المتزامنة. تتمثل العملية العامة في: عند بدء العميل الطلب، يتم تحديد حقل `callback_url` إضافي، بعد أن يقوم العميل بإرسال طلب API، ستقوم الواجهة بإرجاع نتيجة على الفور، تحتوي على معلومات حقل `task_id`، الذي يمثل معرف المهمة الحالي. عند الانتهاء من المهمة، سيتم إرسال نتيجة توليد الصورة إلى `callback_url` المحدد من قبل العميل بتنسيق POST JSON، والذي يتضمن أيضًا حقل `task_id`، بحيث يمكن ربط نتيجة المهمة من خلال المعرف. دعونا نفهم كيفية القيام بذلك من خلال مثال. أولاً، يعد Webhook ردًا يمكنه استقبال طلبات HTTP، يجب على المطور استبداله بعنوان URL الخاص بخادم HTTP الذي قام بإنشائه. هنا، لتسهيل العرض، نستخدم موقع ويب عينة Webhook عام [https://webhook.site/،](https://webhook.site/،) عند فتح هذا الموقع، ستحصل على عنوان URL لـ Webhook، كما هو موضح في الصورة: ![](https://cdn.acedata.cloud/cjjfly.png) انسخ هذا العنوان URL، يمكنك استخدامه كـ Webhook، والعينة هنا هي `https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab`. بعد ذلك، يمكننا تعيين حقل `callback_url` إلى عنوان URL الخاص بـ Webhook المذكور أعلاه، مع ملء المعلمات المناسبة، كما هو موضح في الكود التالي: ```python theme={null} import requests url = "https://api.acedata.cloud/openai/images/generations" headers = { "accept": "application/json", "authorization": "Bearer {token}", "content-type": "application/json" } payload = { "model": "dall-e-3", "prompt": "عجل بحر لطيف", "callback_url": "https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab" } response = requests.post(url, json=payload, headers=headers) print(response.text) ``` عند النقر على التشغيل، يمكنك أن ترى أنك ستحصل على نتيجة على الفور، كما يلي: ```json theme={null} { "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c" } ``` بعد لحظة، يمكننا ملاحظة نتيجة توليد الصورة على عنوان URL الخاص بـ Webhook، المحتوى كما يلي: ```json theme={null} { "success": true, "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c", "trace_id": "9b4b1ff3-90f2-470f-b082-1061ec2948cc", "data": { "created": 1721626477, "data": [ { "revised_prompt": "صورة رائعة تعرض عجل بحر صغير...", "url": "https://dalleprodsec.blob.core.windows.net/private/images/..." } ] } } ``` يمكنك أن ترى أن النتيجة تحتوي على حقل `task_id`، وحقل `data` يحتوي على نفس نتائج توليد الصورة كما في الاستدعاء المتزامن، من خلال حقل `task_id` يمكن ربط المهمة. ## معالجة الأخطاء عند استدعاء واجهة برمجة التطبيقات، إذا واجهت أخطاء، ستقوم الواجهة بإرجاع رمز الخطأ والمعلومات ذات الصلة. على سبيل المثال: * `400 token_mismatched`：طلب غير صالح، ربما بسبب معلمات مفقودة أو غير صالحة. * `400 api_not_implemented`：طلب غير صالح، ربما بسبب معلمات مفقودة أو غير صالحة. * `401 invalid_token`：غير مصرح، رمز التفويض غير صالح أو مفقود. * `429 too_many_requests`：عدد كبير جداً من الطلبات، لقد تجاوزت حد المعدل. * `500 api_error`：خطأ في الخادم الداخلي، حدث خطأ ما على الخادم. ### أمثلة على استجابة الخطأ ```json theme={null} { "success": false, "error": { "code": "api_error", "message": "fetch failed" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## الاستنتاج من خلال هذه الوثيقة، لقد تعرفت على كيفية استخدام واجهة برمجة تطبيقات OpenAI Images Generations بسهولة لاستخدام وظيفة توليد الصور الرسمية من OpenAI DALL-E. نأمل أن تساعدك هذه الوثيقة في التوصيل واستخدام هذه الواجهة بشكل أفضل. إذا كان لديك أي استفسارات، فلا تتردد في الاتصال بفريق الدعم الفني لدينا.