للمطوّرين

واجهة ميزان البرمجية (API)

اطلب المناظرات من تطبيقك أو موقعك. ترسل سؤالًا، فيعرض GPT وClaude الرأيين. وبعد دقائق تحصل على صفحة والملف الصوتي والنص والفيديوهات، بالعربية (الفصحى أو المصرية أو السعودية) أو الإنجليزية. تكلفة المناظرة 5 دولارات أمريكية.

البدء السريع

  1. أنشئ حسابًا مجانيًا في ميزان وأكّد بريدك.
  2. افتح «حسابي» ← «مفاتيح الـAPI والرصيد والاستخدام». أنشئ مفتاحًا واشحن رصيدك.
  3. اطلب أول مناظرة باستخدام curl أو Python أو JavaScript:
curl https://api.mizandebates.com/v1/debates \
  -H "Authorization: Bearer $MIZAN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f9c2e1a-order-42" \
  -d '{"topic": "Is tea better than coffee?", "lang": "en",
       "webhook_url": "https://example.com/hooks/mizan"}'

Python

from mizan_debates import Mizan

mizan = Mizan("mz_live_...")          # or set MIZAN_API_KEY
debate = mizan.create_debate("Is tea better than coffee?", lang="en")
debate = mizan.wait_for_debate(debate["id"])   # or wait for the webhook
print(debate["result"]["page_url"], debate["result"]["audio_url"])

JavaScript

import { Mizan } from "./mizan-debates.js";

const mizan = new Mizan("mz_live_...");   // or set MIZAN_API_KEY
let debate = await mizan.createDebate({ topic: "Is tea better than coffee?" });
debate = await mizan.waitForDebate(debate.id);   // or wait for the webhook
console.log(debate.result.page_url);

كل طلب يُرسل إلى https://api.mizandebates.com ومعه مفتاحك في الترويسة Authorization: Bearer mz_live_…. احفظ المفتاح على خادمك، ولا تضعه أبدًا في صفحة ويب أو تطبيق جوال.

اطلب مناظرة

يردّ POST /v1/debates فورًا بالرمز 202 ومعرّف المناظرة وحالتها queued. ويُخصم 5 دولارات من رصيدك. يستغرق إعداد المناظرة نحو 5 إلى 10 دقائق.

الحقلالافتراضيوظيفته
topicمطلوبالسؤال، من 10 إلى 255 حرفًا. السؤال العربي يعني دائمًا مناظرة عربية.
langenen أو ar.
dialectmsaللعربية فقط: msa (الفصحى) أو eg (المصرية) أو sa (السعودية).
positionsيختارهما ميزانالرأيان: [{title, description}, {title, description}]. ويقترحهما POST /v1/positions مجانًا.
visibilityprivateprivate: صفحة غير مُدرجة. public: تظهر أيضًا في معرض ميزان إذا اجتازت المناظرة فحص الأمان.
webhook_urlلا يوجدعنوان https يُبلَّغ عند جاهزية المناظرة أو تعذّرها.
referenceلا يوجدمعرّفك الخاص لهذه المناظرة، يُعاد إليك كما هو.

أرسل الترويسة Idempotency-Key (أي معرّف حتى 64 حرفًا). إذا أُعيد الطلب بالمفتاح نفسه تحصل على المناظرة نفسها، ولا يُخصم المبلغ إلا مرة واحدة. والحزم البرمجية تفعل ذلك تلقائيًا.

مناظرة عربية باللهجة المصرية، برأيين من اختيارك:

{"topic": "هل العمل من المنزل أفضل من العمل في المكتب؟",
 "lang": "ar", "dialect": "eg",
 "positions": [{"title": "المنزل أفضل", "description": "وقت أكثر وتركيز أعلى"},
               {"title": "المكتب أفضل", "description": "تعاون أسرع وفصل بين العمل والبيت"}]}

الحالة والنتيجة

يعيد GET /v1/debates/{id} المناظرة. حالتها queued ثم generating ثم delivered (ومعها النتيجة) أو failed (ومعها الخطأ). المناظرة المتعذّرة لا تُحتسب أبدًا: يعود المبلغ إلى رصيدك تلقائيًا.

{
  "id": "api-3f9a6c1e0b2d4e5f6a7b",
  "object": "debate",
  "status": "delivered",
  "topic": "Is tea better than coffee?",
  "lang": "en", "dialect": "msa", "visibility": "private",
  "positions": [{"title": "Tea Is Gentler", "description": "..."},
                {"title": "Coffee Is Stronger", "description": "..."}],
  "reference": "order-42", "price_usd": 5.0, "charged": true,
  "created_at": "2026-11-21T10:00:00+00:00",
  "result": {
    "page_url": "https://orders.mizandebates.com/d/k7f3x9q2mz/index.html",
    "audio_url": "https://orders.mizandebates.com/d/k7f3x9q2mz/debate.mp3",
    "transcript_url": "https://orders.mizandebates.com/d/k7f3x9q2mz/transcript.txt",
    "video_highlights_url": "https://orders.mizandebates.com/d/k7f3x9q2mz/highlight.mp4",
    "video_full_url": "https://orders.mizandebates.com/d/k7f3x9q2mz/full-debate.mp4",
    "minutes": 9, "published_as": "private", "seconds_to_make": 312
  },
  "error": null
}

الـWebhooks

إذا حدّدت webhook_url يرسل إليه ميزان طلب POST عندما تجهز المناظرة (debate.delivered) أو تتعذّر (debate.failed). المحتوى هو {id, type, created_at, data} حيث data هي المناظرة. ردّ بأي رمز 2xx. ويحاول ميزان 3 مرات.

كل Webhook موقَّع: Mizan-Signature: t=<unix time>,v1=<hex HMAC-SHA256 of "<t>.<raw body>"> باستخدام سرّ الـWebhook الخاص بمفتاحك (whsec_mz_… في صفحة الـAPI). تحقّق منه، وارفض ما مضى عليه أكثر من 5 دقائق:

# Python (Flask): check the signature with the RAW body
from mizan_debates import verify_webhook

@app.post("/hooks/mizan")
def mizan_hook():
    event = verify_webhook(request.get_data(), request.headers["Mizan-Signature"], WEBHOOK_SECRET)
    if event["type"] == "debate.delivered":
        save(event["data"]["id"], event["data"]["result"])
    return "", 200

// JavaScript (Express): express.raw() keeps the body as bytes
import { verifyWebhook } from "./mizan-debates.js";
app.post("/hooks/mizan", express.raw({ type: "application/json" }), async (req, res) => {
  const event = await verifyWebhook(req.body, req.get("Mizan-Signature"), WEBHOOK_SECRET);
  res.sendStatus(200);
});

الأخطاء

الخطأ دائمًا بالشكل {"error": {"code": …, "message": …}}. ويمكن لتطبيقك الاعتماد على الرمز:

HTTPالرمزماذا تفعل
400invalid_request, topic_too_short, invalid_webhook_urlصحّح الطلب.
401invalid_api_keyالمفتاح مفقود أو خاطئ أو ملغى.
402insufficient_balanceاشحن رصيدك.
404not_foundلا توجد مناظرة بهذا المعرّف في حسابك.
409in_progress, not_deliveredانتظر ثم أعد المحاولة.
422topic_flaggedلم يجتز الموضوع فحص الأمان. أعد صياغته. لم يُخصم منك شيء.
429rate_limited, too_many_runningأبطئ قليلًا؛ راجع Retry-After.
503try_againميزان مشغول أو يستيقظ. أعد المحاولة بعد دقيقة. لم يُخصم منك شيء.

الحدود

الأسعار

5 دولارات للمناظرة من رصيد مدفوع مسبقًا. لا اشتراك، والشحن الأكبر يضيف أكثر:

احصل على مفتاح API

الحزم البرمجية

عملاء صغار بلا اعتماديات، يعيدون المحاولة بأمان ويتحقّقون من توقيع الـWebhooks:

احفظ الملف بجوار شيفرتك. حزم pip وnpm قريبًا.

شروط الاستخدام

لديك سؤال أو تحتاج خطة أكبر؟ راسلنا على [email protected].