REST API v1

Quiz.Video API

Create, manage, and AI-generate quizzes and flashcards programmatically. Build integrations, automate workflows, and extend Quiz.Video into your apps.

Authentication

All API requests require an API key passed via the x-api-key header.

Generate your API key from your account settings under the API Keys tab.

Example header

x-api-key: your_api_key_here

Base URL

All endpoints are relative to the following base URL:

https://www.quiz.video/api/v1

Quick Start

Get up and running in seconds. Here are examples to list your quizzes:

cURL

curl -X GET https://www.quiz.video/api/v1/quizzes \
  -H "x-api-key: your_api_key_here"

JavaScript (fetch)

const response = await fetch("https://www.quiz.video/api/v1/quizzes", {
  headers: {
    "x-api-key": "your_api_key_here",
  },
});

const { data } = await response.json();
console.log(data.quizzes);

Quizzes

GET/api/v1/quizzes

List all your quizzes. Results are paginated.

Query Parameters

page    integer   Page number (default: 1)
limit   integer   Results per page (default: 20, max: 100)

Response

{
  "data": {
    "quizzes": [
      {
        "id": "dQw4w9WgXcQ",
        "title": "World Capitals Quiz",
        "description": "Test your geography knowledge",
        "format": "multiple_choice",
        "quizType": "standard",
        "questionCount": 10,
        "createdAt": "2025-01-15T08:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 45,
      "totalPages": 3
    }
  }
}

Create Complete Quizzes in One Call

The POST /api/v1/quizzes endpoint creates quizzes WITH questions and answers. Include the "questions" array with nested "answers" to create everything at once. This is NOT just a quiz shell!

POST/api/v1/quizzes

Create a new quiz WITH questions and answers in one call. Include the questions array with nested answers to create a complete quiz immediately, or omit it to create an empty quiz shell.

Request Body

{
  "title": "World Capitals Quiz",
  "description": "Test your geography knowledge",
  "format": "tiktok",
  "quizType": "multiple_choice",
  "template": "neon",
  "difficulty": "medium",
  "countdownSeconds": 5,
  "backgroundMusicId": "cm5abc123def",
  "musicVolume": 0.15,
  "questions": [
    {
      "questionText": "What is the capital of France?",
      "order": 1,
      "duration": 4,
      "answers": [
        { "answerText": "London", "isCorrect": false, "order": 1 },
        { "answerText": "Berlin", "isCorrect": false, "order": 2 },
        { "answerText": "Paris", "isCorrect": true, "order": 3 },
        { "answerText": "Madrid", "isCorrect": false, "order": 4 }
      ]
    }
  ]
}

Response

{
  "data": {
    "id": "dQw4w9WgXcQ",
    "title": "World Capitals Quiz",
    "description": "Test your geography knowledge",
    "format": "tiktok",
    "quizType": "multiple_choice",
    "createdAt": "2025-01-15T08:30:00Z"
  }
}

GET/api/v1/quizzes/:id

Get full details for a specific quiz, including all questions and answers.

Response

{
  "data": {
    "id": "dQw4w9WgXcQ",
    "title": "World Capitals Quiz",
    "description": "Test your geography knowledge",
    "format": "multiple_choice",
    "quizType": "standard",
    "questions": [
      {
        "id": "q1",
        "text": "What is the capital of France?",
        "options": ["London", "Berlin", "Paris", "Madrid"],
        "correctAnswer": 2
      }
    ],
    "createdAt": "2025-01-15T08:30:00Z"
  }
}

PATCH/api/v1/quizzes/:id

Update a quiz's title, description, or other properties.

Request Body

{
  "title": "Updated Quiz Title",
  "description": "Updated description",
  "backgroundMusicId": "cm5abc123def",
  "musicVolume": 0.2
}

Response

{
  "data": {
    "id": "dQw4w9WgXcQ",
    "title": "Updated Quiz Title",
    "description": "Updated description",
    "updatedAt": "2025-01-16T10:00:00Z"
  }
}

DELETE/api/v1/quizzes/:id

Permanently delete a quiz and all its questions.

Response

{
  "data": {
    "deleted": true
  }
}

Questions

GET/api/v1/quizzes/:id/questions

Get all questions and answers for a specific quiz.

Response

{
  "data": {
    "questions": [
      {
        "id": "q1",
        "questionText": "What is the capital of France?",
        "order": 1,
        "duration": 4,
        "answers": [
          { "id": "a1", "answerText": "London", "isCorrect": false, "order": 1 },
          { "id": "a2", "answerText": "Berlin", "isCorrect": false, "order": 2 },
          { "id": "a3", "answerText": "Paris", "isCorrect": true, "order": 3 },
          { "id": "a4", "answerText": "Madrid", "isCorrect": false, "order": 4 }
        ]
      }
    ]
  }
}

POST/api/v1/quizzes/:id/questions

Add questions to an existing quiz. Use this endpoint if you created an empty quiz and want to add questions later.

Request Body

{
  "questions": [
    {
      "questionText": "What is the capital of Germany?",
      "order": 2,
      "duration": 4,
      "answers": [
        { "answerText": "Munich", "isCorrect": false, "order": 1 },
        { "answerText": "Berlin", "isCorrect": true, "order": 2 },
        { "answerText": "Hamburg", "isCorrect": false, "order": 3 },
        { "answerText": "Frankfurt", "isCorrect": false, "order": 4 }
      ]
    }
  ]
}

Response

{
  "data": {
    "questionsAdded": 1
  }
}

Images & Picture Quizzes

Picture Quiz Support

Set quizType to "picture_guess" to create picture-based quizzes. Upload images first, then attach them to questions via imagePath and images arrays. All question endpoints now include an images array in responses.

Quiz Types: multiple_choice, reveal_answer, picture_guess

Allowed Formats: JPEG, PNG, WebP, GIF (max 10MB)

POST/api/v1/images/upload

Upload an image file. Returns a URL you can use when creating questions with images. Accepts multipart/form-data with a single 'file' field.

Request Body

Content-Type: multipart/form-data

file: <image file> (JPEG, PNG, WebP, or GIF, max 10MB)

Response

{
  "data": {
    "url": "https://storage.example.com/images/2025/01/15/user123/1705312200-abc123.jpg",
    "thumbnailUrl": "https://storage.example.com/images/2025/01/15/user123/1705312200-abc123.jpg",
    "width": 1920,
    "height": 1080,
    "key": "images/2025/01/15/user123/1705312200-abc123.jpg"
  }
}

POST/api/v1/questions/:questionId/images

Attach an image to an existing question. The question must belong to a quiz owned by the authenticated user.

Request Body

{
  "url": "https://storage.example.com/images/eiffel-tower.jpg",
  "alt": "A famous landmark",
  "source": "upload",
  "sourceUrl": null,
  "width": 1920,
  "height": 1080
}

Response

{
  "data": {
    "id": 1,
    "questionId": 42,
    "url": "https://storage.example.com/images/eiffel-tower.jpg",
    "alt": "A famous landmark",
    "source": "upload",
    "width": 1920,
    "height": 1080,
    "isActive": true,
    "createdAt": "2025-01-15T09:00:00Z"
  }
}

Creating a Picture Quiz (Full Example)

Use POST /api/v1/quizzes with quizType "picture_guess". Each question can include an imagePath and images array:

cURL

curl -X POST https://www.quiz.video/api/v1/quizzes \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Famous Landmarks Quiz",
    "quizType": "picture_guess",
    "questions": [
      {
        "questionText": "Which famous landmark is this?",
        "imagePath": "https://storage.example.com/images/eiffel-tower.jpg",
        "order": 1,
        "duration": 5,
        "images": [
          {
            "url": "https://storage.example.com/images/eiffel-tower.jpg",
            "alt": "A tall iron lattice tower",
            "width": 1920,
            "height": 1080
          }
        ],
        "answers": [
          { "answerText": "Eiffel Tower", "isCorrect": true, "order": 1 },
          { "answerText": "Big Ben", "isCorrect": false, "order": 2 },
          { "answerText": "Colosseum", "isCorrect": false, "order": 3 },
          { "answerText": "Taj Mahal", "isCorrect": false, "order": 4 }
        ]
      }
    ]
  }'

Background Music

Music Volume & Default Track

The musicVolume field defaults to 0.15 (15%) if not specified. When creating a quiz without a backgroundMusicId, a default track is automatically assigned.

GET/api/v1/music

List available background music tracks. Returns shared library tracks and your own uploads. Each track includes a temporary signed URL for playback.

Query Parameters

page    integer   Page number (default: 1)
limit   integer   Results per page (default: 20, max: 100)

Response

{
  "data": {
    "tracks": [
      {
        "id": "cm5abc123def",
        "name": "Upbeat Quiz",
        "duration": 120,
        "category": "upbeat",
        "isDefault": true,
        "url": "https://storage.example.com/music/upbeat-quiz.mp3?token=..."
      },
      {
        "id": "cm5xyz789ghi",
        "name": "Chill Background",
        "duration": 180,
        "category": "chill",
        "isDefault": false,
        "url": "https://storage.example.com/music/chill-bg.mp3?token=..."
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 8,
      "totalPages": 1
    }
  }
}

Hooks

Engagement Slides in Quiz Videos

Hooks are content slides that appear in your rendered quiz video at specific positions. Use them to drive engagement (likes, shares, follows), keep viewers motivated, or add custom content between questions. TTS is enabled by default for all hooks.

Hook Types: engagement, reminder, conclusion, custom

Position Types: start, after_question, end

Animation Styles: fade (default), bounce, slide, zoom

GET/api/v1/quizzes/:id/hooks

List all hooks for a quiz. Returns hook configuration including position, animation style, display duration, and TTS settings.

Response

{
  "data": [
    {
      "id": 1,
      "quizId": "dQw4w9WgXcQ",
      "hookType": "engagement",
      "positionType": "after_question",
      "positionValue": 3,
      "title": "Challenge your friends!",
      "content": "Share this quiz and see who gets the highest score!",
      "emoji": "🎯",
      "animationStyle": "bounce",
      "displayDuration": 5,
      "ttsEnabled": true,
      "ttsText": null,
      "themeColor": null,
      "backgroundColor": null,
      "fontSize": 64,
      "enabled": true,
      "createdAt": "2025-01-15T08:30:00Z"
    }
  ]
}

POST/api/v1/quizzes/:id/hooks

Create a new hook. Required fields: hookType, positionType, title, content. Optional: positionValue (for after_question), emoji, animationStyle (default: fade), displayDuration (default: 5), ttsEnabled (default: true), ttsText, themeColor, backgroundColor, fontSize (default: 64).

Request Body

{
  "hookType": "engagement",
  "positionType": "after_question",
  "positionValue": 3,
  "title": "Challenge your friends!",
  "content": "Share this quiz and see who gets the highest score!",
  "emoji": "🎯",
  "animationStyle": "bounce",
  "displayDuration": 5,
  "ttsEnabled": true
}

Response

{
  "data": {
    "id": 1,
    "quizId": "dQw4w9WgXcQ",
    "hookType": "engagement",
    "positionType": "after_question",
    "positionValue": 3,
    "title": "Challenge your friends!",
    "content": "Share this quiz and see who gets the highest score!",
    "emoji": "🎯",
    "animationStyle": "bounce",
    "displayDuration": 5,
    "ttsEnabled": true,
    "enabled": true,
    "createdAt": "2025-01-15T08:30:00Z"
  }
}

PATCH/api/v1/quizzes/:id/hooks

Update an existing hook. Include hookId in the request body along with the fields you want to update.

Request Body

{
  "hookId": 1,
  "title": "Updated title",
  "animationStyle": "zoom",
  "displayDuration": 7
}

Response

{
  "data": {
    "id": 1,
    "title": "Updated title",
    "animationStyle": "zoom",
    "displayDuration": 7,
    "updatedAt": "2025-01-16T10:00:00Z"
  }
}

DELETE/api/v1/quizzes/:id/hooks

Delete a hook by ID. Pass the hookId as a query parameter.

Query Parameters

hookId   integer   The ID of the hook to delete

Response

{
  "data": {
    "deleted": true
  }
}

Renders

POST/api/v1/renders

Start a video render for a quiz. Returns immediately with a session ID. Poll the status endpoint to track progress.

Request Body

{
  "quizId": "dQw4w9WgXcQ"
}

Response

{
  "data": {
    "sessionId": "abc-123-def",
    "quizId": "dQw4w9WgXcQ",
    "status": "queued"
  }
}

GET/api/v1/renders

List all your renders with their current status. Results are paginated and can be filtered by quiz ID.

Query Parameters

page     integer   Page number (default: 1)
limit    integer   Results per page (default: 20, max: 100)
quizId   string    Optional filter by quiz ID

Response

{
  "data": {
    "renders": [
      {
        "sessionId": "abc-123-def",
        "quizId": "dQw4w9WgXcQ",
        "quizTitle": "World Capitals Quiz",
        "status": "completed",
        "progress": 100,
        "duration": 45,
        "createdAt": "2025-01-15T08:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 15,
      "totalPages": 1
    }
  }
}

GET/api/v1/renders/:sessionId

Get detailed status for a specific render. Poll this endpoint to track rendering progress. Status can be: queued, rendering, completed, or failed.

Response

{
  "data": {
    "sessionId": "abc-123-def",
    "quizId": "dQw4w9WgXcQ",
    "quizTitle": "World Capitals Quiz",
    "status": "completed",
    "progress": 100,
    "duration": 45,
    "fileSize": 15728640,
    "createdAt": "2025-01-15T08:30:00Z",
    "completedAt": "2025-01-15T08:31:00Z"
  }
}

POST/api/v1/renders/:sessionId/download

Get a download URL for a completed render. This endpoint requires a paid plan. The URL is temporary and expires after 24 hours.

Response

{
  "data": {
    "downloadUrl": "https://...",
    "filename": "world-capitals-quiz.mp4"
  }
}

AI Quiz Generation

POST/api/v1/quizzes/generate

Generate a quiz using AI. Provide a topic and configuration, and receive a fully formed quiz with questions and answers. Parameters: topic (required), numberOfQuestions (required), difficulty (required: easy/medium/hard/rising), quizType (required: multiple_choice/reveal_answer/picture_guess), extraDirection (optional: additional instructions for AI).

Request Body

{
  "topic": "The Solar System",
  "numberOfQuestions": 10,
  "difficulty": "medium",
  "quizType": "multiple_choice",
  "extraDirection": "Focus on the outer planets"
}

Response

{
  "data": {
    "id": "xK9mP2vLqRs",
    "title": "The Solar System Quiz",
    "description": "AI-generated quiz about The Solar System",
    "quizType": "multiple_choice",
    "questions": [
      {
        "id": "q1",
        "questionText": "Which planet is closest to the Sun?",
        "answers": [
          { "id": "a1", "answerText": "Venus", "isCorrect": false },
          { "id": "a2", "answerText": "Mercury", "isCorrect": true },
          { "id": "a3", "answerText": "Earth", "isCorrect": false },
          { "id": "a4", "answerText": "Mars", "isCorrect": false }
        ]
      }
    ],
    "createdAt": "2025-01-15T09:00:00Z"
  }
}

Flashcards

GET/api/v1/flashcards

List all your flashcard decks. Results are paginated.

Query Parameters

page    integer   Page number (default: 1)
limit   integer   Results per page (default: 20, max: 100)

Response

{
  "data": {
    "decks": [
      {
        "id": "fL3nR8wKpYt",
        "title": "Spanish Vocabulary",
        "description": "Common Spanish words and phrases",
        "cardCount": 50,
        "createdAt": "2025-01-14T12:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 12,
      "totalPages": 1
    }
  }
}

POST/api/v1/flashcards

Create a new flashcard deck.

Request Body

{
  "title": "Spanish Vocabulary",
  "description": "Common Spanish words and phrases"
}

Response

{
  "data": {
    "id": "fL3nR8wKpYt",
    "title": "Spanish Vocabulary",
    "description": "Common Spanish words and phrases",
    "createdAt": "2025-01-14T12:00:00Z"
  }
}

GET/api/v1/flashcards/:id

Get a flashcard deck with all its cards.

Response

{
  "data": {
    "id": "fL3nR8wKpYt",
    "title": "Spanish Vocabulary",
    "description": "Common Spanish words and phrases",
    "cards": [
      {
        "id": "c1",
        "front": "Hello",
        "back": "Hola"
      },
      {
        "id": "c2",
        "front": "Goodbye",
        "back": "Adios"
      }
    ],
    "createdAt": "2025-01-14T12:00:00Z"
  }
}

DELETE/api/v1/flashcards/:id

Permanently delete a flashcard deck and all its cards.

Response

{
  "data": {
    "deleted": true
  }
}

Account

GET/api/v1/account

Get your account information and API usage statistics.

Response

{
  "data": {
    "email": "user@example.com",
    "plan": "pro",
    "usage": {
      "requestsToday": 142,
      "requestsLimit": 1000,
      "quizzesCreated": 28,
      "flashcardDecksCreated": 15
    }
  }
}

Rate Limiting

The API enforces a default rate limit of 1,000 requests per day per API key. Rate limit information is included in response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 858
X-RateLimit-Reset: 2025-01-16T00:00:00Z

If you exceed the rate limit, you will receive a 429 response. Wait until the reset time before retrying.

Error Codes

Status	Code	Description
401	UNAUTHORIZED	Missing or invalid API key
403	FORBIDDEN	API key does not have permission for this action
404	NOT_FOUND	The requested resource was not found
429	RATE_LIMITED	Too many requests; wait for rate limit reset
500	INTERNAL_ERROR	An unexpected server error occurred

Response Format

All API responses return JSON. Successful responses wrap the result in a data field. Errors return an error message and code.

Success

{
  "data": {
    "id": "dQw4w9WgXcQ",
    "title": "My Quiz"
  }
}

Error

{
  "error": "Quiz not found",
  "code": "NOT_FOUND"
}

Ready to get started?

Create your API key and start building.

Get your API key View pricing

REST API v1

Quiz.Video API

Create, manage, and AI-generate quizzes and flashcards programmatically. Build integrations, automate workflows, and extend Quiz.Video into your apps.

Authentication

All API requests require an API key passed via the x-api-key header.

Generate your API key from your account settings under the API Keys tab.

Example header

x-api-key: your_api_key_here

Base URL

All endpoints are relative to the following base URL:

https://www.quiz.video/api/v1

Quick Start

Get up and running in seconds. Here are examples to list your quizzes:

cURL

curl -X GET https://www.quiz.video/api/v1/quizzes \
  -H "x-api-key: your_api_key_here"

JavaScript (fetch)

const response = await fetch("https://www.quiz.video/api/v1/quizzes", {
  headers: {
    "x-api-key": "your_api_key_here",
  },
});

const { data } = await response.json();
console.log(data.quizzes);

Quizzes

GET/api/v1/quizzes

List all your quizzes. Results are paginated.

Query Parameters

page    integer   Page number (default: 1)
limit   integer   Results per page (default: 20, max: 100)

Response

{
  "data": {
    "quizzes": [
      {
        "id": "dQw4w9WgXcQ",
        "title": "World Capitals Quiz",
        "description": "Test your geography knowledge",
        "format": "multiple_choice",
        "quizType": "standard",
        "questionCount": 10,
        "createdAt": "2025-01-15T08:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 45,
      "totalPages": 3
    }
  }
}

Create Complete Quizzes in One Call

The POST /api/v1/quizzes endpoint creates quizzes WITH questions and answers. Include the "questions" array with nested "answers" to create everything at once. This is NOT just a quiz shell!

POST/api/v1/quizzes

Create a new quiz WITH questions and answers in one call. Include the questions array with nested answers to create a complete quiz immediately, or omit it to create an empty quiz shell.

Request Body

{
  "title": "World Capitals Quiz",
  "description": "Test your geography knowledge",
  "format": "tiktok",
  "quizType": "multiple_choice",
  "template": "neon",
  "difficulty": "medium",
  "countdownSeconds": 5,
  "backgroundMusicId": "cm5abc123def",
  "musicVolume": 0.15,
  "questions": [
    {
      "questionText": "What is the capital of France?",
      "order": 1,
      "duration": 4,
      "answers": [
        { "answerText": "London", "isCorrect": false, "order": 1 },
        { "answerText": "Berlin", "isCorrect": false, "order": 2 },
        { "answerText": "Paris", "isCorrect": true, "order": 3 },
        { "answerText": "Madrid", "isCorrect": false, "order": 4 }
      ]
    }
  ]
}

Response

{
  "data": {
    "id": "dQw4w9WgXcQ",
    "title": "World Capitals Quiz",
    "description": "Test your geography knowledge",
    "format": "tiktok",
    "quizType": "multiple_choice",
    "createdAt": "2025-01-15T08:30:00Z"
  }
}

GET/api/v1/quizzes/:id

Get full details for a specific quiz, including all questions and answers.

Response

{
  "data": {
    "id": "dQw4w9WgXcQ",
    "title": "World Capitals Quiz",
    "description": "Test your geography knowledge",
    "format": "multiple_choice",
    "quizType": "standard",
    "questions": [
      {
        "id": "q1",
        "text": "What is the capital of France?",
        "options": ["London", "Berlin", "Paris", "Madrid"],
        "correctAnswer": 2
      }
    ],
    "createdAt": "2025-01-15T08:30:00Z"
  }
}

PATCH/api/v1/quizzes/:id

Update a quiz's title, description, or other properties.

Request Body

{
  "title": "Updated Quiz Title",
  "description": "Updated description",
  "backgroundMusicId": "cm5abc123def",
  "musicVolume": 0.2
}

Response

{
  "data": {
    "id": "dQw4w9WgXcQ",
    "title": "Updated Quiz Title",
    "description": "Updated description",
    "updatedAt": "2025-01-16T10:00:00Z"
  }
}

DELETE/api/v1/quizzes/:id

Permanently delete a quiz and all its questions.

Response

{
  "data": {
    "deleted": true
  }
}

Questions

GET/api/v1/quizzes/:id/questions

Get all questions and answers for a specific quiz.

Response

{
  "data": {
    "questions": [
      {
        "id": "q1",
        "questionText": "What is the capital of France?",
        "order": 1,
        "duration": 4,
        "answers": [
          { "id": "a1", "answerText": "London", "isCorrect": false, "order": 1 },
          { "id": "a2", "answerText": "Berlin", "isCorrect": false, "order": 2 },
          { "id": "a3", "answerText": "Paris", "isCorrect": true, "order": 3 },
          { "id": "a4", "answerText": "Madrid", "isCorrect": false, "order": 4 }
        ]
      }
    ]
  }
}

POST/api/v1/quizzes/:id/questions

Add questions to an existing quiz. Use this endpoint if you created an empty quiz and want to add questions later.

Request Body

{
  "questions": [
    {
      "questionText": "What is the capital of Germany?",
      "order": 2,
      "duration": 4,
      "answers": [
        { "answerText": "Munich", "isCorrect": false, "order": 1 },
        { "answerText": "Berlin", "isCorrect": true, "order": 2 },
        { "answerText": "Hamburg", "isCorrect": false, "order": 3 },
        { "answerText": "Frankfurt", "isCorrect": false, "order": 4 }
      ]
    }
  ]
}

Response

{
  "data": {
    "questionsAdded": 1
  }
}

Images & Picture Quizzes

Picture Quiz Support

Quiz Types: multiple_choice, reveal_answer, picture_guess

Allowed Formats: JPEG, PNG, WebP, GIF (max 10MB)

POST/api/v1/images/upload

Upload an image file. Returns a URL you can use when creating questions with images. Accepts multipart/form-data with a single 'file' field.

Request Body

Content-Type: multipart/form-data

file: <image file> (JPEG, PNG, WebP, or GIF, max 10MB)

Response

{
  "data": {
    "url": "https://storage.example.com/images/2025/01/15/user123/1705312200-abc123.jpg",
    "thumbnailUrl": "https://storage.example.com/images/2025/01/15/user123/1705312200-abc123.jpg",
    "width": 1920,
    "height": 1080,
    "key": "images/2025/01/15/user123/1705312200-abc123.jpg"
  }
}

POST/api/v1/questions/:questionId/images

Attach an image to an existing question. The question must belong to a quiz owned by the authenticated user.

Request Body

{
  "url": "https://storage.example.com/images/eiffel-tower.jpg",
  "alt": "A famous landmark",
  "source": "upload",
  "sourceUrl": null,
  "width": 1920,
  "height": 1080
}

Response

{
  "data": {
    "id": 1,
    "questionId": 42,
    "url": "https://storage.example.com/images/eiffel-tower.jpg",
    "alt": "A famous landmark",
    "source": "upload",
    "width": 1920,
    "height": 1080,
    "isActive": true,
    "createdAt": "2025-01-15T09:00:00Z"
  }
}

Creating a Picture Quiz (Full Example)

Use POST /api/v1/quizzes with quizType "picture_guess". Each question can include an imagePath and images array:

cURL

curl -X POST https://www.quiz.video/api/v1/quizzes \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Famous Landmarks Quiz",
    "quizType": "picture_guess",
    "questions": [
      {
        "questionText": "Which famous landmark is this?",
        "imagePath": "https://storage.example.com/images/eiffel-tower.jpg",
        "order": 1,
        "duration": 5,
        "images": [
          {
            "url": "https://storage.example.com/images/eiffel-tower.jpg",
            "alt": "A tall iron lattice tower",
            "width": 1920,
            "height": 1080
          }
        ],
        "answers": [
          { "answerText": "Eiffel Tower", "isCorrect": true, "order": 1 },
          { "answerText": "Big Ben", "isCorrect": false, "order": 2 },
          { "answerText": "Colosseum", "isCorrect": false, "order": 3 },
          { "answerText": "Taj Mahal", "isCorrect": false, "order": 4 }
        ]
      }
    ]
  }'

Background Music

Music Volume & Default Track

The musicVolume field defaults to 0.15 (15%) if not specified. When creating a quiz without a backgroundMusicId, a default track is automatically assigned.

GET/api/v1/music

List available background music tracks. Returns shared library tracks and your own uploads. Each track includes a temporary signed URL for playback.

Query Parameters

page    integer   Page number (default: 1)
limit   integer   Results per page (default: 20, max: 100)

Response

{
  "data": {
    "tracks": [
      {
        "id": "cm5abc123def",
        "name": "Upbeat Quiz",
        "duration": 120,
        "category": "upbeat",
        "isDefault": true,
        "url": "https://storage.example.com/music/upbeat-quiz.mp3?token=..."
      },
      {
        "id": "cm5xyz789ghi",
        "name": "Chill Background",
        "duration": 180,
        "category": "chill",
        "isDefault": false,
        "url": "https://storage.example.com/music/chill-bg.mp3?token=..."
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 8,
      "totalPages": 1
    }
  }
}

Hooks

Engagement Slides in Quiz Videos

Hook Types: engagement, reminder, conclusion, custom

Position Types: start, after_question, end

Animation Styles: fade (default), bounce, slide, zoom

GET/api/v1/quizzes/:id/hooks

List all hooks for a quiz. Returns hook configuration including position, animation style, display duration, and TTS settings.

Response

{
  "data": [
    {
      "id": 1,
      "quizId": "dQw4w9WgXcQ",
      "hookType": "engagement",
      "positionType": "after_question",
      "positionValue": 3,
      "title": "Challenge your friends!",
      "content": "Share this quiz and see who gets the highest score!",
      "emoji": "🎯",
      "animationStyle": "bounce",
      "displayDuration": 5,
      "ttsEnabled": true,
      "ttsText": null,
      "themeColor": null,
      "backgroundColor": null,
      "fontSize": 64,
      "enabled": true,
      "createdAt": "2025-01-15T08:30:00Z"
    }
  ]
}

POST/api/v1/quizzes/:id/hooks

Request Body

{
  "hookType": "engagement",
  "positionType": "after_question",
  "positionValue": 3,
  "title": "Challenge your friends!",
  "content": "Share this quiz and see who gets the highest score!",
  "emoji": "🎯",
  "animationStyle": "bounce",
  "displayDuration": 5,
  "ttsEnabled": true
}

Response

{
  "data": {
    "id": 1,
    "quizId": "dQw4w9WgXcQ",
    "hookType": "engagement",
    "positionType": "after_question",
    "positionValue": 3,
    "title": "Challenge your friends!",
    "content": "Share this quiz and see who gets the highest score!",
    "emoji": "🎯",
    "animationStyle": "bounce",
    "displayDuration": 5,
    "ttsEnabled": true,
    "enabled": true,
    "createdAt": "2025-01-15T08:30:00Z"
  }
}

PATCH/api/v1/quizzes/:id/hooks

Update an existing hook. Include hookId in the request body along with the fields you want to update.

Request Body

{
  "hookId": 1,
  "title": "Updated title",
  "animationStyle": "zoom",
  "displayDuration": 7
}

Response

{
  "data": {
    "id": 1,
    "title": "Updated title",
    "animationStyle": "zoom",
    "displayDuration": 7,
    "updatedAt": "2025-01-16T10:00:00Z"
  }
}

DELETE/api/v1/quizzes/:id/hooks

Delete a hook by ID. Pass the hookId as a query parameter.

Query Parameters

hookId   integer   The ID of the hook to delete

Response

{
  "data": {
    "deleted": true
  }
}

Renders

POST/api/v1/renders

Start a video render for a quiz. Returns immediately with a session ID. Poll the status endpoint to track progress.

Request Body

{
  "quizId": "dQw4w9WgXcQ"
}

Response

{
  "data": {
    "sessionId": "abc-123-def",
    "quizId": "dQw4w9WgXcQ",
    "status": "queued"
  }
}

GET/api/v1/renders

List all your renders with their current status. Results are paginated and can be filtered by quiz ID.

Query Parameters

page     integer   Page number (default: 1)
limit    integer   Results per page (default: 20, max: 100)
quizId   string    Optional filter by quiz ID

Response

{
  "data": {
    "renders": [
      {
        "sessionId": "abc-123-def",
        "quizId": "dQw4w9WgXcQ",
        "quizTitle": "World Capitals Quiz",
        "status": "completed",
        "progress": 100,
        "duration": 45,
        "createdAt": "2025-01-15T08:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 15,
      "totalPages": 1
    }
  }
}

GET/api/v1/renders/:sessionId

Get detailed status for a specific render. Poll this endpoint to track rendering progress. Status can be: queued, rendering, completed, or failed.

Response

{
  "data": {
    "sessionId": "abc-123-def",
    "quizId": "dQw4w9WgXcQ",
    "quizTitle": "World Capitals Quiz",
    "status": "completed",
    "progress": 100,
    "duration": 45,
    "fileSize": 15728640,
    "createdAt": "2025-01-15T08:30:00Z",
    "completedAt": "2025-01-15T08:31:00Z"
  }
}

POST/api/v1/renders/:sessionId/download

Get a download URL for a completed render. This endpoint requires a paid plan. The URL is temporary and expires after 24 hours.

Response

{
  "data": {
    "downloadUrl": "https://...",
    "filename": "world-capitals-quiz.mp4"
  }
}

AI Quiz Generation

POST/api/v1/quizzes/generate

Request Body

{
  "topic": "The Solar System",
  "numberOfQuestions": 10,
  "difficulty": "medium",
  "quizType": "multiple_choice",
  "extraDirection": "Focus on the outer planets"
}

Response

{
  "data": {
    "id": "xK9mP2vLqRs",
    "title": "The Solar System Quiz",
    "description": "AI-generated quiz about The Solar System",
    "quizType": "multiple_choice",
    "questions": [
      {
        "id": "q1",
        "questionText": "Which planet is closest to the Sun?",
        "answers": [
          { "id": "a1", "answerText": "Venus", "isCorrect": false },
          { "id": "a2", "answerText": "Mercury", "isCorrect": true },
          { "id": "a3", "answerText": "Earth", "isCorrect": false },
          { "id": "a4", "answerText": "Mars", "isCorrect": false }
        ]
      }
    ],
    "createdAt": "2025-01-15T09:00:00Z"
  }
}

Flashcards

GET/api/v1/flashcards

List all your flashcard decks. Results are paginated.

Query Parameters

page    integer   Page number (default: 1)
limit   integer   Results per page (default: 20, max: 100)

Response

{
  "data": {
    "decks": [
      {
        "id": "fL3nR8wKpYt",
        "title": "Spanish Vocabulary",
        "description": "Common Spanish words and phrases",
        "cardCount": 50,
        "createdAt": "2025-01-14T12:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 12,
      "totalPages": 1
    }
  }
}

POST/api/v1/flashcards

Create a new flashcard deck.

Request Body

{
  "title": "Spanish Vocabulary",
  "description": "Common Spanish words and phrases"
}

Response

{
  "data": {
    "id": "fL3nR8wKpYt",
    "title": "Spanish Vocabulary",
    "description": "Common Spanish words and phrases",
    "createdAt": "2025-01-14T12:00:00Z"
  }
}

GET/api/v1/flashcards/:id

Get a flashcard deck with all its cards.

Response

{
  "data": {
    "id": "fL3nR8wKpYt",
    "title": "Spanish Vocabulary",
    "description": "Common Spanish words and phrases",
    "cards": [
      {
        "id": "c1",
        "front": "Hello",
        "back": "Hola"
      },
      {
        "id": "c2",
        "front": "Goodbye",
        "back": "Adios"
      }
    ],
    "createdAt": "2025-01-14T12:00:00Z"
  }
}

DELETE/api/v1/flashcards/:id

Permanently delete a flashcard deck and all its cards.

Response

{
  "data": {
    "deleted": true
  }
}

Account

GET/api/v1/account

Get your account information and API usage statistics.

Response

{
  "data": {
    "email": "user@example.com",
    "plan": "pro",
    "usage": {
      "requestsToday": 142,
      "requestsLimit": 1000,
      "quizzesCreated": 28,
      "flashcardDecksCreated": 15
    }
  }
}

Rate Limiting

The API enforces a default rate limit of 1,000 requests per day per API key. Rate limit information is included in response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 858
X-RateLimit-Reset: 2025-01-16T00:00:00Z

If you exceed the rate limit, you will receive a 429 response. Wait until the reset time before retrying.

Error Codes

Status	Code	Description
401	UNAUTHORIZED	Missing or invalid API key
403	FORBIDDEN	API key does not have permission for this action
404	NOT_FOUND	The requested resource was not found
429	RATE_LIMITED	Too many requests; wait for rate limit reset
500	INTERNAL_ERROR	An unexpected server error occurred

Response Format

All API responses return JSON. Successful responses wrap the result in a data field. Errors return an error message and code.

Success

{
  "data": {
    "id": "dQw4w9WgXcQ",
    "title": "My Quiz"
  }
}

Error

{
  "error": "Quiz not found",
  "code": "NOT_FOUND"
}

Ready to get started?

Create your API key and start building.

Get your API key View pricing