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

  1. Create a free Mizan account and verify your email.
  2. Open My account → API keys, balance and usage. Create a key and top up your balance.
  3. 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.

FieldDefaultWhat it does
topicrequiredThe question, 10–255 characters. An Arabic question is always an Arabic debate.
langenen or ar.
dialectmsaArabic only: msa (Modern Standard), eg (Egyptian) or sa (Saudi).
positionschosen by MizanThe two sides: [{title, description}, {title, description}]. POST /v1/positions suggests them for free.
visibilityprivateprivate: an unlisted page. public: also listed in the Mizan gallery, if the finished debate passes the safety check.
webhook_urlnoneAn https address that is told when the debate is delivered or failed.
referencenoneYour 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
}

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:

HTTPCodeWhat to do
400invalid_request, topic_too_short, invalid_webhook_urlFix the request.
401invalid_api_keyThe key is missing, wrong or revoked.
402insufficient_balanceTop up your balance.
404not_foundNo debate with this id on your account.
409in_progress, not_deliveredWait, then try again.
422topic_flaggedThe topic didn't pass the safety check. Rephrase it. You were not charged.
429rate_limited, too_many_runningSlow down; see Retry-After.
503try_againMizan is busy or waking up. Try again in a minute. You were not charged.

Limits

Prices

US$5 per debate, from a prepaid balance. There's no subscription, and bigger top-ups add more:

Get an API key

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

Questions or a bigger plan? Write to [email protected].