> ## 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 Tasks: الاتصال والاستخدام

> OpenAI generation API guide - Ace Data Cloud

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

في نمط الاستدعاء، **ترجع واجهة الصور الأصلية على الفور `task_id` بعد معالجة الطلب**، يمكنك الاحتفاظ بهذا `task_id` واستخدامه للاستعلام في هذه الواجهة عند الحاجة، دون الحاجة إلى تمرير `trace_id` مخصص (فقط إذا كنت ترغب في ربطه بمعرف عملك الخاص).

> سيتم الاحتفاظ بالمهمة فقط إذا كان الطلب الأصلي للصورة يحتوي على `callback_url`. لن يتم تخزين الطلبات التي تم استدعاؤها بطريقة متزامنة (غير استدعائية).

## عملية التقديم

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

يحصل المستخدمون الجدد على حصة مجانية عند التقديم لأول مرة.

## عنوان الواجهة

```
POST https://api.acedata.cloud/openai/tasks
```

الإجراءات المدعومة:

| العملية | الوصف |
| - | - |
| `retrieve` | استعلام عن مهمة واحدة باستخدام `id` أو `trace_id` |
| `retrieve_batch` | استعلام عن مجموعة من المهام باستخدام `ids` / `trace_ids` / `application_id` / `user_id` |

## رأس الطلب

* `accept: application/json`
* `authorization: Bearer {token}`
* `content-type: application/json`

## استعلام عن مهمة واحدة (`retrieve`)

### جسم الطلب

| الحقل | النوع | مطلوب | الوصف |
| - | - | - | - |
| `action` | string | نعم | ثابت كـ `retrieve` |
| `id` | string | إما | معرف المهمة الذي تم إرجاعه في استجابة الطلب المتزامن (يوصى باستخدامه) |
| `trace_id` | string | إما | مطلوب فقط إذا قمت بتمرير `trace_id` مخصص في الطلب الأصلي |

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

### مثال على الكود

#### CURL

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/openai/tasks' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "action": "retrieve",
    "id": "7489df4c-ef03-4de0-b598-e9a590793434"
  }'
```

#### بايثون

```python theme={null}
import requests

url = "https://api.acedata.cloud/openai/tasks"
headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json",
}
payload = {
    "action": "retrieve",
    "id": "7489df4c-ef03-4de0-b598-e9a590793434",
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
```

### مثال على الاستجابة

عند وجود المهمة:

```json theme={null}
{
  "_id": "67a1b2c3d4e5f6a7b8c9d0e1",
  "id": "7489df4c-ef03-4de0-b598-e9a590793434",
  "trace_id": "my-custom-trace-001",
  "type": "images",
  "application_id": "9dec7b2a-1cad-41ff-8536-d4ddaf2525d4",
  "user_id": "5d8e7f6a-1234-4abc-9def-0123456789ab",
  "credential_id": "68253cc8-505d-47f4-97ad-0050a62e4975",
  "created_at": 1763142607.967,
  "started_at": 1763142607.97,
  "finished_at": 1763142637.404,
  "elapsed": 29.437,
  "request": {
    "model": "gpt-image-1",
    "prompt": "A cat sitting on a table",
    "size": "1024x1024",
    "callback_url": "https://your.server/callback"
  },
  "response": {
    "created": 1763142637,
    "data": [
      {
        "url": "https://platform.cdn.acedata.cloud/openai/...png"
      }
    ],
    "success": true
  }
}
```

عند عدم مطابقة أي مهمة، يتم إرجاع كائن فارغ:

```json theme={null}
{}
```

### شرح الحقول

* `id`: معرف المهمة الذي تم إنشاؤه عند معالجة الطلب الأصلي للصورة.
* `trace_id`: معرف التتبع المخصص الذي تم تمريره في الطلب الأصلي، لتسهيل الربط مع الأعمال الخاصة بالعميل.
* `type`: نوع المهمة. المهام المكتوبة في سلسلة `gpt-image` (مثل `gpt-image-2`) تكون من نوع `images`؛ بينما `gpt-image-1`، nano-banana، وما إلى ذلك تستخدم `images_generations` / `images_edits`، وبعض واجهات الدردشة تكون من نوع `chat_completions_image`.
* `request`: جسم الطلب الكامل للطلب الأصلي.
* `response`: جسم الاستجابة النهائية التي تم إرجاعها عند اكتمال الاستدعاء.
* `created_at` / `started_at` / `finished_at`: طوابع زمنية Unix (بالثواني، عائم).
* `elapsed`: الوقت المستغرق للتنفيذ (بالثواني، عائم).
* `application_id` / `user_id` / `credential_id`: معرف التطبيق، المستخدم النهائي، ومعرف الاعتماد.

## الاستعلام الجماعي (`retrieve_batch`)

### جسم الطلب

| الحقل | النوع | الوصف |
| - | - | - |
| `action` | string | ثابت كـ `retrieve_batch` |
| `ids` | string\[] | استعلام باستخدام قائمة معرفات المهام |
| `trace_ids` | string\[] | استعلام باستخدام قائمة `trace_id` |
| `application_id` | string | استعلام عن جميع المهام حسب التطبيق |
| `user_id` | string | استعلام عن جميع المهام حسب المستخدم النهائي |
| `type` | string | تصفية حسب نوع المهمة (القيم: `images`، `images_generations`، `images_edits`) |
| `offset` | int | نقطة البداية للتقسيم، الافتراضي `0` |
| `limit` | int | عدد العناصر في الصفحة الواحدة، الافتراضي `12` |
| `created_at_min` | float | الطابع الزمني الابتدائي (ثواني Unix) |
| `created_at_max` | float | الطابع الزمني النهائي (ثواني Unix) |

يمكن تمرير `ids` / `trace_ids` / `application_id` / `user_id` أو نافذة زمنية `created_at_*` واحدة فقط.

### مثال على CURL

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/openai/tasks' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "action": "retrieve_batch",
    "trace_ids": ["my-trace-001", "my-trace-002"]
  }'
```

### مثال على الاستجابة

```json theme={null}
{
  "items": [
    {
      "_id": "67a1b2c3d4e5f6a7b8c9d0e1",
      "id": "7489df4c-ef03-4de0-b598-e9a590793434",
      "trace_id": "my-trace-001",
      "type": "images",
      "request": {
        "model": "gpt-image-2",
        "prompt": "قطة"
      },
      "response": {
        "data": [
          {
            "url": "https://...png"
          }
        ]
      },
      "created_at": 1763142607.967,
      "started_at": 1763142608.027,
      "finished_at": 1763142637.404,
      "elapsed": 29.377
    }
  ],
  "count": 1
}
```

## مثال شامل: تقديم واستطلاع

تعمل واجهة برمجة التطبيقات للمهام بشكل رئيسي في وضع الاستدعاء في العمليات غير المتزامنة. في وضع الاستدعاء، ستقوم واجهة تقديم الطلبات **بإرجاع `task_id`** (أي معرف المهمة) على الفور، بعد ذلك يمكنك فقط استخدام هذا `task_id` لاستطلاع واجهة المهام، دون الحاجة إلى إنشاء `trace_id` بنفسك.

```python theme={null}
import os, time, requests

API = "https://api.acedata.cloud"
HEADERS = {
    "authorization": f"Bearer {os.environ['ACEDATA_API_KEY']}",
    "content-type": "application/json",
}

# 1. تقديم مهمة توليد صورة (وضع الاستدعاء: مع إضافة callback_url سيتم إرجاع task_id على الفور)
submit = requests.post(
    f"{API}/openai/images/generations",
    headers=HEADERS,
    json={
        "model": "gpt-image-1",
        "prompt": "قطة بأسلوب الألوان المائية جالسة على الطاولة",
        "callback_url": "https://webhook.site/your-uuid",
    },
).json()
print("تم التقديم:", submit)

task_id = submit["task_id"]

# 2. استخدم مباشرة task_id الموجود في استجابة التقديم لاستطلاع واجهة المهام حتى تكتمل المهمة
while True:
    task = requests.post(
        f"{API}/openai/tasks",
        headers=HEADERS,
        json={"action": "retrieve", "id": task_id},
    ).json()
    if task and task.get("response"):
        print("انتهى:", task["response"])
        break
    time.sleep(3)
```

## ملاحظات

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.