وثائق واجهة برمجة تطبيقات توليد الصور

توفر KozeAI واجهات لتوليد الصور وتحريرها على غرار OpenAI. تُعيد واجهة الصور تنسيق استجابة صورة موحدًا، ولكن يتم تحديد الحجم والجودة والصورة المرجعية وتنسيق الإخراج المدعوم من النموذج المحدد بواسطة مُهايئ القناة.

المصادقة

يتم التحقق من جميع الطلبات عبر Authorization: Bearer . يُستخدم بعد إنشاء رمز API في وحدة التحكم.

export KOZEAI_API_KEY='sk-your-token'

export KOZEAI_BASE_URL='https://your-kozeai-domain'

API نظرة عامة

يمكن أيضًا استدعاء نموذج الصور عبر

/v1/chat/completions

. ستقوم واجهة الدردشة باستخراج الصور من النصوص والرسائل ثم تحويلها إلى تنسيق واجهة الصور؛ يُنصح باستخدام واجهة الصور المخصصة أعلاه عند الاتصال المباشر. 1. صورة توضيحية

curl '$KOZEAI_BASE_URL/v1/images/generations' \

-H 'Authorization: Bearer $KOZEAI_API_KEY' \

-H 'Content-Type: application/json' \

-d '{

'model': 'gpt-image-1',

'prompt': 'An orange cat sitting by the window, cinematic light and shadow',

'n': 1,

'size': '1024x1024',

'quality': 'auto',

'response_format': 'url'

}

الطلب المعلمات

الطريقة	المسار	نوع المحتوى	الغرض
POST	/v1/images/generations	application/json	الصور المُولّدة من النصوص

المعلمات	النوع	مطلوب	الوصف
model	string	هل	اسم نموذج الصورة. تعتمد النماذج المتاحة فعليًا على النتائج المُعادة من /v1/models.
prompt	string	نعم	وصف محتوى الصورة. يُنصح باستخدام سلسلة نصية غير فارغة. ...
quality	string	No	مستوى الجودة، القيم الشائعة هي: standard، hd، auto، 2k، 4k.
response_format	string	No	القيم الشائعة هي: url أو b64_json.
style	any	No	OpenAI compatible style parameter.
user / user_id	any	No	Caller user identifier.
extra_fields	object	No	Additional structured parameter; تعتمد فعاليته على محول القناة.
output_compression	عدد صحيح	لا	معامل ضغط الإخراج، مدعوم من بعض نماذج صور Codex.
partial_images	عدد صحيح	لا	بعض المعاملات المتعلقة بالصور/البث، مدعومة من بعض نماذج صور Codex.
watermark	قيمة منطقية	لا	مفتاح العلامة المائية، وتعتمد فعاليته على القناة.
watermark_enabled	any	No	متوافق مع بعض معلمات العلامة المائية الأصلية.
image	string/object/array	No	راجع رابط الصورة، أو رابط البيانات، أو كائن الصورة؛ ستدخل بعض القنوات تلقائيًا في عملية التحرير.

مقاسات DALL·E والقيم الافتراضية

dall-e-3

الطراز	المقاس المسموح به القيم	القيم الافتراضية
dall-e-2 / dall-e	256x256، 512x512، 1024x1024	1024x1024
1024x1024، 1024x1792، 1792x1024	1024x1024
gpt-image-1 / gpt-image-2	يُحدد بواسطة النموذج الأساسي	quality=auto

size يجب استخدام أحرف بنصف العرض x، لا تستخدم علامات الضرب ×.

2. تحرير الصور

تستخدم طلبات التحرير القياسية نموذج multipart، مع تسمية حقل الصورة image. يمكن إعادة استخدام صور متعددة باستخدام image أو image[].

curl '$KOZEAI_BASE_URL/v1/images/edits' \
-H 'Authorization: Bearer $KOZEAI_API_KEY' \
-F 'model=gpt-image-1' \
-F 'prompt=Change the background to night scene and retain subject details' \
-F 'image=@./input.png' \
-F 'n=1' \
-F 'quality=standard'

النموذج الشائع الحقول:

الحقل	النوع	الوصف
model	string	نموذج تحرير الصور.
prompt	string	متطلبات التحرير.
image / image[]	file	أدخل صورة، واحدة على الأقل.
mask	file	Mask image; يُستخدم بشكل أساسي في عمليات التحرير المتوافقة مع OpenAI/Codex.
n	عدد صحيح	عدد العناصر المُولَّدة، القيمة الافتراضية 1، النطاق 1-10.
size	نص	حجم أو نسبة الإخراج.
quality	نص	جودة الإخراج.
response_format	string	url أو b64_json، حسب القناة.
watermark	boolean	مفتاح العلامة المائية، حسب القناة.

تدعم بعض القنوات أيضًا طلبات تعديل JSON، مثل تعيين image إلى عنوان URL للبيانات أو عنوان URL للصورة؛ ومع ذلك، تستخدم مسارات تعديل OAuth الخاصة بـ OpenAI وCodex وChatGPT بشكل أساسي multipart.

3. اختلافات القنوات

القناة	سلوكيات إضافية
OpenAI / DALL·E	تم توجيهها بواسطة حقل صورة OpenAI؛ لدى DALL·E تحقق صارم من size.
xAI	size سيتم تحويله إلى aspect_ratio و resolution؛ response_format القيمة الافتراضية هي b64_json. يدعم البرنامج معلمات JSON إضافية مثل aspect_ratio و resolution.
Flow	size يدعم نسب العرض إلى الارتفاع 1:1، 16:9، 9:16، 4:3، و3:4؛ quality=2k/4k يُفعّل عملية تغيير الحجم. يتم تحميل الصور المرجعية عبر image.
Jimeng / Dreamina	size يُستخدم لتعيين نسبة العرض إلى الارتفاع؛ quality=hd سيختار دقة أعلى؛ ستدخل الصورة المرجعية في عملية المزج.
Codex	يدعم أيضًا input_fidelity، mask، stream، output_format، output_compression، partial_images.
ChatGPT OAuth	يستهلك فعليًا model، prompt، n ويُعدّل الصور؛ قد يتم تجاهل معلمات الصور الأخرى.
Grok	response_format يدعم فقط url أو b64_json، والقيمة الافتراضية هي url؛ تتطلب طلبات التعديل صورة واحدة على الأقل.

لا يُضمن تمرير المعلمات غير المُعرّفة في الحقول العامة تلقائيًا. لن تُفعّل إلا المعلمات الإضافية التي يقرأها مُهايئ القناة المُناسب صراحةً.

4. تنسيق الاستجابة

{

"created": 1751000000,

"data": [
{
"url": "https://example.com/generated.png",

"b64_json": "",

"revised_prompt": "قطة برتقالية تجلس بجانب النافذة، إضاءة وظلال سينمائية"

}
]

}

عند استخدام `response_format=b64_json`، يكون محتوى الصورة موجودًا في `data[].b64_json`؛ أما عند استخدام تنسيق URL، فيكون عنوان الصورة موجودًا في `data[].url`. قد تُرجع القنوات المختلفة سلاسل نصية فارغة للحقول غير المستخدمة.

5. مثال على استدعاء جافا سكريبت

const baseURL = process.env.KOZEAI_BASE_URL;

const apiKey = process.env.KOZEAI_API_KEY;


const response = await fetch(`${baseURL}/v1/images/generations`, {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',

},
body: JSON.stringify({
model: 'gpt-image-1',
prompt: 'A minimal product illustration on a white background',
n: 1, size: 1024x1024,

response_format: url,

}),

});

if (!response.ok) {

throw new Error(await response.text());

}
const result = await response.json();

console.log(result.data[0].url || result.data[0].b64_json);

6. الأخطاء الشائعة

• model is required: لم يتم تمرير اسم النموذج.
• prompt is required: كلمة المطالبات فارغة.
• n must be between 1 and 10: تجاوز عدد الأجيال الحد المسموح به.
• size must be one of ...: يستخدم DALL·E حجمًا غير مدعوم.
• image is required: لم تقم واجهة التحرير بتحميل صورة أو توفير مرجع صورة يمكن التعرف عليه.
• unsupported ... response_format: القناة المستهدفة لا تدعم تنسيق الإخراج المطلوب.