AI Quiz Generator — Create Multiple Choice & Short Answer Questions Instantly

Generate structured, fact-checked quizzes on any topic in seconds using AI. This Apify Actor calls a large language model via OpenRouter to produce ready-to-use quiz questions — complete with answer options, correct answers, ideal answers, and explanations — exported as clean JSON.

Perfect for building e-learning platforms, trivia apps, training assessments, revision tools, and automated test sets.

---

Features

• 🧠 Multiple question formats — multiple-choice (4 options + correct answer) and short-answer (ideal answer for grading), both with explanations
• 🎯 Adjustable difficulty — Easy, Medium, or Hard. Hard difficulty actively filters and rewrites any questions that aren't genuinely challenging via a two-pass AI review
• ⚡ Two AI tiers — Standard (cost-effective) and Premium (faster, higher accuracy)
• ✅ Validated output — every response is validated with Pydantic before being saved; failed batches are retried automatically
• 🔄 Smart batching — large quizzes are split across multiple API calls to avoid token limits
• 📦 Clean JSON dataset — flat, camelCase records ready to export as CSV, JSONL, or connect via the Apify API

---

Inputs

Field	Type	Default	Description
topic	String	—	What the quiz is about. Be specific — "Causes of World War I" gives far better results than "History".
total_questions	Integer	10	Total questions to generate. Min: 1, Max: 100.
multiple_choice_count	Integer	7	How many questions should be multiple-choice. The rest will be short-answer. Must not exceed total_questions.
difficulty	Select	medium	easy · medium · hard. On medium/hard, a second AI pass reviews and rewrites any under-difficulty questions.
quality_tier	Select	standard	standard (OpenAI GPT-4o Mini) or premium (Gemini 2.5 Flash Lite). Premium adds a small per-question charge.

Example Input

{
    "topic": "The causes and key events of World War I",
    "total_questions": 20,
    "multiple_choice_count": 14,
    "difficulty": "hard",
    "quality_tier": "premium"
}

---

Output

Each dataset item is one quiz question. Multiple-choice and short-answer questions share the same flat schema — type-specific fields are null when not applicable.

Multiple-Choice Example

{
    "questionNumber": 1,
    "type": "multiple_choice",
    "question": "Which event directly triggered the outbreak of World War I?",
    "options": [
        "The assassination of Archduke Franz Ferdinand",
        "The sinking of the Lusitania",
        "The invasion of Poland",
        "The fall of the Ottoman Empire"
    ],
    "correctAnswer": "The assassination of Archduke Franz Ferdinand",
    "idealAnswer": null,
    "explanation": "The assassination of Archduke Franz Ferdinand in Sarajevo on 28 June 1914 triggered a chain of diplomatic crises that led directly to the outbreak of World War I.",
    "metaTopic": "The causes and key events of World War I",
    "metaDifficulty": "hard",
    "metaQualityTier": "premium",
    "metaModel": "google/gemini-2.5-flash-lite",
    "metaGeneratedAt": "2025-04-24T16:00:00.000000+00:00"
}

Short-Answer Example

{
    "questionNumber": 15,
    "type": "short_answer",
    "question": "What was the name of the military alliance that opposed the Triple Alliance in World War I?",
    "options": null,
    "correctAnswer": null,
    "idealAnswer": "The Triple Entente, consisting of France, Russia, and Great Britain.",
    "explanation": "The Triple Entente was formed by France, Russia, and the United Kingdom. It opposed the Central Powers — the Triple Alliance of Germany, Austria-Hungary, and Italy.",
    "metaTopic": "The causes and key events of World War I",
    "metaDifficulty": "hard",
    "metaQualityTier": "premium",
    "metaModel": "google/gemini-2.5-flash-lite",
    "metaGeneratedAt": "2025-04-24T16:00:00.000000+00:00"
}

Output Field Reference

Field	Type	Description
questionNumber	Number	Sequential position in the quiz (1-indexed)
type	String	"multiple_choice" or "short_answer"
question	String	The full question text
options	Array / null	Four answer choices — multiple-choice only
correctAnswer	String / null	Exact text of the correct option — multiple-choice only
idealAnswer	String / null	Model answer for grading — short-answer only
explanation	String	Why the answer is correct. Useful for learning and review.
metaTopic	String	The topic provided as input
metaDifficulty	String	Difficulty level: "easy", "medium", or "hard"
metaQualityTier	String	"standard" or "premium"
metaModel	String	OpenRouter model slug used to generate the question
metaGeneratedAt	Date	ISO 8601 UTC timestamp

---

Difficulty Levels

Level	Target Audience	How It Works
🟢 Easy	Anyone	Well-known facts. Distractors are clearly wrong to someone with basic familiarity.
🟡 Medium	Enthusiasts	Requires specific knowledge. Distractors need careful thought to eliminate. Includes an AI review pass.
🔴 Hard	Experts & specialists	Niche details, exact dates, minor characters, production trivia. Forbidden from asking any "famous" facts. Distractors must be real entities from the same domain. Includes a strict AI review and rewrite pass.

---

Quality Tiers

Tier	Model	Best For
⚡ Standard	openai/gpt-4o-mini	General topics, high volume, cost-sensitive use
🏆 Premium	google/gemini-2.5-flash-lite	Technical, academic, or specialised topics needing higher accuracy (+charge per question)

---

Setup

This Actor requires an OpenRouter API key. Add it as an encrypted secret environment variable in your Actor's settings.

Steps

1. Get a free API key at openrouter.ai/keys
2. In the Apify Console, go to your Actor → Settings → Environment variables
3. Add a variable named OPENROUTER_API_KEY, paste your key, and toggle Secret ✅

Environment Variables

Variable	Required	Default	Description
OPENROUTER_API_KEY	✅ Yes	—	Your OpenRouter API key
OPENROUTER_MODEL_STANDARD	No	openai/gpt-4o-mini	Override the standard-tier model
OPENROUTER_MODEL_PREMIUM	No	google/gemini-2.5-flash-lite	Override the premium-tier model

---

How It Works

1. Validate inputs — fails immediately with a clear message if anything is misconfigured
2. Plan batches — splits your question count into batches of ≤12 to stay within LLM token limits, distributing MCQ and short-answer questions evenly
3. Generate — each batch is sent to the LLM with a structured system prompt at temperature 0.3 for factual accuracy
4. Validate — every batch is validated with Pydantic; invalid batches are retried up to 3 times
5. Critique (medium/hard only) — a second LLM call reviews the batch and rewrites any questions that don't meet the difficulty standard
6. Push — validated records are pushed to the Apify dataset as flat, camelCase JSON

---

Use Cases

• 📚 E-learning & LMS platforms — auto-generate quizzes for any lesson or module
• 🎓 Student revision tools — create practice tests and flashcard-style question sets
• 🧩 Trivia & quiz apps — bulk-generate questions across topics and difficulties
• 📊 Corporate training & HR — build knowledge-check assessments at scale
• 🤖 LLM benchmarking — generate domain-specific evaluation sets
• 🧪 Research — create question datasets for NLP and education research

---

Tips for Best Results

• Be specific with your topic. "Mitochondrial DNA replication in eukaryotes" produces much better questions than "Biology".
• Use a 70/30 MCQ-to-short-answer split. A good default for most learning contexts.
• Use Hard + Premium for specialist domains. Medical, legal, and highly technical topics benefit most from both settings.
• Test with 10 questions first. Validate the quality before generating a full set of 100.
• Run multiple times for variety. Each run generates a fresh set — useful for building large question banks.

---

Pricing

• Standard tier — no additional charge beyond Apify compute fees.
• Premium tier — a small Pay Per Event charge is applied per successfully generated question.

---

License

MIT