# AI Exam Practice Helper (`saadithya/ai-exam-practice-helper`) Actor

Extract and solve MCQ questions from images using AI for study and practice purposes.

- **URL**: https://apify.com/saadithya/ai-exam-practice-helper.md
- **Developed by:** [Aadhithya](https://apify.com/saadithya) (community)
- **Categories:** AI, Automation, Other
- **Stats:** 3 total users, 1 monthly users, 100.0% runs succeeded, 2 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.01 / answered

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## AI Exam Practice Helper

[![Apify Actor](https://apify.com/actor-badge)](https://apify.com/saadithya/ai-exam-practice-helper)

An intelligent Apify Actor that extracts and solves multiple-choice questions (MCQs) from images using advanced AI vision capabilities. Designed for students and educators to streamline exam preparation and study workflows.

### Overview

The **AI Exam Practice Helper** leverages cutting-edge AI vision models (OpenAI GPT-4o-mini) to automatically extract MCQ questions from images, identify correct answers, and provide detailed explanations. This tool transforms static exam materials into interactive study resources, enabling efficient learning and practice.

#### Key Features

- **AI-Powered Vision Analysis**: Extracts text and questions from images using state-of-the-art vision models
- **Intelligent Question Parsing**: Automatically identifies question text and multiple-choice options
- **Automated Answer Solving**: Determines correct answers with AI reasoning
- **Detailed Explanations**: Provides concise, educational explanations for each answer
- **Batch Processing**: Handles multiple images in a single run for efficient workflows
- **Test Mode**: Validate setup without consuming API credits
- **Structured Output**: Clean JSON format ideal for further processing or integration

### Input Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `imageUrls` | Array of strings | Yes | - | URLs of images containing MCQ questions |
| `apiKey` | String | Yes | - | OpenAI API key for AI processing |
| `model` | String | No | `gpt-4o-mini` | AI model to use for extraction and solving |
| `testMode` | Boolean | No | `false` | Returns mock data without API calls |

#### Input Example

```json
{
  "imageUrls": [
    "https://example.com/exam-page-1.jpg",
    "https://example.com/exam-page-2.jpg"
  ],
  "apiKey": "sk-your-openai-api-key",
  "model": "gpt-4o-mini",
  "testMode": false
}
```

### Output Format

The actor outputs structured JSON data to an Apify dataset with the following fields:

| Field | Type | Description |
|-------|------|-------------|
| `slNo` | Number | Serial number for ordering |
| `question` | String | Full question text including all options |
| `explanation` | String | Detailed explanation of the correct answer |
| `correctAnswer` | String | The correct option (e.g., "A. Paris") |

#### Output Example

```json
{
  "slNo": 1,
  "question": "What is the capital of France?\n\nOptions:\nA. London\nB. Berlin\nC. Paris\nD. Madrid",
  "explanation": "Paris is the capital and largest city of France. It has been the country's capital since 987 CE and is known for its cultural significance.",
  "correctAnswer": "C. Paris"
}
```

### Use Cases

#### Educational Institutions

- Convert paper-based exams into digital practice tests
- Create study materials from textbook images
- Generate answer keys with explanations

#### Students

- Digitize handwritten notes and practice questions
- Get instant explanations for difficult questions
- Build personalized study databases

#### Content Creators

- Extract questions from screenshots or scanned documents
- Create quiz content from existing materials
- Automate question bank development

#### Corporate Training

- Convert training materials into interactive assessments
- Create certification practice exams
- Generate learning resources from documentation

### How It Works

The actor operates in a two-stage pipeline:

```
┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  Input Images   │────▶│  AI Extraction   │────▶│  Question List  │
└─────────────────┘     └──────────────────┘     └─────────────────┘
                                                            │
                                                            ▼
┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  Output Dataset │◀────│  AI Solving      │◀────│  Each Question  │
└─────────────────┘     └──────────────────┘     └─────────────────┘
```

#### Stage 1: Question Extraction

1. Downloads and analyzes each image using AI vision
2. Identifies MCQ patterns and structures
3. Extracts question text and answer options
4. Returns structured question data

#### Stage 2: Answer Solving

1. Processes each extracted question individually
2. Uses AI reasoning to determine the correct answer
3. Generates educational explanations
4. Outputs structured results to dataset

### Performance & Limitations

- **Execution Time**: Typically completes within 1-5 minutes depending on image count and question density
- **Image Formats**: Supports JPG, PNG, and other common image formats via URL
- **Question Types**: Optimized for standard multiple-choice questions (A, B, C, D format)
- **Accuracy**: AI-generated answers should be verified; included disclaimer emphasizes educational use

### Error Handling

The actor includes robust error handling:

- Invalid image URLs are logged and skipped
- API errors are captured with descriptive messages
- Malformed responses are parsed with fallback strategies
- Failed images don't stop processing of remaining images

### Pricing

#### Apify Compute Units

- **Base Cost**: Varies based on run duration and memory usage
- **Average Run**: ~0.1-0.5 compute units per 10 questions

#### OpenAI API Costs

- **GPT-4o-mini**: ~$0.15 per 1M input tokens, ~$0.60 per 1M output tokens
- **GPT-4o**: ~$2.50 per 1M input tokens, ~$10.00 per 1M output tokens
- Typical cost: $0.01-$0.05 per image processed

### Getting Started

#### Prerequisites

1. [Apify account](https://console.apify.com/sign-up)
2. [OpenAI API key](https://platform.openai.com/api-keys)
3. Images containing MCQ questions hosted at accessible URLs

#### Quick Start

1. Navigate to the [Actor page](https://apify.com/saadithya/ai-exam-practice-helper)
2. Click **"Start"** or **"Try for Free"**
3. Enter your input parameters:
   - Add image URLs
   - Provide your OpenAI API key
   - Adjust model if needed
4. Click **"Start"** to run the actor
5. Download results from the Dataset tab

#### Local Development

```bash
## Clone the repository
git clone https://github.com/yourusername/ai-exam-practice-helper.git
cd ai-exam-practice-helper

## Install dependencies
npm install

## Set up environment variables
export APIFY_TOKEN=your-apify-token
export OPENAI_API_KEY=your-openai-key

## Run locally
npm start
```

### API Usage

#### Run via API

```bash
curl -X POST https://api.apify.com/v2/acts/saadithya~ai-exam-practice-helper/runs \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -d '{
    "imageUrls": ["https://example.com/exam.jpg"],
    "apiKey": "sk-your-openai-key",
    "model": "gpt-4o-mini",
    "testMode": false
  }'
```

#### Retrieve Results

```bash
curl https://api.apify.com/v2/datasets/{datasetId}/items \
  -H 'Authorization: Bearer YOUR_API_TOKEN'
```

### Support & Resources

- **Actor Page**: [apify.com/saadithya/ai-exam-practice-helper](https://apify.com/saadithya/ai-exam-practice-helper)
- **Apify Documentation**: [docs.apify.com](https://docs.apify.com)
- **OpenAI API Docs**: [platform.openai.com/docs](https://platform.openai.com/docs)
- **Report Issues**: Via the Apify platform or GitHub issues

### Disclaimer

⚠️ **EDUCATIONAL USE ONLY**

This tool is designed for educational and study purposes only. The answers and explanations provided by AI may not always be accurate. Always verify with official sources and use your own judgment. The creators assume no responsibility for incorrect answers or academic outcomes.

### License

MIT License - See LICENSE file for details.

### Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

***

**Built with** ❤️ **using [Apify](https://apify.com) and [OpenAI](https://openai.com)**

# Actor input Schema

## `imageUrls` (type: `array`):

Array of image URLs containing MCQs

## `apiKey` (type: `string`):

OpenAI API key (not required in Test Mode)

## `model` (type: `string`):

AI model to use for extraction and solving

## `testMode` (type: `boolean`):

Return 1 mock result without making AI calls (enable for testing)

## Actor input object example

```json
{
  "imageUrls": [
    "https://example.com/sample-mcq.jpg"
  ],
  "model": "gpt-4o",
  "testMode": true
}
```

# Actor output Schema

## `results` (type: `string`):

Dataset containing extracted and solved MCQ questions

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "imageUrls": [
        "https://example.com/sample-mcq.jpg"
    ],
    "model": "gpt-4o",
    "testMode": true
};

// Run the Actor and wait for it to finish
const run = await client.actor("saadithya/ai-exam-practice-helper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "imageUrls": ["https://example.com/sample-mcq.jpg"],
    "model": "gpt-4o",
    "testMode": True,
}

# Run the Actor and wait for it to finish
run = client.actor("saadithya/ai-exam-practice-helper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "imageUrls": [
    "https://example.com/sample-mcq.jpg"
  ],
  "model": "gpt-4o",
  "testMode": true
}' |
apify call saadithya/ai-exam-practice-helper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,saadithya/ai-exam-practice-helper"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/SmOrBYACE9Xt4gvhK/builds/OyZpOb5EevyZvZkO5/openapi.json