Skip to main content
Glama
Sign In

api

by video.quiz
OverviewDiscussionsAdmin

Generate a quiz with AI

quiz_video_generate_quiz

AI-generate and save a quiz from a topic. Prefer providing themeDescription or themeCustomization; when omitted, the server derives and saves a topic-based custom theme. Omit backgroundMusicId to use default YouTube-safe shared background music, or set null for silent. The response data always includes a watchUrl (the public quiz-viewer page, instantly playable). When autoRender is true, data.render also contains the queued render session so the agent can poll quiz_video_get_render for the MP4.

Input Schema

NameRequiredDescriptionDefault
topicYesSubject the AI should build the quiz around. Can be a short topic or a detailed multi-paragraph brief (up to 20,000 characters).
formatNoOutput aspect ratio. Defaults to "tiktok".
quizTypeNoQuiz mechanic to generate.
templateNoVisual template id. If omitted, the saved custom theme can suggest a matching template.
autoRenderNoIf true, immediately queue a video render for the new quiz. The render session (sessionId, status) is returned under `data.render`; poll quiz_video_get_render with that sessionId for progress and the final videoUrl. Rendering typically takes 1-5 minutes. Quiz creation is not blocked by render-queue failures — the quiz is returned either way.
difficultyNoTarget difficulty level.
musicVolumeNoBackground music volume from 0 (silent) to 1 (full). Default 0.15.
extraDirectionNoAdditional instructions to steer the AI (tone, focus areas, exclusions). Up to 20,000 characters.
countdownSecondsNoSeconds of countdown shown before each question (3-15).
progressBarStyleNoCountdown progress indicator style.
themeDescriptionNoNatural-language custom visual theme prompt. Example: "golden luxury game show", "ocean glass", or "cyber neon".
answerOptionCountNoFor multiple-choice quizzes, generate 3 or 4 answer options per question. Defaults to 4.
backgroundMusicIdNoBackground music track id from /api/v1/music. Omit to use the default YouTube-safe shared track; set null for silent.
numberOfQuestionsNoHow many questions to generate (1–200).
themeCustomizationNoExplicit custom theme to save and apply to the generated quiz. Use themeDescription for prompt-style themes.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changed
    • changedInput schema / properties / extraDirection / description
      Previous value: -"Additional instructions to steer the AI (tone, focus areas, exclusions)."New value: +"Additional instructions to steer the AI (tone, focus areas, exclusions). Up to 20,000 characters."
    • addedInput schema / properties / extraDirection / maxLength
      Added value: +20000
    • addedInput schema / properties / themeDescription / maxLength
      Added value: +20000
    • changedInput schema / properties / topic / description
      Previous value: -"Subject the AI should build the quiz around."New value: +"Subject the AI should build the quiz around. Can be a short topic or a detailed multi-paragraph brief (up to 20,000 characters)."
    • addedInput schema / properties / topic / maxLength
      Added value: +20000
  2. Changed1 schema field changed
    • changedInput schema / properties / backgroundMusicId / description
      Previous value: -"Background music track id from /api/v1/music. Omit to use the default shared track; set null for silent."New value: +"Background music track id from /api/v1/music. Omit to use the default YouTube-safe shared track; set null for silent."
  3. Changed2 schema fields changed
    • changedInput schema / properties / numberOfQuestions / description
      Previous value: -"How many questions to generate (1–20)."New value: +"How many questions to generate (1–200)."
    • changedInput schema / properties / numberOfQuestions / maximum
      Previous value: -20New value: +200
  4. Changed1 schema field changed
    • addedInput schema / properties / answerOptionCount
      Added value: +{
+  "description": "For multiple-choice quizzes, generate 3 or 4 answer options per question. Defaults to 4.",
+  "enum": [
+    3,
+    4
+  ],
+  "type": "number"
+}
  5. First observed

TDQS

A4.5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the annotations (which only declare write/openWorld/non-idempotent) by disclosing the async render lifecycle, the 1-5 minute render latency, the polling tool to use, and the failure-tolerance rule that queued-render failures do not block quiz creation. It also names the response fields (watchUrl, render session), behavior the annotations cannot convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core action ('AI-generate and save a quiz from a topic') before parameter and response guidance. Three dense sentences, each earning its place; only the music-id sentence mildly duplicates the schema text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 15-parameter tool with a nested theme object and no output schema, the description covers the tricky behaviors well (theme fallback, music default, response shape, render polling). It does not say whether the saved quiz returns an id for later get_quiz/update_quiz calls, which is the one gap an agent chaining tools could hit.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so a baseline of 3 applies, but the description adds genuine meaning: the preference order between themeDescription and themeCustomization plus the server-derived-topic fallback, and the consequence of autoRender on the returned payload. The backgroundMusicId guidance largely restates the schema, so it is not a clean 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource — 'AI-generate and save a quiz from a topic' — where the 'AI-generate from a topic' framing implicitly separates it from the sibling quiz_video_create_quiz (structured/manual creation). An agent can tell what this does and why it differs from its nearest sibling without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear operational guidance: prefer themeDescription or themeCustomization with a stated fallback when both are omitted, omit backgroundMusicId vs set null for silent, and route to quiz_video_get_render when autoRender is true. It never states when to prefer this tool over quiz_video_create_quiz or quiz_video_add_quiz_questions, so tool-level alternatives are left implicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All api toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources