للمطوّرين
واجهة ميزان البرمجية (API)
اطلب المناظرات من تطبيقك أو موقعك. ترسل سؤالًا، فيعرض GPT وClaude الرأيين. وبعد دقائق تحصل على صفحة والملف الصوتي والنص والفيديوهات، بالعربية (الفصحى أو المصرية أو السعودية) أو الإنجليزية. تكلفة المناظرة 5 دولارات أمريكية.
البدء السريع
- أنشئ حسابًا مجانيًا في ميزان وأكّد بريدك.
- افتح «حسابي» ← «مفاتيح الـAPI والرصيد والاستخدام». أنشئ مفتاحًا واشحن رصيدك.
- اطلب أول مناظرة باستخدام 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 حرفًا. السؤال العربي يعني دائمًا مناظرة عربية. |
lang | en | en أو ar. |
dialect | msa | للعربية فقط: msa (الفصحى) أو eg (المصرية) أو sa (السعودية). |
positions | يختارهما ميزان | الرأيان: [{title, description}, {title, description}]. ويقترحهما POST /v1/positions مجانًا. |
visibility | private | private: صفحة غير مُدرجة. 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
}
GET /v1/debates/{id}/transcript: المناظرة الجاهزة بصيغة JSON: من قال ماذا، جولة بعد جولة.GET /v1/debates?limit=10: أحدث مناظراتك.POST /v1/positions: الرأيان اللذان سيعرضهما ميزان لموضوع ما. مجانًا، حتى 30 مرة في الساعة.GET /v1/balance: رصيدك وسعر المناظرة وعدد المناظرات التي يكفيها.GET /v1/usage: الطلبات يوميًا والمناظرات والمصروف خلال آخر 30 يومًا، وأحدث مناظراتك.
الـ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 | الرمز | ماذا تفعل |
|---|---|---|
400 | invalid_request, topic_too_short, invalid_webhook_url | صحّح الطلب. |
401 | invalid_api_key | المفتاح مفقود أو خاطئ أو ملغى. |
402 | insufficient_balance | اشحن رصيدك. |
404 | not_found | لا توجد مناظرة بهذا المعرّف في حسابك. |
409 | in_progress, not_delivered | انتظر ثم أعد المحاولة. |
422 | topic_flagged | لم يجتز الموضوع فحص الأمان. أعد صياغته. لم يُخصم منك شيء. |
429 | rate_limited, too_many_running | أبطئ قليلًا؛ راجع Retry-After. |
503 | try_again | ميزان مشغول أو يستيقظ. أعد المحاولة بعد دقيقة. لم يُخصم منك شيء. |
الحدود
- 60 طلبًا في الدقيقة لكل مفتاح، و10 مناظرات جديدة في الدقيقة.
- حتى 5 مناظرات قيد الإعداد في الوقت نفسه لكل حساب.
- حتى 5 مفاتيح لكل حساب. ويمكنك إلغاء أي مفتاح في أي وقت من صفحة الـAPI.
الأسعار
5 دولارات للمناظرة من رصيد مدفوع مسبقًا. لا اشتراك، والشحن الأكبر يضيف أكثر:
- ادفع 25 دولارًا ← رصيد 25 دولارًا (5 مناظرة، 5.00 دولار للواحدة)
- ادفع 90 دولارًا ← رصيد 100 دولارًا (20 مناظرة، 4.50 دولار للواحدة)
- ادفع 400 دولارًا ← رصيد 500 دولارًا (100 مناظرة، 4.00 دولار للواحدة)
الحزم البرمجية
عملاء صغار بلا اعتماديات، يعيدون المحاولة بأمان ويتحقّقون من توقيع الـWebhooks:
احفظ الملف بجوار شيفرتك. حزم pip وnpm قريبًا.
شروط الاستخدام
- كل مناظرة تعرض الرأيين. لا يعلن ميزان فائزًا ولا يصدر حكمًا أبدًا.
- تُفحص المواضيع والمناظرات الجاهزة للتأكد من سلامتها. المواضيع التي تروّج للكراهية أو العنف أو الأذى لا تُناقش، والمناظرة العامة التي لا تجتاز الفحص تبقى خاصة.
- المناظرات وكل الأصوات فيها من إنتاج الذكاء الاصطناعي، وهي للتعليم والترفيه، وليست نصيحة طبية أو قانونية أو مالية. اذكر ذلك حيثما تعرضها.
- يمكنك استخدام المناظرات التي تطلبها في منتجاتك. لا تقدّمها على أنها آراء أشخاص حقيقيين.
- احفظ مفاتيحك سرًّا. الطلبات المرسلة بمفتاحك تُخصم من رصيدك. وإذا تسرّب مفتاح فألغِه.
- المناظرة المتعذّرة أو المعلّقة للمراجعة يعود مبلغها إلى رصيدك تلقائيًا.
- يحق لميزان إيقاف أي مفتاح يُستخدم للالتفاف على هذه الشروط أو على فحوص الأمان.
لديك سؤال أو تحتاج خطة أكبر؟ راسلنا على [email protected].