For developers
The Mizan API
Order debates from your own app or website. You send a question, and both sides are argued by GPT and Claude. A few minutes later you get a page, the audio, the transcript and videos, in English or Arabic (Modern Standard, Egyptian or Saudi). Each debate costs US$5.
Quick start
- Create a free Mizan account and verify your email.
- Open My account → API keys, balance and usage. Create a key and top up your balance.
- Order your first debate with curl, Python or 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);
Every call goes to https://api.mizandebates.com and sends your key as Authorization: Bearer mz_live_…. Keep the key on your server: never put it in a web page or a mobile app.
Order a debate
POST /v1/debates answers at once with 202 and the debate's id, status queued. US$5 is taken from your balance. Making the debate takes about 5–10 minutes.
| Field | Default | What it does |
|---|---|---|
topic | required | The question, 10–255 characters. An Arabic question is always an Arabic debate. |
lang | en | en or ar. |
dialect | msa | Arabic only: msa (Modern Standard), eg (Egyptian) or sa (Saudi). |
positions | chosen by Mizan | The two sides: [{title, description}, {title, description}]. POST /v1/positions suggests them for free. |
visibility | private | private: an unlisted page. public: also listed in the Mizan gallery, if the finished debate passes the safety check. |
webhook_url | none | An https address that is told when the debate is delivered or failed. |
reference | none | Your own id for this debate, sent back as is. |
Send an Idempotency-Key header (any id, up to 64 characters). If a call is retried with the same key, you get the same debate back and you're only charged once. The client packages do this for you.
An Arabic debate in Egyptian, with your own two sides:
{"topic": "هل العمل من المنزل أفضل من العمل في المكتب؟",
"lang": "ar", "dialect": "eg",
"positions": [{"title": "المنزل أفضل", "description": "وقت أكثر وتركيز أعلى"},
{"title": "المكتب أفضل", "description": "تعاون أسرع وفصل بين العمل والبيت"}]}
Status and result
GET /v1/debates/{id} returns the debate. Its status is queued, then generating, then delivered (with a result) or failed (with an error). A failed debate is never charged: the money goes back to your balance automatically.
{
"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: The delivered debate as JSON: who said what, round by round.GET /v1/debates?limit=10: Your latest debates.POST /v1/positions: The two sides Mizan would argue for a topic. Free, up to 30 an hour.GET /v1/balance: Your balance, the price of a debate and how many debates it covers.GET /v1/usage: Calls per day, debates and spending over the last 30 days, and your latest debates.
Webhooks
If you set webhook_url, Mizan sends it a POST when the debate is ready (debate.delivered) or couldn't be made (debate.failed). The body is {id, type, created_at, data}, where data is the debate. Answer with any 2xx code. Mizan tries 3 times.
Every webhook is signed: Mizan-Signature: t=<unix time>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">, using your key's webhook secret (whsec_mz_…, on your API page). Check it, and reject webhooks older than 5 minutes:
# 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);
});
Errors
An error is always {"error": {"code": …, "message": …}}. Your app can rely on the code:
| HTTP | Code | What to do |
|---|---|---|
400 | invalid_request, topic_too_short, invalid_webhook_url | Fix the request. |
401 | invalid_api_key | The key is missing, wrong or revoked. |
402 | insufficient_balance | Top up your balance. |
404 | not_found | No debate with this id on your account. |
409 | in_progress, not_delivered | Wait, then try again. |
422 | topic_flagged | The topic didn't pass the safety check. Rephrase it. You were not charged. |
429 | rate_limited, too_many_running | Slow down; see Retry-After. |
503 | try_again | Mizan is busy or waking up. Try again in a minute. You were not charged. |
Limits
- 60 calls a minute per key, and 10 new debates a minute.
- Up to 5 debates in progress at once per account.
- Up to 5 keys per account. Revoke a key at any time on your API page.
Prices
US$5 per debate, from a prepaid balance. There's no subscription, and bigger top-ups add more:
- Pay US$25 → US$25 balance (5 debates, US$5.00 each)
- Pay US$90 → US$100 balance (20 debates, US$4.50 each)
- Pay US$400 → US$500 balance (100 debates, US$4.00 each)
Client packages
Small, dependency-free clients that retry safely and check webhook signatures:
Save the file next to your code. pip and npm packages are coming.
Terms of use
- Every debate shows both sides. Mizan never declares a winner or gives a verdict.
- Topics and finished debates are checked for safety. Topics that promote hate, violence or harm aren't debated, and a public debate that fails the check stays private.
- Debates and every voice in them are made by AI. They are for education and entertainment, and are not medical, legal or financial advice. Say so wherever you show them.
- You may use the debates you order in your own products. Don't present them as real people's views.
- Keep your keys secret. Calls made with your key are charged to your balance. If a key leaks, revoke it.
- A debate that fails or is held for review is refunded to your balance automatically.
- Mizan may suspend a key that's used to get around these terms or the safety checks.
Questions or a bigger plan? Write to [email protected].