`POST /v1/filmmaker/runs`

استخدم حقول الطلب والأذونات الموثقة لنقطة HTTP هذه.

مثال طلب#

curl -X POST 'https://platform.tongai.io/v1/filmmaker/runs' \  -H "Authorization: Bearer $TONG_API_KEY" \  -H "Content-Type: application/json" \  -H "Idempotency-Key: 45be69f1-c266-4a09-a82c-bf3c6303eb03" \  -d '{  "message": "A quiet street at blue hour"}'

الإعدادات

curl --version

المصادقة#

استخدم مفتاح API على الخادم لحسابك، أو OAuth لحساب كل عميل. لا ترسل المفاتيح في المطالبات أو وسيطات الأدوات.

filmmaker:runcredits:spend

المعاملات#

Idempotency-Keystringمطلوب

معرّف UUID، مثل e8aa0a87-6cd9-42eb-975a-b72bf43218c8.

محتوى الطلب#

application/json

messagestringمطلوب

صف النتيجة التي تريد إنشاءها.

الحد الأدنى للطول: 1 محرفًا.

الحد الأقصى للطول: 32000 محرفًا.

attachmentsstring[]اختياري

استخدم معرّفات أصول تملكها وتوافق إمكانات المراجع للنموذج المحدد.

الحد الأقصى للعناصر: 30.

القيمة الافتراضية: [].

reference_bindingsobject[]اختياري

الحد الأقصى للعناصر: 30.

عرض الحقول المتداخلة

labelstringمطلوب

استخدم تسمية مرجع مرقّمة، مثل Image1.

assetIdstringمطلوب

استخدم معرّف أصل يملكه الحساب المصرح له.

معرّف سداسي عشري من 24 محرفًا.

modestringاختياري

تتوقف العمليات الموجّهة للمراجعة البشرية في Tong، وتستمر التلقائية. يُحاسب كلاهما أثناء العمل ويتوقفان عند نفاد الرصيد.

القيم المسموح بها"guided""automatic"

القيمة الافتراضية: "guided".

conversation_idstringاختياري

معرّف UUID، مثل e8aa0a87-6cd9-42eb-975a-b72bf43218c8.

model_preferencesobjectاختياري

عرض الحقول المتداخلة

imagestring | nullمطلوب

استخدم حروفًا أو أرقامًا أو شرطات سفلية أو نقاطًا أو نقطتين أو شرطات مائلة أو واصلات.

الحد الأدنى للطول: 1 محرفًا.

الحد الأقصى للطول: 150 محرفًا.

videostring | nullمطلوب

استخدم حروفًا أو أرقامًا أو شرطات سفلية أو نقاطًا أو نقطتين أو شرطات مائلة أو واصلات.

الحد الأدنى للطول: 1 محرفًا.

الحد الأقصى للطول: 150 محرفًا.

sourceobjectاختياري

عرض الحقول المتداخلة

kindstringمطلوب

القيم المسموح بها"director""text"

idstringمطلوب

معرّف سداسي عشري من 24 محرفًا.

مخطط الاستجابة#

الاستجابة

JSON

{  "id": "e8aa0a87-6cd9-42eb-975a-b72bf43218c8",  "tool": "example",  "category": "example",  "channel": "api",  "state": "queued",  "status": "accepted",  "stage": "admission",  "dispatch_status": "pending",  "created_at": "2026-10-22T09:00:00.000Z",  "updated_at": "2026-10-22T09:00:00.000Z",  "detail_expires_at": "2026-10-22T09:00:00.000Z",  "detail_expired": false,  "timing": {    "dispatch_started_at": "2026-10-22T09:00:00.000Z",    "acknowledged_at": "2026-10-22T09:00:00.000Z",    "completed_at": "2026-10-22T09:00:00.000Z",    "dispatch_acknowledgement_ms": 0,    "end_to_end_ms": 0  },  "review": null,  "result": null,  "error": {    "code": "example"  },  "billing": {    "status": "none",    "usage_credits": "0.000000",    "wallet_debited_credits": "0.000000"  }}

`HTTP 202`

application/json

idstringمطلوب

المعرّف الفريد للعملية المحفوظة.

معرّف UUID، مثل e8aa0a87-6cd9-42eb-975a-b72bf43218c8.

toolstringمطلوب

categorystringمطلوب

channelstringمطلوب

القيم المسموح بها"api""mcp"

statestringمطلوب

حالة التنفيذ الحالية للعمل المحفوظ.

القيم المسموح بها"queued""running""waiting""needs_review""paused""reconciling""succeeded""failed""cancelled"

statusstringمطلوب

الحالة العامة المستخدمة لتتبع العملية.

القيم المسموح بها"accepted""running""needs_review""paused""reconciling""succeeded""failed""cancelled"

stagestringمطلوب

المرحلة الحالية للعملية.

القيم المسموح بها"admission""dispatch""review""generation""reconciliation""complete"

dispatch_statusstringمطلوب

ما إذا كانت الأداة قد قبلت الطلب. لا يعني الإقرار أن التوليد اكتمل.

القيم المسموح بها"pending""unknown""acknowledged"

created_atstringمطلوب

تاريخ ووقت بتنسيق ISO 8601، مثل 2026-10-22T09:00:00Z.

updated_atstringمطلوب

تاريخ ووقت بتنسيق ISO 8601، مثل 2026-10-22T09:00:00Z.

detail_expires_atstring | nullمطلوب

موعد انتهاء صلاحية تفاصيل العملية المحفوظة. تعني القيمة null أنه لا يوجد انتهاء محدد حاليًا.

تاريخ ووقت بتنسيق ISO 8601، مثل 2026-10-22T09:00:00Z.

detail_expiredbooleanمطلوب

ما إذا كانت صلاحية تفاصيل العملية المحفوظة قد انتهت.

timingobjectمطلوب

الطوابع الزمنية والمدد المنقضية لتتبع هذه العملية.

عرض الحقول المتداخلة

dispatch_started_atstring | nullمطلوب

تاريخ ووقت بتنسيق ISO 8601، مثل 2026-10-22T09:00:00Z.

acknowledged_atstring | nullمطلوب

تاريخ ووقت بتنسيق ISO 8601، مثل 2026-10-22T09:00:00Z.

completed_atstring | nullمطلوب

تاريخ ووقت بتنسيق ISO 8601، مثل 2026-10-22T09:00:00Z.

dispatch_acknowledgement_msnumber | nullمطلوب

الحد الأدنى: 0.

end_to_end_msnumber | nullمطلوب

الحد الأدنى: 0.

reviewJSON | nullمطلوب

معلومات المراجعة عندما تحتاج العملية إلى تدخل بشري؛ وإلا تكون null.

resultJSON | nullمطلوب

المخرجات التي تعيدها هذه الأداة، أو null عندما لا تتوفر مخرجات.

errorobject | nullمطلوب

رمز الخطأ العام إذا فشلت العملية؛ وإلا تكون null.

عرض الحقول المتداخلة

codestringمطلوب

billingobjectمطلوب

استخدام أرصدة العميل ورسوم المحفظة. جاهزية المخرجات وتسوية الفوترة حالتان منفصلتان.

عرض الحقول المتداخلة

statusstringمطلوب

القيم المسموح بها"none""pending""settled""released""reconciling"

usage_creditsstringمطلوب

سلسلة عشرية بست منازل عشرية، مثل 1.250000.

wallet_debited_creditsstringمطلوب

سلسلة عشرية بست منازل عشرية، مثل 1.250000.

released_creditsstringاختياري

سلسلة عشرية بست منازل عشرية، مثل 1.250000.

refunded_creditsstringاختياري

سلسلة عشرية بست منازل عشرية، مثل 1.250000.

unfunded_creditsstringاختياري

سلسلة عشرية بست منازل عشرية، مثل 1.250000.

pending_creditsstringاختياري

سلسلة عشرية بست منازل عشرية، مثل 1.250000.

tokensobjectاختياري

عرض الحقول المتداخلة

inputnumberاختياري

الحد الأدنى: 0.

outputnumberاختياري

الحد الأدنى: 0.

cachednumberاختياري

الحد الأدنى: 0.

cache_writenumberاختياري

الحد الأدنى: 0.

componentsobject[]اختياري

عرض الحقول المتداخلة

idstringاختياري

source_idstringمطلوب

toolstringمطلوب

modelstring | nullمطلوب

channelstringمطلوب

القيم المسموح بها"api""mcp"

credential_idstringمطلوب

kindstringمطلوب

القيم المسموح بها"text_pool""reasoning""generation"

usage_creditsstringمطلوب

سلسلة عشرية بست منازل عشرية، مثل 1.250000.

wallet_debited_creditsstringمطلوب

سلسلة عشرية بست منازل عشرية، مثل 1.250000.

evidence_atstringاختياري

تاريخ ووقت بتنسيق ISO 8601، مثل 2026-10-22T09:00:00Z.

updated_atstringاختياري

تاريخ ووقت بتنسيق ISO 8601، مثل 2026-10-22T09:00:00Z.

quoteobjectاختياري

الإعدادات والسعر وقيم الإرسال عند توفر عرض سعر.

عرض الحقول المتداخلة

idstringمطلوب

معرّف UUID، مثل e8aa0a87-6cd9-42eb-975a-b72bf43218c8.

operation_idstringمطلوب

معرّف UUID، مثل e8aa0a87-6cd9-42eb-975a-b72bf43218c8.

toolstringمطلوب

operationstring | nullمطلوب

modelstring | nullمطلوب

configurationobjectمطلوب

submit_valuestringمطلوب

submit_fieldstringمطلوب

quoted_creditsstring | nullمطلوب

سلسلة عشرية بست منازل عشرية، مثل 1.250000.

expires_atstring | nullمطلوب

تاريخ ووقت بتنسيق ISO 8601، مثل 2026-10-22T09:00:00Z.

الأخطاء والحدود#

HTTP	الخطأ	الاستئناف
`400`	طلب غير صالح`REQUEST_INVALID`	صحح الحقول المشار إليها في الخطأ قبل إعادة المحاولة.
`401`	بيانات اعتماد غير صالحة`CREDENTIAL_INVALID`	تحقق من بيانات الاعتماد وانتهائها وما إذا أُلغيت.
`402`	أرصدة غير كافية`INSUFFICIENT_CREDITS`	أضف أرصدة إلى الحساب المالك لبيانات الاعتماد ثم تابع العمل المحفوظ.
`403`	الإذن مرفوض`SCOPE_REQUIRED`	استخدم بيانات اعتماد بالأذونات المطلوبة والوصول إلى المورد المحدد.
`404`	المورد غير متاح`RESOURCE_UNAVAILABLE`	تحقق من معرّف المورد وملكيته للحساب المصرح له.
`409`	تعارض القصد`IDEMPOTENCY_CONFLICT`	أعد استخدام القصد مع طلبه الأصلي فقط. استخدم UUID جديدًا لإجراء مختلف.
`429`	تم بلوغ حد الطلبات`RATE_LIMITED`	انتظر المدة المحددة في Retry-After قبل إعادة الطلب نفسه.
`503`	غير متاح مؤقتًا`DEPENDENCY_UNAVAILABLE`	انتظر Retry-After وأعد المحاولة بالقصد نفسه. تحقق من العملية المحفوظة بعد انتهاء مهلة.

المصادقةتُخصم تكلفة مفاتيح API من حساب مالك المفتاح. ويتيح OAuth لكل مستخدم متصل استخدام أرصدته.الأخطاء وحدود الطلباتافهم استجابات الأخطاء وأعد المحاولة بأمان واستأنف عمليات التوليد الفاشلة.الطلبات والسجلاتقبول الطلب لا يعني اكتمال التوليد. تابع المهمة المحفوظة حتى تصبح النتيجة جاهزة.