Quiz.Video MCP: list, create, AI-generate, and render quiz and flashcard videos.
Maintain this server? Claim it
Call this server's tools from your browser. Nothing to install.
Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.
Tool list from our last check. Connect live to refresh it.
Return the Quiz.Video API catalog linkset for agent discovery.
This tool takes no arguments.
Return the Quiz.Video API catalog linkset for agent discovery.
No arguments.
{
"type": "object",
"properties": {},
"additionalProperties": false
}Return the GET /api/v1 index: documentation and OpenAPI URLs, OAuth/API-key auth metadata, rate-limit and versioning policy, and every resource URL.
No arguments.
{
"type": "object",
"properties": {},
"additionalProperties": false
}Return a compact LLM-readable summary of the Quiz.Video API.
No arguments.
{
"type": "object",
"properties": {},
"additionalProperties": false
}Return the Quiz.Video OpenAPI 3.1 specification.
No arguments.
{
"type": "object",
"properties": {},
"additionalProperties": false
}Append one or more questions (with their answers and optional images) to an existing quiz.
| Argument | Type | Description |
|---|---|---|
| quizId* | string | Quiz ID in YouTube-style 11-character base64url format. |
| questions* | array | One or more questions to append to the quiz. |
{
"type": "object",
"required": [
"quizId",
"questions"
],
"properties": {
"quizId": {
"type": "string",
"minLength": 1,
"description": "Quiz ID in YouTube-style 11-character base64url format."
},
"questions": {
"type": "array",
"items": {
"type": "object",
"required": [
"questionText"
],
"properties": {
"order": {
"type": "number",
"description": "1-indexed display order of the question within the quiz."
},
"images": {
"type": "array",
"items": {
"type": "object",
"required": [
"url"
],
"properties": {
"alt": {
"type": "string",
"description": "Alt text describing the image for accessibility."
},
"url": {
"type": "string",
"description": "Absolute URL of the image asset."
},
"width": {
"type": "number",
"description": "Image width in pixels."
},
"height": {
"type": "number",
"description": "Image height in pixels."
},
"source": {
"type": "string",
"description": "Image source label, e.g. \"upload\", \"unsplash\", \"generated\"."
},
"sourceUrl": {
"type": "string",
"description": "Original attribution URL for the image, if any."
}
},
"additionalProperties": true
},
"description": "Additional images attached to the question (in addition to imagePath)."
},
"answers": {
"type": "array",
"items": {
"type": "object",
"required": [
"answerText",
"isCorrect"
],
"properties": {
"order": {
"type": "number",
"description": "1-indexed display order of the answer within the question."
},
"ttsText": {
"type": "string",
"description": "Optional exact narration line for the answer reveal."
},
"isCorrect": {
"type": "boolean",
"description": "Whether this answer is the correct one for the question."
},
"answerText": {
"type": "string",
"minLength": 1,
"description": "Answer text shown to viewers."
},
"additionalInfo": {
"type": "string",
"description": "Optional explanation or trivia shown after the answer is revealed."
}
},
"additionalProperties": false
},
"description": "Answer options for this question; exactly one should be marked isCorrect=true."
},
"ttsText": {
"type": "string",
"description": "Optional exact narration line for this question."
},
"duration": {
"type": "number",
"minimum": 1,
"description": "Seconds viewers have to answer this question (must be >= 1)."
},
"imagePath": {
"type": "string",
"description": "Optional primary image URL shown with the question (used by picture_guess quizzes)."
},
"questionText": {
"type": "string",
"minLength": 1,
"description": "The question prompt shown to viewers."
}
},
"additionalProperties": true
},
"minItems": 1,
"description": "One or more questions to append to the quiz."
}
},
"additionalProperties": false
}Apply a snapshot of a custom template to one or more quizzes you own. Sets each quiz's template field to "custom" and writes the snapshot into themeCustomization.customTemplate. Future edits to the source template do not auto-propagate.
| Argument | Type | Description |
|---|---|---|
| quizIds* | array | Quiz ids to apply the template to. |
| templateId* | string |
{
"type": "object",
"required": [
"templateId",
"quizIds"
],
"properties": {
"quizIds": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"minItems": 1,
"description": "Quiz ids to apply the template to."
},
"templateId": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": false
}Create a flashcard deck. Required: title (3-120 chars) and cards[] (min 1). Optional: description (≤1200 chars), tags (≤50 each).
| Argument | Type | Description |
|---|---|---|
| tags | array | Optional tags to categorize the deck (≤50 characters each). |
| cards* | array | Flashcards in the deck; at least one card is required. |
| title* | string | Deck title (3–120 characters). |
| description | string | Optional deck description (≤1200 characters). |
{
"type": "object",
"required": [
"title",
"cards"
],
"properties": {
"tags": {
"type": "array",
"items": {
"type": "string",
"maxLength": 50
},
"description": "Optional tags to categorize the deck (≤50 characters each)."
},
"cards": {
"type": "array",
"items": {
"type": "object",
"required": [
"front",
"back"
],
"properties": {
"back": {
"type": "string",
"minLength": 1,
"description": "Text shown on the back of the flashcard (the answer)."
},
"hint": {
"type": "string",
"description": "Optional hint shown before revealing the back of the card."
},
"front": {
"type": "string",
"minLength": 1,
"description": "Text shown on the front of the flashcard (the prompt)."
},
"order": {
"type": "number",
"description": "1-indexed display order of the card within the deck."
}
},
"additionalProperties": false
},
"minItems": 1,
"description": "Flashcards in the deck; at least one card is required."
},
"title": {
"type": "string",
"maxLength": 120,
"minLength": 3,
"description": "Deck title (3–120 characters)."
},
"description": {
"type": "string",
"maxLength": 1200,
"description": "Optional deck description (≤1200 characters)."
}
},
"additionalProperties": false
}Create a quiz. Prefer sending themeDescription or themeCustomization so the saved quiz has a custom visual theme; if omitted, the server derives one from the title/description. Omit backgroundMusicId to use default YouTube-safe shared background music, or set null for silent. Required: title. Optional: description, format, quizType, template, countdownSeconds, difficulty, musicVolume, and questions[].
| Argument | Type | Description |
|---|---|---|
| title* | string | Human-readable quiz title. |
| format | string | Output aspect ratio: "tiktok" (9:16 vertical) or "youtube" (16:9 horizontal). |
| quizType | string | Quiz mechanic: multiple_choice, reveal_answer, or picture_guess. |
| template | string | Visual template id (e.g. "neon", "minimal"). |
| questions | array | Optional initial questions with their answers and images. |
| difficulty | string | Target difficulty level for the generated/created quiz. |
| description | string | Optional longer description shown on the quiz page. |
| musicVolume | number | Background music volume from 0 (silent) to 1 (full). Default 0.15. |
Create a hook for a quiz. `hook` is a pass-through object whose fields follow the HookInput schema (see OpenAPI spec).
| Argument | Type | Description |
|---|---|---|
| hook* | object | HookInput object (hookType, positionType, title, content, plus optional styling — see OpenAPI spec). |
| quizId* | string | Quiz ID in YouTube-style 11-character base64url format. |
{
"type": "object",
"required": [
"quizId",
"hook"
],
"properties": {
"hook": {
"type": "object",
"properties": {},
"description": "HookInput object (hookType, positionType, title, content, plus optional styling — see OpenAPI spec).",
"additionalProperties": true
},
"quizId": {
"type": "string",
"minLength": 1,
"description": "Quiz ID in YouTube-style 11-character base64url format."
}
},
"additionalProperties": false
}Queue a new video render for an existing quiz. Returns the render sessionId; poll quiz_video_get_render until its status is "completed" (typically 1-5 minutes), then call quiz_video_download_render to obtain the signed MP4 URL. The quiz itself is viewable immediately at /quiz/{slug}/ regardless of render status.
| Argument | Type | Description |
|---|---|---|
| quizId* | string | ID of the quiz to render into a video. |
{
"type": "object",
"required": [
"quizId"
],
"properties": {
"quizId": {
"type": "string",
"minLength": 1,
"description": "ID of the quiz to render into a video."
}
},
"additionalProperties": false
}Save a new custom template authored in the drag-and-drop editor. Required: template (the CustomTemplate JSON). Optional: name, description, thumbnail, isDefault, isPublic.
| Argument | Type | Description |
|---|---|---|
| name | string | |
| isPublic | boolean | Make discoverable to other users. |
| template* | object | CustomTemplate JSON with scenes.hook/question/answer and canvas. |
| isDefault | boolean | Mark as your default template (replaces any existing default). |
| thumbnail | string | Optional preview image URL or data URI. |
| description | string |
{
"type": "object",
"required": [
"template"
],
"properties": {
"name": {
"type": "string",
"maxLength": 120,
"minLength": 1
},
"isPublic": {
"type": "boolean",
"description": "Make discoverable to other users."
},
"template": {
"type": "object",
"description": "CustomTemplate JSON with scenes.hook/question/answer and canvas."
},
"isDefault": {
"type": "boolean",
"description": "Mark as your default template (replaces any existing default)."
},
"thumbnail": {
"type": "string",
"description": "Optional preview image URL or data URI."
},
"description": {
"type": "string",
"maxLength": 280
}
},
"additionalProperties": false
}Permanently delete a flashcard deck and all of its cards.
| Argument | Type | Description |
|---|---|---|
| deckId* | string | Flashcard deck ID. |
{
"type": "object",
"required": [
"deckId"
],
"properties": {
"deckId": {
"type": "string",
"minLength": 1,
"description": "Flashcard deck ID."
}
},
"additionalProperties": false
}Permanently delete a quiz and all of its questions, answers, and hooks.
| Argument | Type | Description |
|---|---|---|
| quizId* | string | Quiz ID in YouTube-style 11-character base64url format. |
{
"type": "object",
"required": [
"quizId"
],
"properties": {
"quizId": {
"type": "string",
"minLength": 1,
"description": "Quiz ID in YouTube-style 11-character base64url format."
}
},
"additionalProperties": false
}Delete a single hook from a quiz.
| Argument | Type | Description |
|---|---|---|
| hookId* | number | Numeric id of the hook to delete. |
| quizId* | string | Quiz ID in YouTube-style 11-character base64url format. |
{
"type": "object",
"required": [
"quizId",
"hookId"
],
"properties": {
"hookId": {
"type": "number",
"description": "Numeric id of the hook to delete."
},
"quizId": {
"type": "string",
"minLength": 1,
"description": "Quiz ID in YouTube-style 11-character base64url format."
}
},
"additionalProperties": false
}Permanently delete a custom template you own. Quizzes that have a snapshot of this template are unaffected — the snapshot remains in their themeCustomization.
| Argument | Type | Description |
|---|---|---|
| templateId* | string |
{
"type": "object",
"required": [
"templateId"
],
"properties": {
"templateId": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": false
}Request a signed download URL for a completed render.
| Argument | Type | Description |
|---|---|---|
| sessionId* | string | Render session id for a completed render. |
{
"type": "object",
"required": [
"sessionId"
],
"properties": {
"sessionId": {
"type": "string",
"minLength": 1,
"description": "Render session id for a completed render."
}
},
"additionalProperties": false
}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.
| Argument | Type | Description |
|---|---|---|
| topic* | string | Subject the AI should build the quiz around. Can be a short topic or a detailed multi-paragraph brief (up to 20,000 characters). |
| format | string | Output aspect ratio. Defaults to "tiktok". |
| quizType | string | Quiz mechanic to generate. |
| template | string | Visual template id. If omitted, the saved custom theme can suggest a matching template. |
| autoRender | boolean | If 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. |
| difficulty | string | Target difficulty level. |
Get the authenticated user's account info, plan, and usage limits.
No arguments.
{
"type": "object",
"properties": {},
"additionalProperties": false
}Fetch a flashcard deck (including all cards) by id.
| Argument | Type | Description |
|---|---|---|
| deckId* | string | Flashcard deck ID. |
{
"type": "object",
"required": [
"deckId"
],
"properties": {
"deckId": {
"type": "string",
"minLength": 1,
"description": "Flashcard deck ID."
}
},
"additionalProperties": false
}Fetch a single quiz (including settings and metadata) by id.
| Argument | Type | Description |
|---|---|---|
| quizId* | string | Quiz ID in YouTube-style 11-character base64url format. |
{
"type": "object",
"required": [
"quizId"
],
"properties": {
"quizId": {
"type": "string",
"minLength": 1,
"description": "Quiz ID in YouTube-style 11-character base64url format."
}
},
"additionalProperties": false
}Fetch the status and progress of a render session. When status is "completed", the response also contains a signed `videoUrl` (and `filename`) so the agent can share the MP4 directly without a separate quiz_video_download_render call. In-progress polls return status + progress.
| Argument | Type | Description |
|---|---|---|
| sessionId* | string | Render session id returned when the render was started. |
{
"type": "object",
"required": [
"sessionId"
],
"properties": {
"sessionId": {
"type": "string",
"minLength": 1,
"description": "Render session id returned when the render was started."
}
},
"additionalProperties": false
}Fetch a single custom template (including the full scenes/layers payload) by id.
| Argument | Type | Description |
|---|---|---|
| templateId* | string | Template id (tpl_...). |
{
"type": "object",
"required": [
"templateId"
],
"properties": {
"templateId": {
"type": "string",
"minLength": 1,
"description": "Template id (tpl_...)."
}
},
"additionalProperties": false
}List flashcard decks owned by the authenticated user with optional pagination.
| Argument | Type | Description |
|---|---|---|
| page | number | 1-indexed page number. |
| limit | number | Results per page (1–100, default 20). |
{
"type": "object",
"properties": {
"page": {
"type": "number",
"minimum": 1,
"description": "1-indexed page number."
},
"limit": {
"type": "number",
"maximum": 100,
"minimum": 1,
"description": "Results per page (1–100, default 20)."
}
},
"additionalProperties": false
}List available background music tracks.
No arguments.
{
"type": "object",
"properties": {},
"additionalProperties": false
}List video hooks configured for a quiz.
| Argument | Type | Description |
|---|---|---|
| quizId* | string | Quiz ID in YouTube-style 11-character base64url format. |
{
"type": "object",
"required": [
"quizId"
],
"properties": {
"quizId": {
"type": "string",
"minLength": 1,
"description": "Quiz ID in YouTube-style 11-character base64url format."
}
},
"additionalProperties": false
}List questions (and their answers) for a quiz.
| Argument | Type | Description |
|---|---|---|
| quizId* | string | Quiz ID in YouTube-style 11-character base64url format. |
{
"type": "object",
"required": [
"quizId"
],
"properties": {
"quizId": {
"type": "string",
"minLength": 1,
"description": "Quiz ID in YouTube-style 11-character base64url format."
}
},
"additionalProperties": false
}List quizzes owned by the authenticated user with optional pagination (page, limit).
| Argument | Type | Description |
|---|---|---|
| page | number | 1-indexed page number. |
| limit | number | Results per page (1–100, default 20). |
{
"type": "object",
"properties": {
"page": {
"type": "number",
"minimum": 1,
"description": "1-indexed page number."
},
"limit": {
"type": "number",
"maximum": 100,
"minimum": 1,
"description": "Results per page (1–100, default 20)."
}
},
"additionalProperties": false
}List the caller's saved custom templates (and optionally public ones). Templates are reusable scene-based designs that can be applied to many quizzes.
| Argument | Type | Description |
|---|---|---|
| page | number | |
| limit | number | |
| includePublic | boolean | Include public templates in addition to your own. Default true. |
{
"type": "object",
"properties": {
"page": {
"type": "number",
"minimum": 1
},
"limit": {
"type": "number",
"maximum": 100,
"minimum": 1
},
"includePublic": {
"type": "boolean",
"description": "Include public templates in addition to your own. Default true."
}
},
"additionalProperties": false
}Update a quiz. `updates` accepts any subset of quiz settings (title, description, format, template, timing, music, TTS, publish status, etc.).
| Argument | Type | Description |
|---|---|---|
| quizId* | string | Quiz ID in YouTube-style 11-character base64url format. |
| updates* | object | Partial quiz settings object; only included fields are updated. |
{
"type": "object",
"required": [
"quizId",
"updates"
],
"properties": {
"quizId": {
"type": "string",
"minLength": 1,
"description": "Quiz ID in YouTube-style 11-character base64url format."
},
"updates": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Updated quiz title."
},
"format": {
"enum": [
"tiktok",
"youtube"
],
"type": "string",
"description": "Output aspect ratio: \"tiktok\" (9:16 vertical) or \"youtube\" (16:9 horizontal)."
},
"quizType": {
"enum": [
"multiple_choice",
"reveal_answer",
"picture_guess"
],
"type": "string",
"description": "Quiz mechanic: multiple_choice, reveal_answer, or picture_guess."
},
"template": {
"type": "string",
"description": "Visual template id (e.g. \"neon\", \"minimal\"). See /api/v1 templates list."
},
"ttsSpeed": {
"type": "number",
"description": "Text-to-speech playback speed multiplier."
},
"ttsVoice": {
"type": "string",
"description": "Text-to-speech voice identifier."
},
"enableTTS": {
"type": "boolean",
"description": "Whether to read questions and answers aloud via text-to-speech."
},
"description": {
"type": "string",
"description": "Updated quiz description."
},
"isPublished": {
"type": "boolean",
"description": "Whether the quiz is publicly listed on quiz.video."
},
"musicVolume": {
"type": "number",
"maximum": 1,
"minimum": 0,
"description": "Background music volume from 0 (silent) to 1 (full). Default 0.15."
},
"revealStyle": {
"type": "string",
"description": "Animation style used when revealing the correct answer."
},
"answerFontSize": {
"type": "number",
"description": "Font size (px) for answer text."
},
"paceMultiplier": {
"type": "number",
"description": "Global timing multiplier applied to durations and animations."
},
"countdownSeconds": {
"type": "number",
"maximum": 15,
"minimum": 3,
"description": "Seconds of countdown shown before each question (3–15)."
},
"progressBarStyle": {
"enum": [
"circle",
"line"
],
"type": "string",
"description": "Countdown progress indicator style."
},
"questionFontSize": {
"type": "number",
"description": "Font size (px) for question text."
},
"themeDescription": {
"type": "string",
"description": "Natural-language custom visual theme prompt. Example: \"golden luxury game show\". The server saves the generated themeCustomization and applies it automatically."
},
"backgroundMusicId": {
"type": [
"number",
"null"
],
"description": "Background music track id from /api/v1/music. Omit to use the default YouTube-safe shared track; set null for silent."
},
"showQuestionCount": {
"type": "boolean",
"description": "Whether to show the \"Question N of M\" indicator."
},
"ttsAnswerTemplate": {
"type": "string",
"description": "Template string used to phrase the answer for TTS."
},
"themeCustomization": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Optional saved theme label, e.g. \"Golden Theme\"."
},
"description": {
"type": "string",
"description": "Optional natural-language source description for the custom theme."
},
"fontFamilyOverride": {
"enum": [
"Inter",
"Poppins",
"Roboto",
"Montserrat",
"Open Sans",
"Lato",
"Oswald",
"Raleway",
"Playfair Display",
"Source Sans Pro"
],
"type": "string",
"description": "Approved font family used for question and answer text."
},
"accentColorOverride": {
"type": "string",
"pattern": "^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$",
"description": "Primary accent hex color, e.g. \"#F6C945\"."
},
"secondaryColorOverride": {
"type": "string",
"pattern": "^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$",
"description": "Secondary accent hex color."
},
"backgroundColorOverride": {
"type": "string",
"pattern": "^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$",
"description": "Solid background hex color."
}
},
"description": "Explicit custom theme to save on the quiz. Use this when you already know the exact colors/font.",
"additionalProperties": false
},
"ttsQuestionTemplate": {
"type": "string",
"description": "Template string used to phrase the question for TTS."
}
},
"description": "Partial quiz settings object; only included fields are updated.",
"additionalProperties": true
}
},
"additionalProperties": false
}Update an existing hook on a quiz. Requires quizId and numeric hookId; `updates` is a partial HookInput.
| Argument | Type | Description |
|---|---|---|
| hookId* | number | Numeric id of the hook to update (from list_quiz_hooks). |
| quizId* | string | Quiz ID in YouTube-style 11-character base64url format. |
| updates* | object | Partial HookInput object; only included fields are updated. |
{
"type": "object",
"required": [
"quizId",
"hookId",
"updates"
],
"properties": {
"hookId": {
"type": "number",
"description": "Numeric id of the hook to update (from list_quiz_hooks)."
},
"quizId": {
"type": "string",
"minLength": 1,
"description": "Quiz ID in YouTube-style 11-character base64url format."
},
"updates": {
"type": "object",
"properties": {},
"description": "Partial HookInput object; only included fields are updated.",
"additionalProperties": true
}
},
"additionalProperties": false
}Update an existing template. Any subset of fields may be supplied; omitted fields stay unchanged.
| Argument | Type | Description |
|---|---|---|
| name | string | |
| isPublic | boolean | |
| template | object | |
| isDefault | boolean | |
| thumbnail | string | null | |
| templateId* | string | |
| description | string | null |
{
"type": "object",
"required": [
"templateId"
],
"properties": {
"name": {
"type": "string",
"maxLength": 120,
"minLength": 1
},
"isPublic": {
"type": "boolean"
},
"template": {
"type": "object"
},
"isDefault": {
"type": "boolean"
},
"thumbnail": {
"type": [
"string",
"null"
]
},
"templateId": {
"type": "string",
"minLength": 1
},
"description": {
"type": [
"string",
"null"
],
"maxLength": 280
}
},
"additionalProperties": false
}| countdownSeconds | number | Seconds of countdown shown before each question (3–15). |
| themeDescription | string | Natural-language custom visual theme prompt. Example: "golden luxury game show", "ocean glass", or "cyber neon". The server saves the generated themeCustomization and applies it automatically. |
| backgroundMusicId | number | null | Background music track id from /api/v1/music. Omit to use the default YouTube-safe shared track; set null for silent. |
| themeCustomization | object | Explicit custom theme to save and apply to the quiz. Invalid colors/fonts are ignored by the API sanitizer. |
{
"type": "object",
"required": [
"title"
],
"properties": {
"title": {
"type": "string",
"minLength": 1,
"description": "Human-readable quiz title."
},
"format": {
"enum": [
"tiktok",
"youtube"
],
"type": "string",
"description": "Output aspect ratio: \"tiktok\" (9:16 vertical) or \"youtube\" (16:9 horizontal)."
},
"quizType": {
"enum": [
"multiple_choice",
"reveal_answer",
"picture_guess"
],
"type": "string",
"description": "Quiz mechanic: multiple_choice, reveal_answer, or picture_guess."
},
"template": {
"type": "string",
"description": "Visual template id (e.g. \"neon\", \"minimal\")."
},
"questions": {
"type": "array",
"items": {
"type": "object",
"required": [
"questionText"
],
"properties": {
"order": {
"type": "number",
"description": "1-indexed display order of the question within the quiz."
},
"images": {
"type": "array",
"items": {
"type": "object",
"required": [
"url"
],
"properties": {
"alt": {
"type": "string",
"description": "Alt text describing the image for accessibility."
},
"url": {
"type": "string",
"description": "Absolute URL of the image asset."
},
"width": {
"type": "number",
"description": "Image width in pixels."
},
"height": {
"type": "number",
"description": "Image height in pixels."
},
"source": {
"type": "string",
"description": "Image source label, e.g. \"upload\", \"unsplash\", \"generated\"."
},
"sourceUrl": {
"type": "string",
"description": "Original attribution URL for the image, if any."
}
},
"additionalProperties": true
},
"description": "Additional images attached to the question (in addition to imagePath)."
},
"answers": {
"type": "array",
"items": {
"type": "object",
"required": [
"answerText",
"isCorrect"
],
"properties": {
"order": {
"type": "number",
"description": "1-indexed display order of the answer within the question."
},
"ttsText": {
"type": "string",
"description": "Optional exact narration line for the answer reveal."
},
"isCorrect": {
"type": "boolean",
"description": "Whether this answer is the correct one for the question."
},
"answerText": {
"type": "string",
"minLength": 1,
"description": "Answer text shown to viewers."
},
"additionalInfo": {
"type": "string",
"description": "Optional explanation or trivia shown after the answer is revealed."
}
},
"additionalProperties": false
},
"description": "Answer options for this question; exactly one should be marked isCorrect=true."
},
"ttsText": {
"type": "string",
"description": "Optional exact narration line for this question."
},
"duration": {
"type": "number",
"minimum": 1,
"description": "Seconds viewers have to answer this question (must be >= 1)."
},
"imagePath": {
"type": "string",
"description": "Optional primary image URL shown with the question (used by picture_guess quizzes)."
},
"questionText": {
"type": "string",
"minLength": 1,
"description": "The question prompt shown to viewers."
}
},
"additionalProperties": true
},
"description": "Optional initial questions with their answers and images."
},
"difficulty": {
"enum": [
"easy",
"medium",
"hard",
"rising"
],
"type": "string",
"description": "Target difficulty level for the generated/created quiz."
},
"description": {
"type": "string",
"description": "Optional longer description shown on the quiz page."
},
"musicVolume": {
"type": "number",
"maximum": 1,
"minimum": 0,
"description": "Background music volume from 0 (silent) to 1 (full). Default 0.15."
},
"countdownSeconds": {
"type": "number",
"maximum": 15,
"minimum": 3,
"description": "Seconds of countdown shown before each question (3–15)."
},
"themeDescription": {
"type": "string",
"description": "Natural-language custom visual theme prompt. Example: \"golden luxury game show\", \"ocean glass\", or \"cyber neon\". The server saves the generated themeCustomization and applies it automatically."
},
"backgroundMusicId": {
"type": [
"number",
"null"
],
"description": "Background music track id from /api/v1/music. Omit to use the default YouTube-safe shared track; set null for silent."
},
"themeCustomization": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Optional saved theme label, e.g. \"Golden Theme\"."
},
"description": {
"type": "string",
"description": "Optional natural-language source description for the custom theme."
},
"fontFamilyOverride": {
"enum": [
"Inter",
"Poppins",
"Roboto",
"Montserrat",
"Open Sans",
"Lato",
"Oswald",
"Raleway",
"Playfair Display",
"Source Sans Pro"
],
"type": "string",
"description": "Approved font family used for question and answer text."
},
"accentColorOverride": {
"type": "string",
"pattern": "^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$",
"description": "Primary accent hex color, e.g. \"#F6C945\"."
},
"secondaryColorOverride": {
"type": "string",
"pattern": "^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$",
"description": "Secondary accent hex color."
},
"backgroundColorOverride": {
"type": "string",
"pattern": "^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$",
"description": "Solid background hex color."
}
},
"description": "Explicit custom theme to save and apply to the quiz. Invalid colors/fonts are ignored by the API sanitizer.",
"additionalProperties": false
}
},
"additionalProperties": true
}| musicVolume |
| number |
| Background music volume from 0 (silent) to 1 (full). Default 0.15. |
| extraDirection | string | Additional instructions to steer the AI (tone, focus areas, exclusions). Up to 20,000 characters. |
| countdownSeconds | number | Seconds of countdown shown before each question (3-15). |
| progressBarStyle | string | Countdown progress indicator style. |
| themeDescription | string | Natural-language custom visual theme prompt. Example: "golden luxury game show", "ocean glass", or "cyber neon". |
| answerOptionCount | number | For multiple-choice quizzes, generate 3 or 4 answer options per question. Defaults to 4. |
| backgroundMusicId | number | null | Background music track id from /api/v1/music. Omit to use the default YouTube-safe shared track; set null for silent. |
| numberOfQuestions | number | How many questions to generate (1–200). |
| themeCustomization | object | Explicit custom theme to save and apply to the generated quiz. Use themeDescription for prompt-style themes. |
{
"type": "object",
"required": [
"topic"
],
"properties": {
"topic": {
"type": "string",
"maxLength": 20000,
"minLength": 1,
"description": "Subject the AI should build the quiz around. Can be a short topic or a detailed multi-paragraph brief (up to 20,000 characters)."
},
"format": {
"enum": [
"tiktok",
"youtube"
],
"type": "string",
"description": "Output aspect ratio. Defaults to \"tiktok\"."
},
"quizType": {
"enum": [
"multiple_choice",
"reveal_answer",
"picture_guess"
],
"type": "string",
"description": "Quiz mechanic to generate."
},
"template": {
"type": "string",
"description": "Visual template id. If omitted, the saved custom theme can suggest a matching template."
},
"autoRender": {
"type": "boolean",
"description": "If 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."
},
"difficulty": {
"enum": [
"easy",
"medium",
"hard",
"rising"
],
"type": "string",
"description": "Target difficulty level."
},
"musicVolume": {
"type": "number",
"maximum": 1,
"minimum": 0,
"description": "Background music volume from 0 (silent) to 1 (full). Default 0.15."
},
"extraDirection": {
"type": "string",
"maxLength": 20000,
"description": "Additional instructions to steer the AI (tone, focus areas, exclusions). Up to 20,000 characters."
},
"countdownSeconds": {
"type": "number",
"maximum": 15,
"minimum": 3,
"description": "Seconds of countdown shown before each question (3-15)."
},
"progressBarStyle": {
"enum": [
"circle",
"line"
],
"type": "string",
"description": "Countdown progress indicator style."
},
"themeDescription": {
"type": "string",
"maxLength": 20000,
"description": "Natural-language custom visual theme prompt. Example: \"golden luxury game show\", \"ocean glass\", or \"cyber neon\"."
},
"answerOptionCount": {
"enum": [
3,
4
],
"type": "number",
"description": "For multiple-choice quizzes, generate 3 or 4 answer options per question. Defaults to 4."
},
"backgroundMusicId": {
"type": [
"number",
"null"
],
"description": "Background music track id from /api/v1/music. Omit to use the default YouTube-safe shared track; set null for silent."
},
"numberOfQuestions": {
"type": "number",
"maximum": 200,
"minimum": 1,
"description": "How many questions to generate (1–200)."
},
"themeCustomization": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Optional saved theme label, e.g. \"Golden Theme\"."
},
"description": {
"type": "string",
"description": "Optional natural-language source description for the custom theme."
},
"fontFamilyOverride": {
"enum": [
"Inter",
"Poppins",
"Roboto",
"Montserrat",
"Open Sans",
"Lato",
"Oswald",
"Raleway",
"Playfair Display",
"Source Sans Pro"
],
"type": "string",
"description": "Approved font family used for question and answer text."
},
"accentColorOverride": {
"type": "string",
"pattern": "^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$",
"description": "Primary accent hex color, e.g. \"#F6C945\"."
},
"secondaryColorOverride": {
"type": "string",
"pattern": "^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$",
"description": "Secondary accent hex color."
},
"backgroundColorOverride": {
"type": "string",
"pattern": "^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$",
"description": "Solid background hex color."
}
},
"description": "Explicit custom theme to save and apply to the generated quiz. Use themeDescription for prompt-style themes.",
"additionalProperties": false
}
},
"additionalProperties": false
}