عمليات التوليد
تابع عملية توليد في Direct API حتى حالتها النهائية بالاستطلاع الطويل، واقرأ عدة عمليات دفعة واحدة، واعرف متى تستطلع.
عملية التوليد وحدة واحدة من العمل غير المتزامن: صورة واحدة، أو فيديو واحد، أو مقطع صوتي واحد، أو عملية عرض واحدة. تبدأ الأدوات التي تحمل returns_generation: true عملية واحدة أو أكثر وتُجيب فورًا بمعرّفاتها. تابعها عبر الاستطلاع، أو عبر الويبهوك، أو كليهما: استخدم الويبهوك كإشارة رئيسية واستطلاعًا عرضيًا كشبكة أمان.
الحالات
queued ──► in_progress ──► succeeded
│ │
│ ├──────► failed
└─────────────┴──────► cancelled| الحالة | نهائية | المعنى |
|---|---|---|
queued | لا | قُبلت، وتنتظر توفر سعة النموذج |
in_progress | لا | النموذج يعمل |
succeeded | نعم | يحتوي assets على المخرجات |
failed | نعم | يوضح error السبب؛ ويُسترد المبلغ المخصوم، ويوضح billing.credits_refunded مقداره |
cancelled | نعم | توقفت قبل أن تنتج مخرجات؛ ويُسترد المبلغ المخصوم |
تعامل مع أي حالة لا تعرفها على أنها غير نهائية، واستمر في متابعة عملية التوليد؛ فقد تُضاف حالات وسيطة جديدة.
كائن عملية التوليد
{
"object": "generation",
"id": "0192a7b3-a1c4-7e02-8f9d-1a2b3c4d5e6f",
"tool": "generate_video",
"status": "succeeded",
"project_id": "01928f4e-5b7c-7d2a-9e11-3c4b5a6d7e8f",
"model_id": "mdl_7rk2pq9vxa4m",
"created_at": "2026-10-25T09:14:03.120Z",
"completed_at": "2026-10-25T09:15:41.902Z",
"error": null,
"billing": {
"estimated_credits": 120,
"credits_charged": 96,
"credits_refunded": 0,
"credits_are_final": true,
"credits_settle_on_output_duration": true
},
"assets": [
{
"id": "0192a7b4-0f1e-7d3c-9b8a-7c6d5e4f3a2b",
"type": "video",
"name": "Bicycle hero shot",
"mime_type": "video/mp4",
"width": 1920,
"height": 1080,
"duration_seconds": 8,
"url": "https://mcp.morphic.com/m/Xk29dPq",
"url_expires_at": null,
"studio_url": "https://studio.morphic.com/…",
"final_generation_expires_at": null
}
],
"content_left_out": [],
"render_warnings": [],
"metadata": { "order_id": "4411" },
"poll_after_seconds": null
}| الحقل | المعنى |
|---|---|
error | null، أو { "error_code": "…", "message": "…" } عند failed. الرسالة آمنة لعرضها على مستخدميك. |
billing | تكلفة عملية التوليد هذه؛ راجع الأرصدة والاستخدام |
assets[].id | معرّف الأصل الذي تأخذه الأدوات الأخرى كمدخل (image_asset_id، video_asset_id، …) |
assets[].url | رابط قصير لتنزيل الوسائط؛ لا تنتهي صلاحيته، وurl_expires_at هو null |
assets[].studio_url | يفتح الأصل في Morphic Studio لفريقك |
assets[].final_generation_expires_at | لمسودات الفيديو فقط: الموعد الذي يظل حتى حلوله بإمكان finalize_video_draft عرضها بالدقة الكاملة |
content_left_out، render_warnings | لعمليات التركيب وتصدير الخط الزمني فقط: ما لم تتمكن المخرجات من تضمينه، والسبب |
poll_after_seconds | ما دامت غير نهائية، المدة التي تنتظرها قبل القراءة التالية؛ وnull بعد أن تصبح نهائية |
قراءة عملية توليد واحدة
يُجيب GET /v1/direct/generations/{id} بـ 200 مع { "generation": { … } }.
curl -s "https://mcp.morphic.com/v1/direct/generations/$ID?wait=45" \
-H "Authorization: Bearer $MORPHIC_API_KEY"waitاختياري، من0إلى45ثانية. يبقى الطلب مفتوحًا حتى تتغير حالة عملية التوليد أو تنتهي، ثم يُجيب فورًا.- عندما تنقضي مدة الانتظار، يُجيب بالحالة الحالية. وتُقلَّص أي قيمة تتجاوز 45 إلى 45.
- عملية التوليد التابعة لمؤسسة أخرى، أو التي لا يجوز لهذا المفتاح قراءتها، تُجاب بـ
404وليس403أبدًا، حتى لا يمكن تخمين المعرّفات.
قراءة عدة عمليات توليد
يقرأ POST /v1/direct/generations/batch-get ما يصل إلى 10 عمليات توليد في طلب واحد.
curl -s https://mcp.morphic.com/v1/direct/generations/batch-get \
-H "Authorization: Bearer $MORPHIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"ids": ["0192a7b3-…", "0192a7b3-…"], "wait": 30}'- مع
wait، يُجيب الطلب بمجرد أن تتغير حالة أي منها أو تصبح كلها نهائية. - الاستجابة هي
{ "generations": [ … ], "not_found": ["…"] }، بالترتيب المطلوب.
كم مرة تستطلع
يحمل كل بدء وكل قراءة غير نهائية poll_after_seconds. انتظر تلك المدة على الأقل قبل القراءة التالية، ثم زِد فترات الانتظار تدريجيًا.
| المخرجات | أول استطلاع بعد | الوقت المعتاد حتى الحالة النهائية |
|---|---|---|
| صورة، تعديل صورة، رفع دقة، عمليات على الصور | 5 ثوانٍ | من 5 إلى 60 ثانية |
| كلام، مؤثر صوتي، تفريغ نصي | 10 ثوانٍ | من 10 إلى 90 ثانية |
| موسيقى، حوار | 20 ثانية | من 30 ثانية إلى 3 دقائق |
| فيديو، تعديل فيديو، مزامنة شفاه، عمليات عرض | 30 ثانية | من 1 إلى 10 دقائق، وأطول تحت الضغط |
يُحتسب الاستطلاع الطويل (wait=45) قراءة واحدة مهما طال إبقاؤه مفتوحًا، لذا فهو أسرع طرق الاستطلاع وأرخصها. اضبط مهلة عميل HTTP لديك فوق مدة الانتظار: 60 ثانية لـ wait=45.
import time, requests
def wait_for(generation_id, key):
headers = {"Authorization": f"Bearer {key}"}
url = f"https://mcp.morphic.com/v1/direct/generations/{generation_id}"
while True:
r = requests.get(url, params={"wait": 45}, headers=headers, timeout=60)
if r.status_code == 429:
time.sleep(int(r.headers.get("Retry-After", "5")))
continue
r.raise_for_status()
gen = r.json()["generation"]
if gen["status"] in ("succeeded", "failed", "cancelled"):
return gen
# A long-poll already waited; only sleep if the server asks for more.
time.sleep(max(0, (gen.get("poll_after_seconds") or 0) - 45))حدود الاستطلاع
| الحد | القيمة | عند التجاوز |
|---|---|---|
| قراءات عملية توليد واحدة بمفتاح واحد | 30 في الدقيقة | 429، Retry-After |
| قراءات جميع عمليات التوليد بمفتاح واحد | 1,200 في الدقيقة | 429، Retry-After |
wait | 45 ثانية | تُقلَّص |
| المعرّفات في القراءة المجمّعة | 10 | 400 |
تُحتسب القراءة المجمّعة مرة لكل معرّف مقابل الحدين كليهما. وبالوتيرة الموصى بها، يستطيع مفتاح واحد متابعة عدة مئات من عمليات التوليد الجارية في الوقت نفسه؛ وإن كنت تتابع أكثر من ذلك، فاستخدم الويبهوك.
إذا واجهت أي مشكلة أو كانت لديك أي أسئلة، فلا تتردد في التواصل معنا. يسعدنا مساعدتك. اكتب لنا على support@morphic.com.