> ## 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.

# دليل تكامل واجهة API للاستعلام عن مهام MiniMax H3

> Minimax API guide - Ace Data Cloud

تقدم هذه المقالة تكامل واستخدام واجهة API للاستعلام عن مهام MiniMax H3. تُستخدم هذه الواجهة للاستعلام عن المهام غير المتزامنة التي تم إنشاؤها بواسطة [واجهة API لتوليد فيديو MiniMax H3](https://platform.acedata.cloud/documents/minimax-videos-integration)، أو سردها دفعةً واحدة أو حذفها.

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

لاستخدام واجهة API للاستعلام عن مهام MiniMax H3، انتقل أولاً إلى [لوحة تحكم Ace Data Cloud](https://platform.acedata.cloud/console/applications) للحصول على API Token الخاص بك، واحتفظ به للاستخدام لاحقًا.

![](https://cdn.acedata.cloud/dvc3cg.jpg)

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

**يمكن لـ API Token واحد استدعاء جميع خدمات المنصة، ولا حاجة للتقديم بشكل منفصل لكل خدمة.** سيُمنحك رصيد مجاني عند أول تقديم، ويمكنك التجربة مجانًا؛ وعندما لا يكون الرصيد كافيًا، يمكنك شحن الرصيد العام في [لوحة التحكم](https://platform.acedata.cloud/console/coin).

> 📘 الوثائق الكاملة: [واجهة API للاستعلام عن مهام MiniMax H3 →](https://platform.acedata.cloud/documents/minimax-tasks-integration)

عند الاستعلام عن مهمة، يجب استخدام نفس Token الذي أنشأ تلك المهمة. يُوصى بحفظ Token كمتغير بيئة، وعدم كتابته في الشفرة المصدرية أو إرساله إلى مستودع الإصدارات:

```bash theme={null}
export ACEDATACLOUD_API_KEY="YOUR_API_KEY"
```

## نظرة عامة على الواجهة

* **Base URL**: `https://api.acedata.cloud`
* **Endpoint**: `POST /minimax/tasks`
* **طريقة المصادقة**: تضمين `authorization: Bearer {token}` في HTTP Header
* **رؤوس الطلب**:
  * `accept: application/json`
  * `content-type: application/json`
* **الاستعلام عن مهمة واحدة**: `action=retrieve`، مع تمرير `id`
* **الاستعلام عن المهام دفعةً واحدة**: `action=retrieve_batch`، ويمكن التصفية حسب معرّف المهمة ونطاق الوقت وشروط الترقيم
* **حذف مهمة**: `action=delete`، مع تمرير `id`
* **ملاحظات الفوترة**: الاستعلام عن المهام مجاني ولا ينتج عنه فوترة مكررة

يجب حفظ `task_id` بعد إنشاء الفيديو. يُوصى بالاستعلام مرة كل 10 ثوانٍ تقريبًا، حتى تدخل المهمة في حالة نهائية.

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

| المعلمة | النوع | مطلوب | الإجراء المطبق | الوصف |
| - | - | - | - | - |
| `action` | string | لا | الكل | `retrieve` أو `retrieve_batch` أو `delete`؛ الافتراضي هو `retrieve` |
| `id` | string | مطلوب بشروط | `retrieve`، `delete` | معرّف مهمة واحدة |
| `ids` | string\[] | لا | `retrieve_batch` | يعيد فقط معرّفات المهام المحددة؛ وعند حذفه تُدرج المهام وفقًا للشروط الأخرى |
| `limit` | integer | لا | `retrieve_batch` | الحد الأقصى لعدد المهام المعادة هذه المرة |
| `offset` | integer | لا | `retrieve_batch` | عدد المهام التي يتم تجاوزها من قائمة النتائج، ويُستخدم للترقيم |
| `created_at_min` | number | لا | `retrieve_batch` | الحد الأدنى لوقت الإنشاء، طابع زمني Unix، بوحدة الثواني |
| `created_at_max` | number | لا | `retrieve_batch` | الحد الأقصى لوقت الإنشاء، طابع زمني Unix، بوحدة الثواني |

استخدامات الإجراءات الثلاثة هي كما يلي:

| `action` | الاستخدام | المعلمات المطلوبة | بنية الاستجابة |
| - | - | - | - |
| `retrieve` | الاستعلام عن حالة ونتيجة مهمة واحدة | `id` | `{ "task": {...} }` |
| `retrieve_batch` | الاستعلام عن المهام دفعةً واحدة حسب معرّف المهمة والوقت وشروط الترقيم | اختياري: `ids`، نطاق الوقت، `offset`، `limit` | `{ "items": [...], "total": number }` |
| `delete` | إلغاء أو حذف سجل المهمة وفقًا للحالة الحالية للمهمة | `id` | `{ "id": "...", "deleted": true }` |

## الاستعلام عن مهمة واحدة

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/minimax/tasks' \
  -H "Authorization: Bearer $ACEDATACLOUD_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "action": "retrieve",
    "id": "f5977217-ed2c-40da-adbe-93d08235618f"
  }'
```

فيما يلي استجابة لمهمة ناجحة حقيقية:

```json theme={null}
{
  "task": {
    "id": "f5977217-ed2c-40da-adbe-93d08235618f",
    "model": "MiniMax-H3",
    "status": "succeeded",
    "created_at": 1786184658,
    "updated_at": 1786184758,
    "content": {
      "url": "https://cdn.acedata.cloud/assets/examples/minimax/f5977217-ed2c-40da-adbe-93d08235618f-b080c998dde2.mp4"
    },
    "resolution": "768P",
    "duration": 4,
    "usage": {
      "total_seconds": 4,
      "input_seconds": 0,
      "output_seconds": 4,
      "input_image_count": 0
    },
    "ratio": "16:9",
    "task_type": "generation",
    "modality": "video"
  }
}
```

[فتح نتيجة الفيديو الحقيقية لهذه المهمة](https://cdn.acedata.cloud/assets/examples/minimax/f5977217-ed2c-40da-adbe-93d08235618f-b080c998dde2.mp4)

## حالات المهمة

| `status` | المعنى | معالجة العميل |
| - | - | - |
| `queued` | دخل قائمة الانتظار، بانتظار التنفيذ | مواصلة الاستطلاع |
| `running` | قيد التوليد | مواصلة الاستطلاع |
| `succeeded` | تم التوليد بنجاح | قراءة `task.content.url`، وإيقاف الاستطلاع |
| `failed` | فشل التوليد | قراءة `task.error`، وإيقاف الاستطلاع |
| `cancelled` | تم إلغاء المهمة | إيقاف الاستطلاع |

تُعد `succeeded` و`failed` و`cancelled` جميعها حالات نهائية. لا تواصل الاستطلاع بعد الدخول في حالة نهائية.

## حقول استجابة task

| الحقل | النوع | الوصف |
| - | - | - |
| `id` | string | معرّف المهمة |
| `model` | string | النموذج المستخدم في المهمة، وهو حاليًا `MiniMax-H3` |
| `status` | string | حالة المهمة الحالية |
| `error.code` | string | رمز خطأ الفشل، يُعاد فقط عند الفشل |
| `error.message` | string | سبب الفشل، يُعاد فقط عند الفشل |
| `created_at` | integer | وقت الإنشاء، طابع زمني Unix، بوحدة الثواني |
| `updated_at` | integer | وقت آخر تحديث للحالة، طابع زمني Unix، بوحدة الثواني |
| `content.url` | string | عنوان الفيديو بعد النجاح |
| `resolution` | string | دقة الإخراج، `768P` أو `2K` |
| `duration` | integer | مدة فيديو الإخراج، بوحدة الثواني |
| `usage.total_seconds` | integer | إجمالي كمية الفوترة، يساوي مجموع ثواني فيديو الإدخال وثواني الإخراج |
| `usage.input_seconds` | integer | كمية الفوترة الناتجة عن إدخال الفيديو المرجعي |
| `usage.output_seconds` | integer | كمية الفوترة الناتجة عن فيديو الإخراج |
| `usage.input_image_count` | integer | عدد صور الإدخال في إحصاءات الفوترة |
| `ratio` | string | نسبة العرض إلى الارتفاع الفعلية للإخراج؛ عند استخدام `adaptive` تكون النتيجة هنا هي المعتمدة |
| `task_type` | string | مهمة توليد الفيديو هي `generation` |
| `modality` | string | مهمة الفيديو هي `video` |

## مثال كامل للاستعلام الدوري في Python

يقرأ الكود التالي Token من متغيرات البيئة، وبعد إنشاء المهمة يستعلم مرة كل 10 ثوانٍ:

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

import requests

BASE_URL = "https://api.acedata.cloud"
HEADERS = {
    "Authorization": f"Bearer {os.environ['ACEDATACLOUD_API_KEY']}",
    "Content-Type": "application/json",
}

create_response = requests.post(
    f"{BASE_URL}/minimax/videos",
    headers=HEADERS,
    json={
        "model": "MiniMax-H3",
        "content": [
            {
                "type": "text",
                "text": "清晨的海边，一艘白色帆船驶过平静海面，镜头缓慢横移",
            }
        ],
        "resolution": "768P",
        "duration": 4,
        "ratio": "16:9",
    },
    timeout=30,
)
create_response.raise_for_status()
task_id = create_response.json()["task_id"]

while True:
    time.sleep(10)
    query_response = requests.post(
        f"{BASE_URL}/minimax/tasks",
        headers=HEADERS,
        json={"action": "retrieve", "id": task_id},
        timeout=30,
    )
    query_response.raise_for_status()
    task = query_response.json()["task"]
    print(f"task={task_id} status={task['status']}")

    if task["status"] == "succeeded":
        print(f"video_url={task['content']['url']}")
        break
    if task["status"] in ("failed", "cancelled"):
        raise RuntimeError(task.get("error") or task["status"])
```

ينبغي في بيئة الإنتاج تعيين مهلة إجمالية للاستعلام الدوري، واستخدام التراجع الأُسّي مع `429` و`5xx` المؤقتة. مهلة الشبكة لا تعني فشل الإنشاء، ويمكن متابعة الاستعلام باستخدام `task_id` نفسه.

## الاستعلام الدفعي

حدّد عدة معرّفات للمهام:

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/minimax/tasks' \
  -H "Authorization: Bearer $ACEDATACLOUD_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "action": "retrieve_batch",
    "ids": ["TASK_ID_1", "TASK_ID_2"],
    "offset": 0,
    "limit": 20
  }'
```

اعرض المهام على صفحات وفق نطاق زمني:

```json theme={null}
{
  "action": "retrieve_batch",
  "created_at_min": 1786000000,
  "created_at_max": 1786200000,
  "offset": 0,
  "limit": 20
}
```

تستخدم `items` في الاستجابة الدفعية حقول task نفسها المستخدمة في استعلام المهمة المفردة، ويمثل `total` العدد الإجمالي للمهام المطابقة لشروط التصفية:

```json theme={null}
{
  "items": [
    {
      "id": "TASK_ID_1",
      "model": "MiniMax-H3",
      "status": "running",
      "resolution": "2K",
      "duration": 5,
      "ratio": "adaptive",
      "task_type": "generation",
      "modality": "video"
    }
  ],
  "total": 1
}
```

نافذة الاستعلام عن المهام هي آخر 7 أيام. قد يعيد `task_id` الذي يتجاوز هذه النافذة مهمة غير صالحة؛ ينبغي لنظام الأعمال حفظ المعرّف عند إنشاء المهمة، وحفظ عنوان URL للنتيجة بشكل دائم في الوقت المناسب بعد النجاح.

## إلغاء المهام أو حذفها

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/minimax/tasks' \
  -H "Authorization: Bearer $ACEDATACLOUD_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "action": "delete",
    "id": "YOUR_TASK_ID"
  }'
```

يعتمد الإجراء على الحالة الحالية للمهمة:

| الحالة الحالية | السلوك |
| - | - |
| `queued` | إلغاء مهمة لم تبدأ بعد |
| `succeeded` | حذف سجل المهمة |
| `failed` | حذف سجل المهمة |
| `running` | لا يُسمح بالحذف أو الإلغاء، ويُعاد خطأ |
| `cancelled` | لا يُسمح بتكرار العملية، ويُعاد خطأ |

مثال على نجاح الحذف:

```json theme={null}
{
  "id": "YOUR_TASK_ID",
  "deleted": true
}
```

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

## استجابات الفشل واستكشاف الأخطاء وإصلاحها

تُعيد المهام الفاشلة كائن task باستخدام HTTP 200 أيضًا، وتوفر السبب في `task.error`:

```json theme={null}
{
  "task": {
    "id": "YOUR_TASK_ID",
    "model": "MiniMax-H3",
    "status": "failed",
    "error": {
      "code": "1026",
      "message": "video description contains sensitive content"
    },
    "task_type": "generation",
    "modality": "video"
  }
}
```

عندما تعيد الواجهة نفسها `400`، ينبغي التحقق من `action` ومعلمات الشروط؛ يشير `401` إلى أن Token غير صالح، ويشير `429` إلى أن الاستعلامات متكررة جدًا، ويشير `500` إلى أن الخدمة غير متاحة مؤقتًا. لا تتم فوترة المهام التي يفشل إنشاؤها؛ وتُسجل استخدامات المهام الناجحة وفق `usage` النهائي.


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