Input Structure
On-Rails API:
{
"grade": "<grade>",
"subject": "<subject>",
"type": "<content_type>",
"difficulty": "<difficulty>",
"locale": "<locale>",
"quantity": "<quantity>",
"skills": {
"lesson_title": "<lesson_title>",
"substandard_id": "<substandard_id>",
"substandard_description": "<substandard_description>"
},
"instructions": "<content_instruction>"
}
Parameters:
grade: Target Grade level, select from these: K, 1, 2, … 10, 11, 12
subject: Subject, select from these: math, ela, science, social-studies, general
type: Content type, select from these: mcq, multi-correct, fill-in, match, article
difficulty: Difficulty level: easy, medium, hard
locale: language-region (e.g., en-AE for English UAE, ar-AE for Arabic UAE, en-IN for English India, etc.)
quantity: Number of samples to generate (1, 2, 5, 10, etc.) — Optional, default value: 1
instruction: Describe the content you want to generate. Required if skills is not passed, optional otherwise
skills: Maps to curriculum defined sub standards (Optional)
- lesson_title from the curriculum data model (Optional)
- substandard_id from the curriculum data model (Optional)
- substandard_description from the curriculum data model (Optional)
- NOTE: substandard_id is matched first. If it matches, lesson_title and substandard_description are ignored. If it fails, title and description are matched semantically.
Example Input
{
"grade": "6",
"subject": "math",
"type": "mcq",
"difficulty": "medium",
"locale": "ar-AE",
"quantity": 1,
"skills": {
"lesson_title": "Finding Area with the Distributive Property",
"substandard_id": "CCSS.MATH.CONTENT.3.MD.C.7.C+1",
"substandard_description": "Use tiling to demonstrate that the area of a rectangle with whole-number side lengths a and b + c equals the sum of the areas a × b and a × c."
},
"instructions": "Use spiderman theme for explanation."
}
Freeform API:
{
"prompt": "Prompt to generate the content."
}
Note: Experimental, Might not always route correctly. Use at your own risk.
Output Structure
{
"generated_content": [
{
"id": "<content_id>",
"request": {
"grade": "<grade>",
"subject": "<subject>",
"type": "<content_type>",
"difficulty": "<difficulty>",
"locale": "<locale>",
"skills": {
"lesson_title": "<lesson_title>",
"substandard_id": "<substandard_id>",
"substandard_description": "<substandard_description>"
},
"instructions": "<content_instruction>"
},
"content": {
// as per type
}
}
]
}
Content Type Schemas
MCQ Type
{
"question": "<question>",
"answer": "<correct_answer_key>",
"answer_explanation": "<answer_explanation>",
"answer_options": [
{ "key": "A", "text": "<option_1>" },
{ "key": "B", "text": "<option_2>" },
{ "key": "C", "text": "<option_3>" },
{ "key": "D", "text": "<option_4>" },
{ "key": "E", "text": "<option_5>" }
],
"image_url": ["<image_url_1>", "<image_url_2>", ...],
"additional_details": "<optional_additional_details>"
}
Note: answer must match one of the keys in answer_options (e.g., “A”, “B”, “C”, “D”, “E”)
Multi-Correct Type
{
"question": "<question>",
"answer": ["<correct_answer_key_1>", "<correct_answer_key_2>", ...],
"answer_explanation": "<answer_explanation>",
"answer_options": [
{ "key": "A", "text": "<option_1>" },
{ "key": "B", "text": "<option_2>" },
{ "key": "C", "text": "<option_3>" }
],
"image_url": ["<image_url_1>", "<image_url_2>", ...],
"additional_details": "<optional_additional_details>"
}
Note: answer is an array of keys from answer_options (e.g., [“A”, “C”])
Fill-In Type
{
"question": "<question>",
"answer": "<correct_answer>",
"answer_explanation": "<answer_explanation>",
"image_url": ["<image_url_1>", "<image_url_2>", ...],
"additional_details": "<optional_additional_details>"
}
Match Type
{
"question": "<instruction_text>",
"answer": {
"a1": "b2",
"a2": "b3",
"a3": "b1"
},
"answer_explanation": "<answer_explanation>",
"column_a": [
{"id": "a1", "content": "<item_1>"},
{"id": "a2", "content": "<item_2>"},
{"id": "a3", "content": "<item_3>"}
],
"column_b": [
{"id": "b1", "content": "<matching_item_1>"},
{"id": "b2", "content": "<matching_item_2>"},
{"id": "b3", "content": "<matching_item_3>"}
],
"image_url": ["<image_url_1>", "<image_url_2>", ...],
"additional_details": "<optional_additional_details>"
}
Article Type
{
"content": "<content_in_markdown_format>",
"additional_details": "<optional_additional_details>"
}
Example Output:
{
"generated_content": [
{
"id": "q1",
"request": {
"grade": "6",
"subject": "math",
"type": "mcq",
"difficulty": "medium",
"locale": "ar-AE",
"skills": {
"lesson_title": "Finding Area with the Distributive Property",
"substandard_id": "CCSS.MATH.CONTENT.3.MD.C.7.C+1",
"substandard_description": "Use tiling to demonstrate that the area of a rectangle with whole-number side lengths a and b + c equals the sum of the areas a × b and a × c."
},
"instructions": "Use spiderman theme for explanation."
},
"content": {
"question": "إذا كان ثمن 2 قلم هو 14 ريالًا، فما ثمن 5 أقلام بنفس المعدل؟",
"answer": "C",
"answer_explanation": "الخطوة 1: تحليل المسألة — لدينا ثمن 2 قلم وهو 14 ريالًا. نحتاج إلى معرفة ثمن 5 أقلام بنفس المعدل. يجب التفكير في العلاقة بين عدد الأقلام والسعر وكيفية تحويل عدد الأقلام بمعدل ثابت.\nالخطوة 2: تطوير الاستراتيجية — يمكننا أولًا إيجاد ثمن قلم واحد بقسمة 14 ÷ 2 = 7 ريال، ثم ضربه في 5 لإيجاد ثمن 5 أقلام: 7 × 5 = 35 ريالًا.\nالخطوة 3: التطبيق والتحقق — نتحقق من منطقية الإجابة بمقارنة السعر بعدد الأقلام. السعر يتناسب طرديًا مع العدد، وبالتالي 35 ريالًا هي الإجابة الصحيحة والمنطقية.",
"answer_options": [
{ "key": "A", "text": "28 ريالًا" },
{ "key": "B", "text": "70 ريالًا" },
{ "key": "C", "text": "35 ريالًا" }
],
"image_url": [],
"additional_details": "🔹 **Question generation logic:**\nThis question targets proportional reasoning for Grade 6 students, testing their ability to apply ratios and unit rates to real-world problems. It follows a classic proportionality structure — starting with a known ratio (2 items for 14 riyals) and scaling it up to 5 items. The stepwise reasoning develops algebraic thinking and promotes estimation checks to confirm logical correctness.\n\n🔹 **Personalized insight examples:**\n- Choosing 28 ريالًا shows a misunderstanding by doubling instead of proportionally scaling.\n- Choosing 7 ريالًا indicates the learner found the unit rate but didn't scale it up to 5.\n- Choosing 14 ريالًا confuses the given 2-item cost with the required 5-item cost.\n\n🔹 **Instructional design & DI integration:**\nThe question aligns with *Percent, Ratio, and Probability* learning targets. In DI format 15.7, it models how equivalent fractions and proportional relationships can predict outcomes across different scales. This builds foundational understanding for probability and proportional reasoning. By using a simple, relatable context (price of pens), it connects mathematical ratios to practical real-world applications, supporting concept transfer and cognitive engagement."
}
}
]
}