استدعاء أداة

كل قدرة هي أداة واحدة تُستدعى بالطريقة نفسها: POST /v1/direct/tools/{tool_name}. ويسردها كتالوج الأدوات كلها.

الطلبCopy Anchor Link

{
  "input": { },
  "webhook_id": "01929a10-0c3d-7f44-8a21-0b1c2d3e4f50",
  "metadata": { "order_id": "4411", "customer": "acme" }
}

استدعاء كامل مع مفتاح تكرار آمن:

curl -s https://mcp.morphic.com/v1/direct/tools/generate_image \
  -H "Authorization: Bearer $MORPHIC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-4411-hero-image" \
  -d '{"input": {"prompt": "A red vintage bicycle against a pastel wall", "project_id": "01928f4e-5b7c-7d2a-9e11-3c4b5a6d7e8f"}, "metadata": {"order_id": "4411"}}'

الاستجابةCopy Anchor Link

لكل استجابة ناجحة الغلاف نفسه. وتقع مخرجات الأداة نفسها في result، كما يصفها output_schema الخاص بها.

{
  "request_id": "0192a7b3-91d0-7c55-b1aa-6e5f4c3b2a10",
  "tool": "generate_image",
  "result": {
    "generation_id": "0192a7b3-a1c4-7e02-8f9d-1a2b3c4d5e6f",
    "generation_ids": ["0192a7b3-a1c4-7e02-8f9d-1a2b3c4d5e6f"],
    "status": "queued",
    "project_id": "01928f4e-5b7c-7d2a-9e11-3c4b5a6d7e8f",
    "project_name": "Spring campaign",
    "file_id": "01928f4e-6c8d-7a10-b2c3-d4e5f6a7b8c9",
    "model_id": "mdl_3hv8tq1nzc6e",
    "estimated_credits": 8,
    "credits_settle_on_output_duration": false
  },
  "billing": {
    "credits_charged": 8,
    "credits_are_final": false,
    "credits_settle_on_output_duration": false,
    "generation_ids": ["0192a7b3-a1c4-7e02-8f9d-1a2b3c4d5e6f"]
  }
}

كتلة الفوترةCopy Anchor Link

تظهر billing في كل استجابة ناجحة، بما في ذلك الاستدعاءات المجانية.

تُبلغ الكتلة بما خصمه الاستدعاء عند عودته. أما الاستردادات والتسوية فتحدث لاحقًا وتظهر على عملية التوليد، ولا تظهر أبدًا على الاستجابة الأصلية. وتحمل الاستجابات أيضًا Morphic-Credits-Charged: <integer> للتسجيل في البوابة لديك. وتشرح صفحة الأرصدة والاستخدام كيف تُخصم عملية التوليد وتُسوّى وتُسترد.

رفض الأداةCopy Anchor Link

عندما يكون الإدخال سليم الصيغة لكن لا يمكن تشغيله (نموذج لا تشمله خطتك، أو نسبة عرض إلى ارتفاع لا يوفرها النموذج، أو أصل من نوع خاطئ)، يُجيب الاستدعاء بـ 422 tool_refused. وتذكر الرسالة الحقل والقيمة والقيم التي كانت ستنجح. لم يبدأ شيء ولم يُخصم شيء.

{
  "description": "aspect_ratio: \"21:9\" is not offered by model mdl_3hv8tq1nzc6e. Offered: 1:1, 4:3, 3:4, 16:9, 9:16. Models offering 21:9 for text_to_image: mdl_9wd4mf2kqs7b.",
  "code": "tool_refused",
  "data": { "request_id": "0192a7b3-…", "tool": "generate_image" },
  "error": { "error_code": "TOOL_REFUSED", "message": "aspect_ratio: \"21:9\" is not offered by model mdl_3hv8tq1nzc6e. …" }
}

البدء الجزئيCopy Anchor Link

الاستدعاء الذي تزيد فيه variations على 1 يبدأ عملية توليد لكل تنويع. فإذا رُفض تنويع لاحق بعد أن بدأت تنويعات سابقة:

• تظل الاستجابة 202، ويوضح result.partial_failure ما حدث.
• لا يسرد result.generation_ids إلا ما بدأ، ولا يحتسب billing إلا ما بدأ.
• أعد محاولة التنويعات الناقصة فقط.

التكرار الآمنCopy Anchor Link

قد يقع عطل في الشبكة بعد إرسال الطلب وقبل وصول إجابته. لإعادة محاولة استدعاء مدفوع بأمان، أرسل الترويسة Idempotency-Key. استخدم معرّف المهمة أو الطلب الخاص بك.

Idempotency-Key: order-4411-hero-image

• يُنفَّذ أول طلب يحمل المفتاح بشكل طبيعي.
• لا تُنفَّذ إعادة المحاولة بالمفتاح والأداة والجسم نفسها خلال 24 ساعة مرة أخرى. بل تُجيب بـ 200 مع جسم الاستجابة الأصلي، بما في ذلك generation_ids وbilling الأصليتان، ولا تخصم شيئًا إضافيًا. وتكون ترويسة Morphic-Credits-Charged الخاصة بها 0.
• المفتاح نفسه مع أداة أو جسم مختلف يُجاب بـ 409 idempotency_conflict.
• إعادة المحاولة بينما لا يزال الطلب الأصلي قيد التنفيذ تُجاب بـ 409 idempotency_in_progress.
• إعادة محاولة استدعاء مدفوع فشل طلبه الأصلي (5xx) أو لم يُجب قط بعد أن ربما نُفِّذ تُجاب بـ 409 idempotency_outcome_unknown. ولا يُنفَّذ مرة أخرى أبدًا بالمفتاح نفسه: تحقق من نتيجته، ثم استخدم مفتاحًا جديدًا.
• نطاق المفاتيح هو مفتاح API الذي أرسلها، وطولها حتى 200 حرف.

تقبل الاستدعاءات المجانية الترويسة أيضًا، لكنها نادرًا ما تحتاجها.

إعادة محاولة استدعاء مدفوع بعد 5xxCopy Anchor Link

الاستدعاء المدفوع الذي يُجيب بـ 500 أو 503 أو 504 ربما بدأ العمل وخصم مقابله قبل أن يفشل.

1. تحقق مما فعله الاستدعاء عبر list_generations، أو عبر GET /v1/direct/usage مع التصفية حسب الوقت.
2. أرسل Idempotency-Key جديدًا فقط للعمل الذي لم يبدأ.

عندما لا تصل أي إجابة على الإطلاق (اتصال منقطع)، أعد المحاولة بالمفتاح نفسه: ستحصل على الإجابة المخزنة، أو على 409 idempotency_in_progress ما دام لا يزال قيد التنفيذ.

إذا واجهت أي مشكلة أو كانت لديك أي أسئلة، فلا تتردد في التواصل معنا. يسعدنا مساعدتك. اكتب لنا على support@morphic.com.