واجهة برمجة تطبيقات الذكاء الاصطناعي التوليدي للمطورين: توقف عن طرح إخفاقات "ناجحة"

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

تتيح واجهة برمجة تطبيقات الذكاء الاصطناعي التوليدي للمطوّرين لتطبيقك إرسال المدخلات إلى نموذج واستقبال المحتوى المولَّد. اختر واحدة بناءً على المدخلات المطلوبة وتنسيق المخرجات وزمن الانتظار ومعايير القبول. ثم ابنِ آليات إدارة المهام والفحوصات التي تحوّل الاستجابة إلى شيء يمكن للمستخدم استخدامه.

يتابع هذا الدليل سير عمل الصور من الاختيار حتى التسليم. وستجد جدولًا لاختيار المهمة، وأمثلة متطابقة بلغتي JavaScript وPython، و3 مواصفات صور ملموسة، وورقة عمل للتكاليف. وتنطبق عملية القرار نفسها على النصوص والفيديو، مع بروتوكولات وفحوصات مخرجات مختلفة.

أهم النقاط

• اختر المهمة ومعايير القبول قبل النموذج.
• احفظ معرّفات المهام غير المتزامنة حتى يمكن استئناف العمل المتوقف.
• قِس التكلفة لكل مخرج مقبول، بما في ذلك التوليدات المرفوضة.
• اختبر الملفات وقيود العمل قبل عرض النتيجة النهائية.

واجهة برمجة تطبيقات الذكاء الاصطناعي التوليدي للمطوّرين: ما الذي تفعله

النموذج هو من ينفّذ التوليد. أما واجهة برمجة التطبيقات فتحدّد كيفية طلب برنامجك لهذا العمل. وتغلّف مجموعة أدوات التطوير (SDK) الواجهة بمساعدة خاصة بكل لغة. وتشغّل المنصة المستضافة الوصول إلى النماذج، بينما يوفّر تطبيقك تجربة المستخدم والأذونات وقواعد قبول النتيجة.

تكتسب هذه الفروق أهمية عند قراءة صفحة منتج. فوجود تطبيق محادثة يُنشئ صورًا لا يثبت أن نقطة نهاية المطوّر فيه تقبل المدخلات نفسها. كما أن وجود طريقة سهلة في مجموعة أدوات التطوير لا يلغي الحاجة إلى فهم الاستجابة الأساسية وحالات الفشل.

ابدأ بخريطة المهام التالية. يصف عمود التفاعل تصميمًا تطبيقيًا يستحق التقييم، وليس وعدًا بأن كل مزوّد يدعم هذا النمط.

توليد صورة وتحليل صورة مرفوعة وتحرير صورة موجودة قدرات منفصلة. تحقّق من كل واحدة منها صراحةً. وبالمثل، قد تدعم نقطة نهاية الفيديو إطارًا ابتدائيًا دون دعم مراجع متعددة الصور العشوائية.

تحوّل التضمينات المدخلات إلى متجهات مفيدة للاسترجاع والتشابه. ويمكنها المساعدة في العثور على مستندات ذات صلة قبل توليد الإجابة. لكنها لا تنتج الإجابة بنفسها ولا تثبت أن المحتوى المُسترجَع يدعم ادعاءاتها.

الحد العملي هو: المدخل ← الطلب ← المخرج ← قبول التطبيق. وأنت تملك المرحلة الأخيرة. فحقل الفاتورة المولَّد لا يزال يحتاج إلى تحقق؛ والصورة لا تزال تحتاج إلى فحص؛ ورد الدعم لا يزال يحتاج إلى إذن لتقديم الوعد الذي يتضمنه.

تختلف خيارات البروتوكول أيضًا. فمرجع Google يميّز بين التوليد القياسي والبثّي والتفاعل المباشر. اعتبر ذلك دليلًا على أن أنماط التفاعل تختلف، بدلًا من افتراض دعم مطابق في مكان آخر. (مرجع Google Gemini API، تم الاطلاع عليه في سبتمبر 2026.)

واجهة برمجة تطبيقات الذكاء الاصطناعي التوليدي للمطوّرين: كيف تختار

اكتب مواصفات قبول موجزة قبل مقارنة الكتالوجات. فبالنسبة لميزة صورة تحريرية، قد تحدّد مخرجًا أفقيًا، وعددًا محدودًا من العناصر، ودون علامة تجارية ظاهرة، وخطوة مراجعة بشرية. وبالنسبة لتصنيف التذاكر، قد تحدّد مجموعة تصنيفات ثابتة ونتيجة "غير مؤكدة" صريحة.

قيّم المرشحين بهذا الترتيب:

1. المدخلات والمخرجات. تحقّق من نقطة نهاية النموذج المحددة بحثًا عن الملفات المدعومة وحدود الإدخال وتنسيقات المخرجات وسلوك الصورة المرجعية. فاسم عائلة النموذج أوسع من أن يصلح كعقد.
2. الالتزام بالمهمة. جرّب مواصفات تمثيلية، بما في ذلك الصعبة منها. واحسب حالات فشل القيود بشكل منفصل عن أعطال الملفات أو الشبكة لتعرف ما يحتاج إلى إصلاح.
3. ملاءمة التكامل. تأكّد من المصادقة، وأغلفة الاستجابة، وقيم حالة المهمة، ودعم مكتبة العميل. وأدرج العمل اللازم لتكييف هذه العناصر مع الواجهة الخلفية لديك.
4. زمن الانتظار والتزامن. قرّر ما إذا كان يمكن للمستخدمين المغادرة والعودة. واختبر عبء العمل المتوقع قبل الالتزام بتجربة تفاعلية ذات مهلة قصيرة.
5. وضوح الفوترة. حدّد الوحدة القابلة للفوترة والإعدادات التي تغيّرها. وتحقق من معالجة الفشل والاسترداد بدلًا من افتراض أن كل طلب مُقدَّم يتلقى الرسوم نفسها.
6. متطلبات البيانات. راجع طريقة التعامل مع المدخلات والاحتفاظ بها وحذفها والشروط المنطبقة مقابل البيانات الفعلية التي تنوي إرسالها. ووثّق الأسئلة غير المحلولة قبل استخدام مواد حساسة.
7. إدارة التغيير. احتفظ بمجموعة اختبارات انحدار وسجّل معرّفات النماذج والموجّهات والمعاملات. وخطط لكيفية إعادة تقييم السلوك بعد تحديث أو استبدال.

توضّح الإرشادات المؤسسية سبب انتماء قواعد الوصول والبيانات إلى هذا القرار: إذ تصف جامعة هارفارد مسارات الوصول المعتمدة والقيود المفروضة على أدوات الذكاء الاصطناعي للمطوّرين لديها. وهذه ترتيبات هارفارد، وليست أذونات عامة لتطبيقك. (Harvard University Information Technology، تم الاطلاع عليه في سبتمبر 2026.)

Atlas Cloud خيار مستضاف يستحق التقييم عندما تنتمي قدرات عدة نماذج إلى التطبيق نفسه. ويستخدم هذا المقال واجهة مهام الصور لديها كمثال ملموس. ومع ذلك، لا تزال بحاجة إلى التحقق من مدخلات ومخرجات كل نموذج؛ فتغيير معرّف النموذج وحده غير كافٍ.

توثيق نقطة نهاية الصور الرسمي يوضّح تنسيق المخرجات والجودة وقيود الحجم

المعاملات الخاصة بكل نموذج جزء من عقد التكامل. اقرأ قيمها المسموح بها قبل إعادة استخدام جسم طلب.

بالنسبة لفريق SaaS صغير، المقارنة المفيدة هي إجمالي الجهد اللازم لتسليم نتيجة مقبولة واحدة. أدرج كود المحوّل، وتحقيقات الدعم، وزمن المراجعة، واختبارات الترحيل إلى جانب رسم الاستدلال. وهذا يمنع نموذجًا أوليًا مريحًا من إخفاء سير عمل إنتاجي مكلف.

واجهة برمجة تطبيقات الذكاء الاصطناعي التوليدي للمطوّرين: الطلب الأول

يستخدم المثال GPT Image 2 Text-to-Image، بمعرّف النموذج openai/gpt-image-2/text-to-image. وتُدرج وثائق نقطة النهاية الخاصة به quality: high وsize: 2048x1152 وoutput_format: png. وهذه هي الإعدادات المطلوبة للأمثلة أدناه.

1. أنشئ الموجّه في الملعب التجريبي. استخدم مواصفات الإفطار أدناه دون إضافة صورة مرجعية. تحقّق من اسم النموذج والإعدادات المثبَّتة قبل الضغط على Run. فالاختيار الذي يعود إلى وضعه السابق عند مغادرة حقل ليس الإعداد الذي طلبته.

plaintextCopy
1Create a realistic editorial food photograph for an article about a simple breakfast.
2
3On a light oak table, show exactly one white ceramic plate holding exactly two slices of toasted sourdough bread, one small clear glass bowl of strawberry jam, and one stainless steel butter knife resting to the right of the plate.
4
5Use soft morning window light from the left, natural colors, a three-quarter overhead camera angle, and realistic bread texture. Keep every requested object fully inside the frame.
6
7No people, no hands, no drinks, no extra dishes, no packaging, no logos, no text, and no watermark. Landscape composition, 16:9.

2. أبقِ المصادقة على الخادم. ينبغي أن تطلب واجهتك الأمامية من الواجهة الخلفية الخاصة بك بدء مهمة. خزّن ATLAS_API_KEY في بيئة الخادم. ولا تضمّنه أبدًا في JavaScript المتصفح أو عناوين URL للصور أو السجلات الظاهرة للعميل. اضبط ATLAS_API_HOST على api.atlascloud.ai؛ فهذا اسم مضيف، دون مخطط أو مسار.

3. أرسل الطلب مرة واحدة واحفظ المعرّف. مسار التوليد الموثّق هو POST /api/v1/model/generateImage. اقرأ data.id، ثم احفظه مقترنًا بمهمة تطبيقك. وإذا فُقدت استجابة الإرسال، فحقّق قبل إنشاء مهمة أخرى قد تكون قابلة للفوترة.

4. استعلم دوريًا عن المهمة المحفوظة. نفّذ GET /api/v1/model/prediction/{prediction_id}. وتصف وثائق التنبؤات الحالات processing وcompleted وfailed، مع عناوين URL للمخرجات في data.outputs. وينبغي مع حالة الاكتمال التحقق أيضًا من وجود مصفوفة مخرجات غير فارغة.

5. نزّل الملف وتحقق منه. احفظ الملف تحت سيطرتك، وتأكد من أنه يُفكّ ترميزه، وافحصه مقابل المواصفات. وعندها فقط أعِد نتيجة مقبولة إلى التطبيق. وينبغي أن يبقى خطأ التنزيل أو التحقق مرتبطًا بالمهمة القائمة.

الكود التالي مُجمَّع من وثائق الواجهة الرسمية. وهو غير مقدَّم كقياس أداء حيّ لواجهة برمجة التطبيقات. ويستخدم سير عمل الوسائط في هذا المقال الملعب التجريبي في المتصفح، وليس مفتاح API.

احفظ موجّه الإفطار كما هو في ملف باسم prompt.txt. وبالنسبة إلى Node.js، استخدم بيئة تتضمن fetch مدمجًا، وثبّت sharp، واحفظ هذا الملف باسم generate.mjs. شغّله في دليل عمل مخصص. ولا تشغّل سوى واحد من مثالي اللغتين إلا إذا كنت تريد عمدًا إنشاء مهمتين.

javascriptCopy
1import { readFile, writeFile, mkdir } from 'node:fs/promises';
2import sharp from 'sharp';
3
4const key = process.env.ATLAS_API_KEY;
5const host = process.env.ATLAS_API_HOST;
6if (!key || host !== 'api.atlascloud.ai') {
7  throw new Error('Set ATLAS_API_KEY and ATLAS_API_HOST');
8}
9const base = 'https:' + '//' + host;
10const headers = { Authorization: `Bearer ${key}` };
11const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
12const payload = {
13  model: 'openai/gpt-image-2/text-to-image',
14  prompt: await readFile('prompt.txt', 'utf8'),
15  quality: 'high', size: '2048x1152', output_format: 'png'
16};
17await mkdir('output', { recursive: true });
18await writeFile('output/request.json', JSON.stringify(payload, null, 2));
19
20async function api(path, method = 'GET', body) {
21  const response = await fetch(base + path, {
22    method,
23    headers: { ...headers, 'Content-Type': 'application/json' },
24    body: body ? JSON.stringify(body) : undefined,
25    signal: AbortSignal.timeout(30000)
26  });
27  const requestId = response.headers.get('x-request-id');
28  console.error(JSON.stringify({ method, status: response.status, requestId }));
29  if (!response.ok) {
30    const error = new Error(`HTTP ${response.status}; request ${requestId}`);
31    error.retryable = [429, 500, 503, 504].includes(response.status);
32    throw error;
33  }
34  const json = await response.json();
35  if (!json.data) throw new Error('Missing response data');
36  return json.data;
37}
38
39let id = process.env.PREDICTION_ID;
40try {
41  if (!id) {
42    // Deliberately no automatic retry for submission.
43    const submitted = await api('/api/v1/model/generateImage', 'POST', payload);
44    id = submitted.id;
45    if (typeof id !== 'string' || !id) throw new Error('Missing prediction ID');
46    await writeFile('output/prediction-id.txt', id);
47  }
48  const deadline = Date.now() + 600000;
49  let errors = 0;
50  let outputUrl;
51  while (Date.now() < deadline) {
52    let job;
53    try {
54      job = await api('/api/v1/model/prediction/' + encodeURIComponent(id));
55      errors = 0;
56    } catch (error) {
57      const transient = error.retryable ||
58        ['TimeoutError', 'AbortError'].includes(error.name) ||
59        error instanceof TypeError;
60      if (!transient || ++errors > 3) throw error;
61      await sleep(Math.min(30000, 1000 * 2 ** errors) + Math.random() * 500);
62      continue;
63    }
64    if (job.status === 'failed') {
65      throw new Error(`Task failed; code ${job.error_code ?? 'unknown'}`);
66    }
67    if (job.status === 'completed') {
68      outputUrl = job.outputs?.[0];
69      if (typeof outputUrl !== 'string' || !outputUrl) {
70        throw new Error('Completed task has no output');
71      }
72      break;
73    }
74    if (job.status !== 'processing') throw new Error('Unexpected task status');
75    await sleep(2000);
76  }
77  if (!outputUrl) throw new Error('Polling deadline reached; resume this ID');
78  const url = new URL(outputUrl);
79  if (url.protocol !== 'https:') throw new Error('Unexpected output protocol');
80  // Do not forward the API credential to the media host.
81  const file = await fetch(url, { signal: AbortSignal.timeout(60000) });
82  if (!file.ok) throw new Error(`Download HTTP ${file.status}`);
83  const bytes = Buffer.from(await file.arrayBuffer());
84  await sharp(bytes, { limitInputPixels: 20000000 }).raw().toBuffer();
85  const meta = await sharp(bytes).metadata();
86  if (meta.format !== 'png' || meta.width !== 2048 || meta.height !== 1152) {
87    throw new Error('File format or dimensions differ from the request');
88  }
89  await writeFile('output/breakfast.png', bytes);
90  console.log(JSON.stringify({ id, state: 'ready_for_review',
91    file: 'output/breakfast.png' }));
92} catch (error) {
93  console.error(JSON.stringify({ id: id ?? null, state: 'needs_attention',
94    error: error.message }));
95  process.exitCode = 1;
96}

المكافئ الأقصر بلغة Python يستخدم requests وPillow، وملف prompt.txt نفسه، والإعدادات ذاتها. ويقبل أيضًا PREDICTION_ID للاستئناف. توضّح هذه النصوص البرمجية مهمة محلية واحدة؛ أما الخدمة المنشورة فتحتاج إلى سجلات مهام دائمة وتنزيلات محدودة.

pythonCopy
1import io, json, os, random, time
2from pathlib import Path
3from urllib.parse import quote, urlparse
4import requests
5from PIL import Image
6
7key = os.environ['ATLAS_API_KEY']
8assert os.environ['ATLAS_API_HOST'] == 'api.atlascloud.ai'
9base = 'https:' + '//' + os.environ['ATLAS_API_HOST']
10headers = {'Authorization': 'Bearer ' + key}
11out = Path('output')
12out.mkdir(exist_ok=True)
13payload = dict(model='openai/gpt-image-2/text-to-image',
14               prompt=Path('prompt.txt').read_text(encoding='utf-8'),
15               quality='high', size='2048x1152', output_format='png')
16job_id = os.getenv('PREDICTION_ID')
17try:
18    if not job_id:
19        # A submission timeout needs investigation, not a blind retry.
20        r = requests.post(base + '/api/v1/model/generateImage',
21                          headers=headers, json=payload, timeout=30)
22        r.raise_for_status()
23        job_id = r.json()['data']['id']
24        if not isinstance(job_id, str) or not job_id:
25            raise ValueError('Missing prediction ID')
26        (out / 'prediction-id.txt').write_text(job_id)
27    deadline, errors, url = time.monotonic() + 600, 0, None
28    while time.monotonic() < deadline:
29        try:
30            r = requests.get(base + '/api/v1/model/prediction/' +
31                             quote(job_id, safe=''), headers=headers, timeout=30)
32            r.raise_for_status()
33        except requests.RequestException as exc:
34            status = exc.response.status_code if exc.response is not None else None
35            if status not in (None, 429, 500, 503, 504) or errors >= 3:
36                raise
37            errors += 1
38            time.sleep(min(30, 2 ** errors) + random.random() / 2)
39            continue
40        errors = 0
41        job = r.json()['data']
42        if job['status'] == 'failed':
43            raise RuntimeError('Task failed: ' + str(job.get('error_code')))
44        if job['status'] == 'completed':
45            outputs = job.get('outputs') or []
46            if not outputs or not isinstance(outputs[0], str) or not outputs[0]:
47                raise ValueError('Completed task has no output')
48            url = outputs[0]
49            break
50        if job['status'] != 'processing':
51            raise ValueError('Unexpected task status')
52        time.sleep(2)
53    if not url:
54        raise TimeoutError('Polling deadline reached; resume this ID')
55    if urlparse(url).scheme != 'https':
56        raise ValueError('Unexpected output protocol')
57    r = requests.get(url, timeout=60)  # No Authorization header here.
58    r.raise_for_status()
59    with Image.open(io.BytesIO(r.content)) as image:
60        image.load()
61        if image.format != 'PNG' or image.size != (2048, 1152):
62            raise ValueError('Unexpected file format or dimensions')
63    (out / 'breakfast.png').write_bytes(r.content)
64    print(json.dumps(dict(id=job_id, state='ready_for_review')))
65except Exception as exc:
66    print(json.dumps(dict(id=job_id, state='needs_attention', error=str(exc))))
67    raise SystemExit(1)

جولة مكتملة في الملعب التجريبي لـ GPT Image 2 تُظهر موجّه الإفطار المُرسَل والمخرج النهائي

تسجّل جولة مكتملة في الملعب الموجّه المُرسَل وحجم المخرجات وإعداد الجودة والنتيجة المولَّدة معًا.

مهلة الاستعلام الدوري توقف انتظار هذا العميل؛ لكنها لا تلغي العمل من جهة الخادم. فالطلب الذي هو قيد التنفيذ قد ينتهي بعد نافذة الاستعلام الدوري، لذا لا يُعد هذا ضمانًا صارمًا لزمن الاستجابة من طرف إلى طرف. احفظ المعرّف واسمح لعامل بفحصه لاحقًا.

واجهة برمجة تطبيقات الذكاء الاصطناعي التوليدي للمطوّرين: الاستخدامات العملية

تختبر المواصفات الثلاث أدناه متطلبات مختلفة. وهي طلبات مستقلة، وليست سلسلة يصبح فيها نتيجة ما مدخلًا لما بعدها. أبقِ النموذج نفسه والإعدادات المطلوبة ذاتها حتى يبقى من السهل فهم الفروق بين المواصفات.

أ. صورة طعام تحريرية: العدد والموضع. يختبر موجّه الإفطار ما إذا كان المخرج يحتوي على شريحتين من الخبز المحمّص، وطبق واحد، ووعاء مربى واحد، وسكين واحدة. ويجب أن تكون السكين على يمين الطبق، وأن تبقى جميع العناصر المطلوبة داخل الإطار.

مثال على توليد صورة إفطار مقترن بفحص عدد العناصر وموضع السكينsThe نتيجة التوليد تحتوي على الطبق والخبز المحمّص ووعاء المربى والسكين على اليمين، جاهزة لمراجعة الموضع أدناه.

افحص الشرائح المتداخلة كلًا على حدة. فقد تفشل صورة إفطار مقنعة بصريًا إذا ظهر كوب في الخلفية أو انتقلت السكين إلى الطبق. وإذا فشلت نتيجة، فعدّل التعليمات المكانية الغامضة، وغيّر متغيرًا واحدًا، واحتفظ بسبب الرفض. وتجنّب الطلب المتكرر للحصول على صورة أفضل عمومًا.

ب. غلاف مقال: مساحة قابلة للاستخدام للعنوان. يتعامل هذا الطلب مع التكوين كاعتماد على التخطيط. يحتاج محرّر الصفحة إلى مساحة فارغة على اليسار، بينما يحمل الجانب الأيمن الأدوات والأصيص. أضف العنوان الفعلي لاحقًا باستخدام HTML/CSS ليبقى قابلًا للتحرير وسهل القراءة.

plaintextCopy
1Create a realistic editorial photograph for an article about repairing everyday objects.
2
3On the right half of a light wooden workbench, show one pair of worn gardening gloves, one small metal hand trowel, and one unbranded terracotta plant pot. The left 45 percent of the image must remain an empty, softly lit section of the same workbench, suitable for adding a headline later.
4
5Use natural side light from a nearby window, believable material textures, neutral colors, and a slightly elevated camera angle.
6
7No people, no hands, no extra tools, no plants, no logos, no letters, no text, and no watermark. Landscape composition, 16:9.

مثال على غلاف طاولة عمل يُظهر مساحة العنوان المطلوبة على اليسار والعناصر على اليمين

تحافظ النتيجة على مساحة فارغة قابلة للاستخدام على اليسار مع إبقاء القفازات والأصيص والمجرفة الصغيرة على اليمين.

افحص النتيجة عند الاقتصاص المنشور المقصود. فقد تفقد النسخة الأصلية الأفقية منطقتها الفارغة المفيدة عندما يقتصّ بطاقة الجوال مركزيًا. وإذا فشل التكوين، فحدّد حدودًا أضيق للعناصر أو غيّر اقتصاص التطبيق. ولا تُخفِ الفشل بوضع نص فوق العناصر المطلوبة.

ج. رسم توضيحي للأقمشة: التفصيل والترتيب. يطلب الطلب التالي 3 عيّنات مطوية ذات ملمس مرئي يمكن تمييزه. وهو يختبر العدد والموضع وما إذا كانت النتيجة تدعم رسمًا توضيحيًا عند الحجم الذي سيراه القرّاء.

plaintextCopy
1Create a realistic close-up editorial photograph for an article explaining common fabric textures.
2
3Show exactly three folded fabric swatches arranged side by side on a neutral matte gray surface: natural beige linen on the left, blue cotton denim in the center, and dark green wool on the right.
4
5Use the same soft daylight across all three fabrics, an overhead camera angle, and sufficient depth of field to keep the visible weave of each fabric in focus. Preserve natural wrinkles and believable fiber detail.
6
7No labels, no rulers, no sewing tools, no hands, no additional objects, no text, no logos, and no watermark. Landscape composition, 16:9.

رسم توضيحي للأقمشة مولَّد بالذكاء الاصطناعي مع فحوصات موضع العيّنات البيج والأزرق والأخضر الداكن

العيّنات الثلاث المطلوبة متميزة بصريًا. وهذا الملمس المولَّد رسم توضيحي، وليس دليلًا على تركيب ألياف منتج حقيقي.

إذا افتقرت العيّنة الوسطى إلى نسيج واضح، فسجّل تلك المشكلة واضبط التأطير أو تعليمات التفصيل. ولا تصف أبدًا الملمس المولَّد كخاصية مقيسة لمنتج حقيقي.

تحتاج ميزات النصوص إلى فحوصات ضيقة مماثلة. فبالنسبة لتصنيف التذاكر، ارفض التصنيفات خارج المجموعة المسموح بها واحتفظ بمسار "غير مؤكد". وبالنسبة لاستخراج المستندات، اطلب الحقول ونطاقات المصدر إلى جانب JSON قابل للتحليل. فالاستجابة الصحيحة نحويًا قد تضع مع ذلك المبلغ الخطأ في الحقل الخطأ.

واجهة برمجة تطبيقات الذكاء الاصطناعي التوليدي للمطوّرين: معالجة حالات الفشل

تتبّع نجاح النقل، واكتمال المهمة، والقبول من ناحية العمل، كلًا على حدة. فقد تحتوي استجابة HTTP ناجحة على مهمة قيد المعالجة. وقد تنتج مهمة مكتملة تنزيلًا معطوبًا. وقد تنتهك صورة قابلة للقراءة المواصفات. وكل حالة تحتاج إلى إجراء استرداد مختلف.

اضبط 3 مؤقتات عن قصد: مهلة HTTP فردية، وفاصل استعلام دوري، ونافذة انتظار إجمالية. تستخدم الأمثلة مهلة 30 ثانية لطلب API، واستعلامًا دوريًا كل ثانيتين، ونافذة استعلام مدتها 10 دقائق. وهذه خيارات تطبيقية، وليست أداءً معلنًا للخدمة.

تشير وثائق أخطاء المنصة الحالية إلى أن نقاط نهاية LLM والوسائط لا توفّر ترويسة Retry-After أو ترويسات حد المعدل المتبقي. استخدم سياسة تأخير من جهة العميل؛ ولا تجعل الاسترداد معتمدًا على ترويسة لا تُعيدها هذه المسارات. وقد تتصرف عائلات أخرى من واجهات API بشكل مختلف.

أبقِ إعادات المحاولة التلقائية للقراءة محدودة. وتساعد التأخيرات الأسية مع قدر صغير من التذبذب العشوائي على منع كثير من العمال من إعادة المحاولة في الوقت نفسه. وقلّل التزامن إذا استمر تقييد المعدل. وينبغي أن تتحول الإخفاقات المتكررة إلى حادثة قابلة للملاحظة بدلًا من حلقة لا نهاية لها مخفية خلف مؤشر تحميل.

تستحق إعادات محاولة الإرسال معاملة أكثر صرامة. فعندما يُغلق الاتصال بعد إرسال الجسم، قد لا تعرف ما إذا كان الخادم قد أنشأ مهمة. سجّل نية محلية قبل الإرسال، وحقّق في سجل الطلبات أو آثار الدعم عند عدم وصول معرّف تنبؤ. ولا تخترع ترويسة idempotency ما لم توثّقها نقطة النهاية.

بعد حصولك على معرّف، استخدمه للاستئناف. وينبغي أن يؤدي فشل التنزيل إلى محاولة تنزيل أخرى أو فحص للحالة، لا إلى طلب آخر لتوليد صورة. وتُبقي الأمثلة عن قصد سلوك إعادة المحاولة التلقائية على قراءات الاستعلام الدوري وتتوقف عند إرسال فاشل.

احتفظ لكل مهمة بمعرّف المهمة في تطبيقك، ومعرّف التنبؤ، ومعرّفات الطلبات، والنموذج، والإعدادات، والطوابع الزمنية، والنتيجة النهائية. ولا تخزّن الموجّهات إلا وفق سياسة بيانات مناسبة. ولا تضع أبدًا ترويسات التخويل أو محتوى المستخدم الحساس في سجلات الأخطاء العامة.

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

واجهة برمجة تطبيقات الذكاء الاصطناعي التوليدي للمطوّرين: التكاليف الفعلية

لا يخبرك سعر الطلب المنخفض بتكلفة ميزة قابلة للاستخدام. فميزانيتك تحتاج إلى المبلغ المفوتر، وعدد المخرجات المقبولة، والعمل الداعم المطلوب لتسليمها.

تفرّق واجهات النصوص عادةً بين رموز الإدخال ورموز الإخراج. ويمكن أن يسهم السياق الطويل والمقاطع المُسترجَعة وسجل المحادثة والاستجابات المتكررة في الاستخدام. سجّل الفئات التي تحاسب عليها نقطة النهاية المختارة فعليًا بدلًا من تطبيق تقدير واحد للرموز على كل عبء عمل.

بالنسبة للصور، افحص وحدة الفوترة والإعدادات الخاصة بالنموذج بالضبط. وقد يؤثر الحجم والجودة في الفوترة بشكل مختلف بين النماذج. وبالنسبة للفيديو، يمكن أن تغيّر المدة والدقة واختيار النموذج الرسوم. ولا تحوّل سعر البداية في الكتالوج إلى عرض سعر لإعداد معيّن.

لم يتم التحقق خلال إعداد هذا المقال من السعر الدقيق للنموذج الصوري المختار بجودة عالية ودقة 2048 × 1152 عبر الكتالوج وصفحة التفاصيل معًا. ولا يُؤكَّد هنا أي سعر وحدة أو خصم حالي. تأكد منه قبل إجراء تقييم إنتاجي مدفوع.

استخدم حسابين مرتبطين:

plaintextCopy
1API cost per accepted output = actual API charges / accepted outputs
2
3Full feature cost per accepted output =
4(API charges + attributable review + storage + transfer + processing costs)
5/ accepted outputs

أبقِ فترة الملاحظة متسقة. وبالنسبة للتخزين المستمر، حدّد ما إذا كان الحساب يغطي الشهر الأول، أو فترة احتفاظ محددة، أو تكلفة متكررة مخصصة. وتجنّب مقارنة رقم نموذج يقتصر على الاستدلال مع التكلفة الكاملة لسير عمل آخر.

مثال افتراضي: تُرسل 100 طلب وتقبل 80 مخرجًا. اقسم إجمالي الرسوم الفعلية لتلك الدفعة على 80. وإذا فُوترة جميع الطلبات المئة بالمبلغ نفسه c، فستكون تكلفة API لكل مخرج مقبول 1.25c. وهذا الشرط مهم: فهو لا يفترض أن كل طلب فاشل يُفوتر.

استخدم هذا كورقة عمل، لا كجدول نتائج. فالعروض التوضيحية للصور لا تثبت معدل قبول تمثيليًا أو تكلفة إنتاجية. وأبقِ عروض الأسعار من الملعب منفصلة عن سجلات الفوترة النهائية، خصوصًا عند التقييم في بيئة اختبار.

عندما تكون المخرجات المقبولة صفرًا، فأبلغ عن الدفعة بأنها غير ناجحة واعرض إجمالي الإنفاق. وتكون نسبة التكلفة لكل مخرج مقبول غير معرّفة في هذه الحالة. وإخفاء الدفعات الفاشلة سيجعل ميزانيتك تبدو أفضل مما يتصرف به التطبيق.

قلّل الهدر أولًا: تحقّق من المدخلات قبل الإرسال، واحفظ معرّفات المهام، وامنع التكرار العرضي، وأعد استخدام الأصول المقبولة عندما يسمح المنتج بذلك. ثم قارن الإعدادات الأرخص على المواصفات والفحوصات نفسها. فقد يزيد إعداد يخفّض عرض السعر لكنه يضاعف عمل الرفض من تكلفة الميزة.

واجهة برمجة تطبيقات الذكاء الاصطناعي التوليدي للمطوّرين: اختبر المخرج، لا الاستجابة فقط

اكتب معايير القبول أثناء صياغة الموجّه. فهذا يمنع صورة مقنعة من تغيير تعريفك للنجاح بعد وقوع الأمر. وأبقِ المتطلبات الصارمة منفصلة عن التفضيلات الاختيارية، وسجّل سبب رفض المراجع لنتيجة ما.

أتمِت الفحوصات التي لها إجابات ميكانيكية واضحة: نجاح التنزيل، وفك ترميز الملف، والتنسيق، والأبعاد، وحدود حجم الملف. وبالنسبة إلى JSON، تحقق من المخطط والحقول المطلوبة والتصنيفات المسموح بها والأنواع. ولا ينبغي أن يتحول حقل مطلوب مفقود بهدوء إلى قيمة افتراضية مُختلقة.

استخدم المراجعة البشرية للمتطلبات التي تحتاج إلى تفسير. ففي مثال الإفطار، يجب على المراجع أن يميّز الشرائح المتداخلة، ويتعرّف على السكين، ويقيّم موضعها، ويبحث عن عناصر إضافية. وقد يساعد مدقّق الرؤية الآلي، لكن قيّم أخطاءه قبل أن تتركه يعتمد النتائج وحده.

ينبغي أن تتضمن مراجعة الإفطار الفحوصات المستقلة التالية:

• شريحتا خبز محمّص بالضبط، وطبق أبيض واحد، ووعاء مربى شفاف واحد، وسكين واحدة.
• السكين على يمين الطبق؛ والعناصر المطلوبة داخل الإطار بالكامل.
• لا أكواب أو أطباق أو أيدٍ أو تغليف إضافي، ولا علامة تجارية ظاهرة.
• ملف PNG قابل للقراءة بالأبعاد المطلوبة.

سجل تحقق يفصل فحوصات بيانات الملف الوصفية عن فحوصات القبول البصري

يعرض السجل الأبعاد والحجم الفعليين للملف المولَّد بشكل منفصل عن فحوصات القبول البصري.

ابنِ مجموعة انحدار ثابتة من الميزة الفعلية: طلبات عادية، وتكوينات مزدحمة، وتعليمات متعارضة، واقتصاصات صعبة، وحدود إدخال ذات صلة. وحدّث إصدارات المواصفات وقواعد المراجع. وأعد تشغيلها عند تغيير النموذج أو قالب الموجّه أو إعدادات المخرجات.

أبلغ عن النجاح التقني ومعدل المخرجات المقبولة كلًا على حدة. فالملف القابل للقراءة الذي يحتوي على عنصر إضافي يُحتسب تسليمًا ناجحًا ورفضًا للمحتوى في الوقت ذاته. ودمج هاتين النتيجتين في رقم نجاح واحد يخفي الإصلاح الذي يحتاجه فريقك.

وجد استبيان المطوّرين لعام 2025 أن 46% لا يثقون في دقة أدوات الذكاء الاصطناعي، و33% يثقون بها؛ وأفاد 3% بثقة عالية. وتتعلق هذه الإجابات بأدوات الذكاء الاصطناعي في سير عمل التطوير، وليست معدل فشل مقيسًا لواجهات التوليد. (Stack Overflow Developer Survey، 2025.)

وبالمثل، لا يمكن لثلاث جولات توضيحية أن تثبت الدقة الإجمالية أو زمن استجابة p95 مفيدًا. اجمع عيّنة أكبر وذات صلة عبر الظروف التي تتوقعها في الإنتاج، واحتفظ بالقيم الشاذة. واستخدم العروض التوضيحية لتطوير الفحوصات، ثم استخدم تقييمًا منهجيًا لاتخاذ قرار الإصدار.

واجهة برمجة تطبيقات الذكاء الاصطناعي التوليدي للمطوّرين: قائمة تحقق إنتاجية قبل الإطلاق

لا يحسم أول طلب ناجح سوى جزء صغير من قرار الإطلاق. فعلى تطبيقك أيضًا أن يحدّ من الإنفاق، ويسترد العمل غير المكتمل، ويشرح ما حدث عندما لا تتوفر نتيجة.

احمِ الوصول. أبقِ بيانات الاعتماد على الواجهة الخلفية، وافصل البيئات، وقيّد الوصول إلى سجلات المهام، وخطط لتدوير بيانات الاعتماد. وصرّح كل طلب حالة وتنزيل مقابل المستخدم الذي يملك تلك المهمة. فمعرّف المهمة الذي يصعب تخمينه ليس بديلًا عن فحوصات الأذونات.

قيّد المدخلات واستخدام الموارد. تحقّق من طول الموجّه، ونوع التحميل وحجمه، وإعدادات المخرجات المطلوبة، والتركيبات المدعومة. وبالنسبة للوسائط المنزّلة، فرض الوجهات المسموح بها، وإعادات التوجيه، وحدود البايتات، وحدود فك الترميز. توضّح النصوص البرمجية المختصرة أعلاه دورة الحياة؛ لكنها ليست خدمة تنزيل عامة محصّنة.

حدّد الميزانيات قبل الإرسال. عرّف حدودًا لكل مستخدم ولكل مهمة، والحد الأقصى للمهام المتزامنة، ومن يمكنه طلب إعدادات أكثر تكلفة. واحجز ميزانية أثناء وجود العمل قيد الانتظار حتى لا تتمكن الطلبات المتزامنة جميعها من تجاوز فحص الرصيد المتبقي نفسه.

احفظ الحالة بشكل دائم. اكتب المهمة المحلية قبل استدعاء المزوّد. واحفظ معرّف التنبؤ المُعاد فورًا واجعل الاستعلام الدوري قابلًا للاستئناف بعد إعادة تشغيل العملية. وإذا كانت حالة الإرسال غير معروفة، فاستخدم حالة تحقيق بدلًا من إخبار المستخدمين بأن المهمة فشلت بالتأكيد.

امتلك الأصل المُسلَّم. قرّر أين توجد الملفات المقبولة، ومن يمكنه الوصول إليها، ومتى تنتهي صلاحيتها. وتحقق من عمر رابط المزوّد وشروط الاحتفاظ بدلًا من الاعتماد على عنوان URL مؤقت للمخرجات إلى أجل غير مسمى. وأدرج حذف الملفات المشتقة في سير عمل بيانات التطبيق.

اجعل الفشل مفهومًا. ميّز بين مهمة متأخرة، ونتيجة مرفوضة، وخطأ خدمة. واعرض مسارًا واضحًا لإعادة المحاولة عن قصد أو طلب مراجعة. واحفظ مواصفات المستخدم حتى لا يتطلب الاسترداد إعادة بناء العمل.

راقب التغييرات. تتبّع الاكتمال والقبول والتكلفة وزمن الانتظار كلًا على حدة. وأعد تشغيل مجموعة الانحدار بعد تغييرات النموذج أو المعاملات، وأبقِ الإعداد السابق متاحًا حيثما كان ذلك ممكنًا. وحجب البيانات الحساسة في السجلات وحدّد فترات احتفاظ لكل من سجلات المحتوى والسجلات التشغيلية.

لتقييم المنصة المثال لتطبيقك، ابدأ من كتالوج نماذج Atlas Cloud، ثم اقرأ وثائق نقطة النهاية المختارة والتنبؤات. واختر مهمة واحدة، وحدّد القبول، وسجّل ما يقدّمه التقييم فعليًا قبل توسيع نطاق الوصول.

الأسئلة الشائعة

أي واجهة برمجة تطبيقات ذكاء اصطناعي توليدي ينبغي أن أختار لتطبيقي؟

اختر بناءً على مدخلات الميزة ومخرجاتها وزمن الانتظار المقبول ومتطلبات المراجعة. وشغّل المواصفات التمثيلية نفسها على المرشحين الذين يمكنك استخدامهم قانونيًا وتشغيليًا. وقارن تكلفة المخرجات المقبولة وعمل التكامل إلى جانب القدرات. ولا يوجد اختيار عالمي يثبته أمثلة الصور الثلاثة هذه.

هل توجد واجهات برمجة تطبيقات ذكاء اصطناعي توليدي مجانية للمطوّرين؟

تقدّم بعض الخدمات تجارب أو استخدامًا مجانيًا محدودًا، لكن التوفر والأهلية والحصص والاستخدامات المسموح بها تتغير. تحقّق من الشروط الحالية لنقطة النهاية المحددة. ولا يشمل المخصص المجاني لأداة استهلاكية بالضرورة الوصول إلى API. كما تستهلك الاستضافة الذاتية عتادًا وكهرباء ووقتًا هندسيًا، حتى عندما تكون أوزان النموذج قابلة للتنزيل.

هل أحتاج إلى خبرة في تعلّم الآلة لاستخدام واجهة برمجة تطبيقات ذكاء اصطناعي توليدي؟

يمكنك البدء بمهارات HTTP وJSON والمصادقة وتطوير الواجهة الخلفية العادي. ويتطلب إطلاق ميزة موثوقة إضافةً إلى ذلك عملًا في التقييم والتشغيل. وتحتاج إلى فهم قيود النموذج بما يكفي لتعريف مخرج مقبول، دون أن تدرّب نموذجًا بنفسك بالضرورة.

هل يمكن لواجهة API واحدة التعامل مع النصوص والصور والفيديو؟

قد توفّر منصة القدرات الثلاث جميعها، لكن كل قدرة قد تستخدم نقاط نهاية ومعاملات وأنواع مخرجات وأنماط انتظار مختلفة. تحقّق من كل واجهة على حدة. فالحساب أو بيانات الاعتماد المشتركة لا تجعل جسم طلب نصي متوافقًا مع نموذج صور أو فيديو.

لماذا يعيد طلب الصورة معرّف مهمة بدلًا من صورة؟

ترسل نقطة النهاية العمل بشكل غير متزامن. احفظ المعرّف واستعلم عن مسار الحالة الموثّق. واسترجع الملف عند اكتمال المهمة، ثم تحقق منه. وإذا توقف عميلك عن الانتظار، فقد تكون المهمة من جهة الخادم لا تزال قيد التنفيذ؛ استأنف تلك المهمة قبل إرسال أخرى.

كيف يمكنني تقليل تكاليف API دون إفساد سير العمل؟

امنع الإرسال المكرر، وتحقق من المدخلات مبكرًا، وأعد استخدام الأصول المقبولة حيثما كان مناسبًا، واختبر إعدادات أرخص مقابل معايير قبول غير متغيرة. وقِس الرسوم الفعلية لكل نتيجة مقبولة. وتستحق واجهة برمجة تطبيقات الذكاء الاصطناعي التوليدي للمطوّرين مكانها عندما يستطيع التطبيق المحيط بها تقديم عمل قابل للاستخدام بتكلفة يمكنك تحمّلها.