الأرصدة والاستخدام

تخصم Direct API أرصدة Morphic من رصيد مؤسستك، وهو المجمّع نفسه الذي يستخدمه Studio، وكل استجابة تذكر عددها.

• تُخصم استدعاءات Direct API وفق أسعار API الخاصة بمؤسستك، والتي قد تختلف عن تكلفة العمل نفسه في Studio. وكل رقم تعطيك إياه الواجهة يعكسها بالفعل: عروض أسعار plan_media، وestimated_credits، وكتلة billing، وقراءات عمليات التوليد، والويبهوك، و/usage.
• تُحدَّد الأسعار لكل مؤسسة ولا تُنشر. ويمكن لجهة الاتصال الخاصة بحسابك مشاركة جدول أسعار API الخاص بك.
• يسري تغيير السعر على عمليات التوليد التي تبدأ بعده؛ أما عملية التوليد الجارية فتُسوّى بالسعر الذي بدأت به.
• في Studio، ضمن 'Settings' > 'Credits'، يظهر إنفاق API في صف مستقل باسم 'API' بجوار أعضائك، ويفصّله 'Split API by key' حسب كل مفتاح. ويُسحب من أرصدة المؤسسة لكن لا يُسحب أبدًا من حصة أي عضو، وتضع حدود الرصيد لكل مفتاح سقفًا له.

كيف تُخصم عملية التوليدCopy Anchor Link

1. عند البدء، يُخصم من عملية التوليد سعرها المعروض. وتُبلغ استجابة البدء به في billing.credits_charged وresult.estimated_credits.
2. تُسعَّر بعض المخرجات بحسب ما يُنتج فعلًا: الكلام والموسيقى بحسب الطول المُنتج، وعمليات عرض الخط الزمني بحسب وقت الحوسبة. وتحمل هذه credits_settle_on_output_duration: true؛ فيكون خصم البدء حدًا أدنى، ويُسوّى المبلغ النهائي عند انتهاء عملية التوليد.
3. عملية التوليد التي تنتهي بـ failed أو cancelled تُسترد بالكامل، ويُبلغ billing.credits_refunded بالأرصدة المُعادة. وقد تحمل عملية التوليد الناجحة أيضًا استردادًا جزئيًا، على سبيل المثال عندما تأتي مخرجات مُسوّاة أقصر مما غطّاه خصم البدء.
4. بعد أن تصبح عملية التوليد نهائية، يكون billing.credits_charged هو الإجمالي الصافي في السجل (خصم البدء، زائد التسوية أو ناقصها، ناقص credits_refunded)، ويكون credits_are_final هو true. وتنتهي عملية التوليد الفاشلة أو الملغاة بـ credits_charged: 0 وcredits_refunded مساويًا لما خُصم منها.

ما دامت عملية التوليد جارية، يساوي credits_charged خصم البدء. اقرأه مرة أخرى بعد أن تصبح عملية التوليد نهائية لمعرفة المبلغ المُسوّى؛ ولا يُرسَل الويبهوك إلا بعد ذلك.

الفوترة في كل استجابةCopy Anchor Link

تُبلغ كتلة billing في استجابة الاستدعاء بما خصمه الاستدعاء عند عودته؛ وتسردها صفحة استدعاء أداة حسب نوع الاستدعاء. تحدث الاستردادات لاحقًا، لذا تظهر على عملية التوليد (GET /generations/{id} و/usage)، ولا تظهر أبدًا على الاستجابة الأصلية.

• الأداة المدفوعة التي تُجيب ضمن الاستدعاء ويفشل عملها، مثل analyze_video، تُجيب بـ credits_charged: 0 وبتعيين credits_refunded على قيمة الاسترداد.
• تحمل الترويسة Morphic-Credits-Charged: <integer> الرقم نفسه الذي في billing.credits_charged، إلا في إعادة التشغيل الآمنة لطلب سابق، التي لا تخصم شيئًا إضافيًا وترسل 0 بينما يكرر جسمها الخصم الأصلي.

احصل على عرض سعر قبل الإنفاقCopy Anchor Link

يتحقق POST /v1/direct/tools/plan_media من خطة تضم حتى 20 خطوة ويسعّر الخطوات التي يستطيع تسعيرها، دون أن يبدأ أو يخصم أي شيء.

curl -s https://mcp.morphic.com/v1/direct/tools/plan_media \
  -H "Authorization: Bearer $MORPHIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "input": {
          "steps": [
            { "id": "still", "tool_name": "generate_image", "arguments_json": "{\"prompt\":\"A red vintage bicycle\",\"aspect_ratio\":\"16:9\"}" },
            { "id": "clip", "tool_name": "generate_video", "arguments_json": "{\"prompt\":\"The bicycle rolls away\",\"duration_seconds\":8}", "depends_on": ["still"] }
          ]
        }
      }'

• احذف حقول الأصول التي لم تُنتج مخرجاتها بعد، واذكر في depends_on الخطوة التي ستأتي منها.
• تحصل كل خطوة على validation وquote_status وestimated_credits الخاصة بها.
• تعطي النتيجة أيضًا execution_order وknown_estimated_credits وunquoted_step_ids وcomplete_estimate. وعندما يكون complete_estimate هو false، يكون المجموع حدًا أدنى، لا ميزانية.

المفتاح والرصيدCopy Anchor Link

يعيد GET /v1/direct/me المفتاح المستدعي وحدوده وإنفاقه، ورصيد المؤسسة. ويمكن لأي مفتاح استدعاؤه.

curl -s https://mcp.morphic.com/v1/direct/me \
  -H "Authorization: Bearer $MORPHIC_API_KEY"

{
  "api_key": {
    "id": "01928e00-…",
    "name": "Order pipeline (prod)",
    "scopes": ["assets:read", "assets:write", "generations:write", "projects:read"],
    "expires_at": null,
    "credit_limits": {
      "total":   { "limit": 500000, "used": 182340, "remaining": 317660 },
      "monthly": { "limit": 100000, "used": 41200,  "remaining": 58800, "resets_at": "2026-11-01T00:00:00.000Z" },
      "daily":   { "limit": null,   "used": 2310,   "remaining": null,  "resets_at": "2026-10-26T00:00:00.000Z" }
    }
  },
  "organization": {
    "id": "01928d00-…",
    "plan": "enterprise",
    "remaining_credits": 1240000,
    "unlimited": false
  }
}

سجل الاستخدامCopy Anchor Link

يعيد GET /v1/direct/usage (النطاق assets:read) كل قيد في السجل تسبب فيه المفتاح، لمطابقته مع سجلاتك الخاصة.

curl -s "https://mcp.morphic.com/v1/direct/usage?from=2026-10-01T00:00:00Z&limit=200" \
  -H "Authorization: Bearer $MORPHIC_API_KEY"

{
  "usage": [
    { "id": "0192a7b3-…", "created_at": "2026-10-25T09:14:03.500Z", "kind": "charge",     "credits": 120, "generation_id": "0192a7b3-a1c4-…", "tool": "generate_video", "model_id": "mdl_7rk2pq9vxa4m", "metadata": { "order_id": "4411" } },
    { "id": "0192a7b4-…", "created_at": "2026-10-25T09:15:41.950Z", "kind": "settlement", "credits": -24, "generation_id": "0192a7b3-a1c4-…", "tool": "generate_video", "model_id": "mdl_7rk2pq9vxa4m", "metadata": { "order_id": "4411" } }
  ],
  "totals": { "charged": 120, "settled": -24, "refunded": 0, "net": 96 },
  "next_cursor": null
}

• قيمة kind واحدة من charge أو settlement أو refund؛ وتعني قيمة credits السالبة إعادة أرصدة.
• يغطي totals النطاق المُصفّى كاملًا، لا الصفحة فقط.
• الأداة التي تُجيب ضمن الاستدعاء (analyze_video، analyze_audio، filmlab_edit) لا تبدأ عملية توليد، لذا تحمل قيودها generation_id: null ويُميَّز بينها بواسطة tool.

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