---
title: البدء السريع | RunAPI
description: أنشئ مهمة غير متزامنة وتعامل مع الاستطلاع والإكمال والفشل وعمليات الاستدعاء.
url: https://runapi.ai/ar/docs/guides/task-api/quickstart.md
canonical: https://runapi.ai/ar/docs/guides/task-api/quickstart
locale: ar
---

> نسخة HTML: https://runapi.ai/ar/docs/guides/task-api/quickstart
> فهرس الموقع للوكلاء: https://runapi.ai/llms.txt

# البدء السريع

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

## إنشاء مهمة

اختر نموذجاً ونقطة نهاية من الكتالوج، ثم أرسل المدخلات المطلوبة
لنقطة النهاية. يبدأ هذا المثال مهمة Flux 2 لتحويل النص إلى صورة:

```shell
curl -X POST "https://runapi.ai/api/v1/flux_2/text_to_image" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Idempotency-Key: 8c8ba3c9-0ce0-4bbd-a9a7-bf59ab639286" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2-pro-text-to-image",
    "prompt": "A product photograph on a clean studio background"
  }'
```

يُرجع طلب غير متزامن مقبول استجابة `202 Accepted` مع معرّف مهمة:

```json
{
  "id": "task_id",
  "status": "processing"
}
```

احفظ `id` مع سجل تطبيقك. إنه المعرّف الثابت
المستخدم للاستطلاع والدعم ومطابقة عمليات الاستدعاء.

## منع إنشاء مهام مكررة

تقبل نقاط النهاية المُنشِئة للمهام ترويسة اختيارية `Idempotency-Key` تحمل قيمة غير شفافة تصل إلى 512 حرفًا. أنشئ قيمة واحدة لكل مهمة منطقية واحتفظ بها مع الطلب حتى تعرف ما إذا كان قد قُبِل.

إذا تركت مهلة الانتظار أو فشل الاتصال النتيجة مجهولة، أعد تجربة نفس طلب إنشاء المهمة بالضبط مع نفس المفتاح. يُعيد RunAPI المهمة الأصلية بدلاً من إنشاء مهمة ثانية وتحصيل رسومها. إعادة استخدام مفتاح مع طلب إنشاء مهمة مختلف يُعيد `409 Conflict`. أنشئ مفتاحاً جديداً لمهمة جديدة متعمدة، ولا تستخدم `X-Client-Request-Id` كهذا المفتاح.

## استرداد طلب متزامن منقطع

تحتفظ الطرف الطرفية المتزامنة البطيئة عادةً بالاتصال مفتوحاً وتُرجع
nفس الاستجابة النهائية كما كانت من قبل. لا تتطلب تغييرات في الاستطلاع
للتكاملات الموجودة.

لميزانية اتصال أقصر بشكل متعمد، أرسل `Prefer: wait=N`.
إذا كانت المهمة لا تزال قيد التشغيل بعد انتهاء تلك الميزانية الصريحة، تُعيد RunAPI `202 Accepted` مع `id` المهمة ذاتها وعنوان URL معتماً `Location` للاسترداد، و`Retry-After` لفاصل الاستعلام المقترح. اتبع `Location` بدقة بدلاً من إنشاء عنوان URL للنتيجة يدوياً. تحتفظ نتيجة المهمة المكتملة بحالة HTTP الطرفية والرؤوس المسموح بها ونوع المحتوى والجسم؛ فكّ ترميز `response.body` وفقاً لـ `response.content_type`، الذي لا يكون دائماً JSON.

## استطلاع حالة مهمة

أضف معرّف المهمة إلى مسار نقطة النهاية ذاتها:

```shell
curl "https://runapi.ai/api/v1/flux_2/text_to_image/task_id" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

استمر طالما أن `status` هو `processing`. استخدم تأخيراً تصاعدياً محدوداً بين
الطلبات بدلاً من الاستطلاع المستمر. تصبح المهمة نهائية عندما تكون
حالتها `completed` أو `failed`.

## معالجة الإكمال

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

## معالجة الفشل

تتضمن استجابة `failed` معرّف المهمة `id` والحالة النهائية `status`
وخطأ `error` من تأليف RunAPI حين يكون متاحاً. أوقف الاستطلاع، وسجِّل
المعرّف والخطأ، وأعد المحاولة فقط حين تُصنِّف تطبيقاتك الفشلَ على أنه
عارض. تُنشئ كل إعادة محاولة معرّف مهمة جديداً.

## استقبال عملية استدعاء

أضف `callback_url` عبر HTTPS عام إلى طلب الإنشاء حين تريد
من RunAPI إرسال أحداث الاستدعاء الموثقة لتلك نقطة النهاية:

```json
{
  "model": "flux-2-pro-text-to-image",
  "prompt": "A product photograph on a clean studio background",
  "callback_url": "https://your-domain.com/webhooks/runapi"
}
```

يتطابق كل استدعاء مع حدث دورة حياة واحد في مرجع API الخاص بنقطة النهاية ويحذف تفاصيل الفوترة الخاصة بالاستطلاع فقط. تتضمن عمليات الاستدعاء الطرفية نفس حقول النتيجة الموجودة في استجابات الاستطلاع الطرفي؛ وترسل بعض نقاط النهاية أيضاً عمليات استدعاء `processing` موثّقة. أعِد استجابة HTTP ناجحة بسرعة وأبقِ الاستطلاع متاحاً للتسوية عند تأخر التسليم أو عدم توفر معالج الاستدعاء لديك.

اقرأ [عمليات الاستدعاء](https://runapi.ai/ar/docs/guides/task-api/callbacks.md) لإنشاء سرّ عملية الاستدعاء والتحقق من التوقيعات ومعالجة عمليات إعادة المحاولة بأمان.

---

## المزيد من RunAPI

- [الرئيسية](https://runapi.ai/ar/.md)
- [كتالوج النماذج](https://runapi.ai/ar/models.md)
- [الأسعار](https://runapi.ai/ar/pricing.md)
- [مزودو الخدمة](https://runapi.ai/ar/models)
- [التوثيق](https://runapi.ai/ar/docs/guides)
- [حزم SDK](https://runapi.ai/ar/sdk.md)
- [CLI](https://runapi.ai/ar/cli.md)
- [خادم MCP](https://runapi.ai/ar/mcp.md)
- [Claude Code مقابل Cursor](https://runapi.ai/ar/claude-code-vs-cursor.md)
- [إعداد Cursor API](https://runapi.ai/ar/cursor-api-setup.md)
- [RunAPI مقابل OpenRouter](https://runapi.ai/ar/openrouter-alternative.md)
- [المؤسسات](https://runapi.ai/ar/contact.md)
- [اتصل بنا](https://runapi.ai/ar/contact.md)
- [الشروط](https://runapi.ai/ar/terms.md)
- [الخصوصية](https://runapi.ai/ar/privacy.md)
- [فهرس الموقع للوكلاء](https://runapi.ai/llms.txt)

التواصل: contact@runapi.ai

## البيانات المنظمة

```json
[
  {
    "@context": "https://schema.org",
    "inLanguage": "ar",
    "@type": "WebSite",
    "name": "RunAPI",
    "url": "https://runapi.ai/ar",
    "potentialAction": {
      "@type": "SearchAction",
      "target": {
        "@type": "EntryPoint",
        "urlTemplate": "https://runapi.ai/ar/models?q={search_term_string}"
      },
      "query-input": "required name=search_term_string"
    }
  },
  {
    "@context": "https://schema.org",
    "inLanguage": "ar",
    "@type": "Organization",
    "name": "RunAPI",
    "url": "https://runapi.ai/ar",
    "logo": {
      "@type": "ImageObject",
      "url": "https://runapi.ai/aricon.svg"
    },
    "sameAs": [
      "https://github.com/runapi-ai"
    ]
  },
  {
    "@context": "https://schema.org",
    "inLanguage": "ar",
    "@type": "TechArticle",
    "headline": "البدء السريع",
    "description": "أنشئ مهمة غير متزامنة وتعامل مع الاستطلاع والإكمال والفشل وعمليات الاستدعاء.",
    "url": "https://runapi.ai/ar/docs/guides/task-api/quickstart",
    "mainEntityOfPage": "https://runapi.ai/ar/docs/guides/task-api/quickstart"
  }
]
```