الطلبات

الطلب هو استدعاء واحد لنموذج واحد. وله معرّف (req_…) وحالة وتكلفة بأرصدة API (1000 = 1 USD)، وعند نجاحه، الملفات المُنشأة. يعيد كل نقطة نهاية أدناه الكائن نفسه لكل نموذج.

العثور على نموذج#

كتالوج النماذج الـ1,496 الكامل هو JSON عام (لا حاجة إلى مفتاح):

curl "https://api.doitong.com/v1/models?category=text-to-video&lab=Google&limit=20"

يحتوي كل صف على id وname وlab وcategory وfamily وsummary وtags وoutput_kind وdocs_url وكائن price (راجع التسعير). يضيف GET https://api.doitong.com/v1/models/{model_id} مخطط JSON الكامل للمدخل والمخرج، وأسماء المعلمات الأساسية، وقواعد التسعير، ومدخلًا نموذجيًا. تؤدي category أو mode غير المعروفة إلى 400 invalid_parameter.

تشغيل نموذج#

curl -X POST "https://api.doitong.com/v1/run/{model_id}?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1842-cover" \
  -d '{"prompt": "..."}'

• الجسم هو مدخل النموذج، وهو كائن JSON. تسرد صفحة كل نموذج معلماته.
• يُتحقق من المدخل قبل فرض أي تكلفة. يعيد المدخل غير الصالح 422 invalid_input مع param المخالف، ولا يكلّف شيئًا.
• يعلّق ?wait=N (حتى 20 ثانية) الاستدعاء حتى ينتهي الطلب أو ينقضي الوقت.
• يرسل ?webhook_url=https://… طلب POST موقّعًا إلى ذلك العنوان عند انتهاء الطلب (راجع Webhooks).
• يحدد ?storage=permanent أو ?storage=temporary مدة الاحتفاظ بملفات المخرج؛ وبدونه يُطبّق إعداد الحساب (راجع مكان حفظ الملفات).

تكون الاستجابة 202 Accepted ما دام الطلب قيد التنفيذ، و200 OK عند انتهائه ضمن مدة الانتظار (أو عندما يكون إعادة تشغيل، راجع أدناه). تحمل ترويساتا Location وDoitong-Request-Id عنوان الطلب ومعرّفه.

الحالات#

يفشل الطلب الذي يتجاوز حده الزمني بالرمز timeout وتُسترد تكلفته: 15 دقيقة للصور، و60 دقيقة للفيديو، و30 دقيقة للصوت وكل ما عدا ذلك.

كائن الطلب#

{
  "id": "req_8k2m4q7x1z9c3v5b6n0p2r4t",
  "object": "request",
  "model": "flux/schnell",
  "status": "succeeded",
  "created_at": "2026-10-20T12:00:00Z",
  "started_at": "2026-10-20T12:00:01Z",
  "completed_at": "2026-10-20T12:00:02Z",
  "queue_position": null,
  "cost": { "credits": 3, "usd": "0.003", "charged": 3, "refunded": 0 },
  "input": { "prompt": "..." },
  "output": { "images": [ { "url": "https://content.doitong.com/dev-api/…/0-output.jpeg", "width": 1024, "height": 768 } ] },
  "outputs": [
    { "type": "image", "url": "https://content.doitong.com/dev-api/…/0-output.jpeg", "content_type": "image/jpeg",
      "width": 1024, "height": 768, "file_size": 183920, "stored": true }
  ],
  "error": null,
  "metrics": { "inference_seconds": 1.2 },
  "storage": { "mode": "permanent", "bytes": 183920, "expires_at": null, "expired": false },
  "urls": {
    "self": "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t",
    "cancel": "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t/cancel"
  }
}

• تكون outputs متطابقة لكل نموذج: إدخال واحد لكل ملف مُنشأ مع type (image أو video أو audio أو file أو 3d)، وurl على تخزيننا، وcontent_type، وعند معرفتها، file_size وwidth وheight وduration.
• تكون output كائن النتيجة الخاص بالنموذج (تُسرد حقوله في صفحة كل نموذج) مع عناوين URL نفسها.
• توضّح storage كيفية حفظ الملفات: mode (permanent أو temporary)، وbytes المخزنة، وexpires_at (وقت حذف الملف المؤقت، وnull للملفات الدائمة)، وexpired (true بعد زوال الملفات).
• تمثل cost.credits سعر الاستدعاء بأرصدة API (cost.usd بوحدة USD)، وتمثل cost.charged ما خُصم من رصيد API، وتمثل cost.refunded ما أُعيد. في نموذج metered، تمثل cost.credits الحد الأقصى المحتجز في البداية (cost.held)؛ وبعد نجاح التشغيل، توضح cost.settled قيمة الاستخدام، ويكون باقي الحد الأقصى في cost.refunded (راجع الفوترة حسب الاستخدام).
• عند فشل الطلب، تكون error هي { "type": …, "code": …, "message": … }.

قراءة طلب#

curl "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t?wait=20" \
  -H "Authorization: Bearer $DOITONG_API_KEY"

• تنفذ ?wait=N (حتى 20 ثانية) استطلاعًا طويلًا: يعيد الاستدعاء النتيجة فور وصول الطلب إلى حالة نهائية، أو بعد N ثانية مع الحالة الحالية. ويُعد تكرار ذلك أبسط طريقة لانتظار النتيجة.
• تضيف ?logs=1 أسطر سجل تقدم النموذج (آخر 50 سطرًا) باسم logs.

يمكنك قراءة طلبات حسابك فقط؛ وأي معرّف آخر يعيد 404 request_not_found.

سرد الطلبات#

curl "https://api.doitong.com/v1/requests?limit=20&status=succeeded&model=flux/schnell" \
  -H "Authorization: Bearer $DOITONG_API_KEY"

من الأحدث إلى الأقدم. تتراوح limit من 1 إلى 100 (الافتراضي 20)، وتقوم status وmodel بالتصفية. تكون الاستجابة { "object": "list", "data": [ … ], "has_more": true, "next_cursor": "req_…" }؛ مرّر cursor=<next_cursor> للصفحة التالية.

إلغاء طلب#

curl -X POST "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t/cancel" \
  -H "Authorization: Bearer $DOITONG_API_KEY"

• إذا أُلغي قبل بدء النموذج: تصبح الحالة canceled، وتُسترد أرصدة API، وتحصل على 200.
• إذا كان النموذج يُنشئ المخرج بالفعل: يُمرر الإلغاء وتحصل على 202 مع "cancel_requested": true. وإذا انتهى النموذج رغم ذلك، ينجح الطلب بصورة طبيعية وتُفرض تكلفته.
• إذا كان الطلب نهائيًا بالفعل: 409 not_cancelable (أما الطلب الذي حالته canceled فيعيد 200 ببساطة).

حذف ملفات طلب#

curl -X DELETE "https://api.doitong.com/v1/requests/req_8k2m4q7x1z9c3v5b6n0p2r4t/files" \
  -H "Authorization: Bearer $DOITONG_API_KEY"

يحذف نسخنا من ملفات مخرج الطلب فورًا ويوقف رسوم تخزينها. تكون الاستجابة كائن الطلب مع storage.expired: true؛ وتبقى عناوين URL الخاصة به في السجل لكنها لا تعود تعمل. لا يغيّر استدعاؤه مرة أخرى شيئًا (200). لا يملك الطلب الذي لا يزال queued أو running ملفات بعد: 409 request_active. يتطلب models:run.

قابلية التكرار: إعادة المحاولة دون الدفع مرتين#

قد تفشل الشبكات. لإعادة محاولة تشغيل بأمان، أرسل ترويسة Idempotency-Key (أي سلسلة تصل إلى 255 حرفًا، وفريدة لكل عملية، مثل معرّف طلبك الخاص):

• المفتاح نفسه والجسم نفسه كما سبق: تحصل على الطلب الأصلي مجددًا (200، والترويسة Idempotent-Replayed: true)، ولا تُفرض أي تكلفة مرة أخرى.
• المفتاح نفسه والجسم نفسه بعد تشغيل فشل قبل وصوله إلى النموذج (upstream_error أو internal_error عند الإرسال، أو insufficient_credits أو budget_exceeded أو too_many_inflight): لم يُنتج شيء ولم تُفرض تكلفة، لذا تعيد المحاولة تشغيل النموذج بدلًا من إعادة الفشل.
• المفتاح نفسه مع جسم مختلف: 409 idempotency_mismatch.
• ترتبط المفاتيح بمفتاح API الذي أرسلها.

مكان حفظ الملفات#

يُنسخ كل ملف مخرج إلى تخزيننا قبل وضع علامة succeeded على الطلب، لذلك تكون عناوين URL في outputs على مضيفاتنا ويمكنك الربط بها مباشرة. وتختار أنت مدة بقائها:

• يحدد إعداد الحساب ما يحدث للطلبات الجديدة: مفتاح التبديل "الاحتفاظ بالملفات إلى الأبد" في لوحة التحكم، أو PATCH https://api.doitong.com/v1/account/storage مع {"mode": "temporary"}. يعرض GET https://api.doitong.com/v1/account الإعداد ضمن storage، مع وحدات البايت التي تحتفظ بها والتقدير الشهري.
• يتجاوز ?storage=permanent|temporary في التشغيل (وسيطة storage لأداة MCP run) الإعداد لذلك التشغيل.
• لا يلمس تغيير الإعداد الملفات الموجودة لديك؛ احذفها باستخدام DELETE /requests/{id}/files.
• عندما يتعذر على رصيد API دفع تكلفة التخزين، لا تُفرض أي تكلفة وتتلقى بريدًا إلكترونيًا: اشحن الرصيد خلال 30 يومًا، وإلا تصبح الملفات المحتفظ بها مؤقتة وتُحذف بعد 7 يومًا.

في الحالة النادرة التي تفشل فيها عملية النسخ لدينا، يحتوي الإدخال على "stored": false ويكون عنوان URL هو الأصلي قصير الصلاحية: نزّله قريبًا.