ActivityImage API Documentation

Welcome to the ActivityImage API! Our RESTful API provides programmatic access to thousands of educational images, each available in 4 optimized sizes perfect for web apps, PDF generation, and digital content.

What You Can Build

• PDF Worksheet Generators - Use HQ Print format for crystal-clear printables
• Educational Web Apps - Responsive images with Web and Thumbnail formats
• Digital Learning Platforms - Rich visual content with advanced search
• Activity Creators - Access categorized clipart and illustrations

Authentication

ActivityImage API uses API keys to authenticate requests. You can obtain an API key by signing up for an account.

How to Authenticate

Include your API key in the request header:

Authorization: Bearer YOUR_API_KEY

Or pass it as a query parameter:

GET /api/v1/search?q=cat&api_key=YOUR_API_KEY

Rate Limiting

API requests are limited based on your subscription plan:

Plan	Requests per Minute	Monthly Limit
Free	10	1,000
Professional	100	50,000
Enterprise	Custom	Unlimited

Rate Limit Headers

Every API response includes rate limit information:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

Quick Start

Get started with the ActivityImage API in under 5 minutes:

1. Search for Images

curl https://activityimage.com/api/v1/search?q=cat \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "success": true,
  "data": [
    {
      "id": 123,
      "title": "Cute Cat Illustration",
      "slug": "cute-cat-illustration-abc123",
      "description": "A friendly orange cat",
      "category": {
        "name": "Animals",
        "slug": "animals"
      },
      "urls": {
        "hq_print": "https://activityimage.com/uploads/hq-print/cat-abc.png",
        "standard": "https://activityimage.com/uploads/standard/cat-abc.png",
        "web": "https://activityimage.com/uploads/web/cat-abc.png",
        "thumbnail": "https://activityimage.com/uploads/thumbnails/cat-abc.jpg"
      },
      "dimensions": {
        "hq_print": {"width": 2000, "height": 2000},
        "standard": {"width": 1000, "height": 1000},
        "web": {"width": 500, "height": 500},
        "thumbnail": {"width": 200, "height": 200}
      }
    }
  ],
  "pagination": {
    "total": 50,
    "page": 1,
    "per_page": 20,
    "total_pages": 3
  }
}

Search Images

Query Parameters

Parameter	Type	Required	Description
q	string	OPTIONAL	Search query (searches title, description, keywords, alt text)
category	string	OPTIONAL	Filter by category slug (e.g., "animals", "shapes")
category_id	integer	OPTIONAL	Filter by category ID
tag	string	OPTIONAL	Filter by tag slug
formats	string	OPTIONAL	Comma-separated formats (png, jpg, svg, gif)
page	integer	OPTIONAL	Page number (default: 1)
per_page	integer	OPTIONAL	Results per page (default: 20, max: 100)

Example Request

const response = await fetch(
  'https://activityimage.com/api/v1/search?q=animals&category=animals&per_page=10',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);

const data = await response.json();
console.log(data.data); // Array of images

import requests

url = "https://activityimage.com/api/v1/search"
params = {
    "q": "animals",
    "category": "animals",
    "per_page": 10
}
headers = {
    "Authorization": "Bearer YOUR_API_KEY"
}

response = requests.get(url, params=params, headers=headers)
images = response.json()["data"]

Random Images

Query Parameters

Parameter	Type	Required	Description
count	integer	OPTIONAL	Number of random images to return (default: 1, max: 50)
q	string	OPTIONAL	Keyword filter — returns random images matching this term (singular/plural forms are matched automatically)
category	string	OPTIONAL	Filter by category slug (e.g., "animals", "shapes")
category_id	integer	OPTIONAL	Filter by category ID
tag	string	OPTIONAL	Filter by tag slug
formats	string	OPTIONAL	Comma-separated formats to include (png, jpg, svg, gif)

Response

Returns a data array of randomly ordered images plus a total_matching count showing how many images matched your filters in total.

Examples

GET /api/v1/random?count=5&category=shapes

GET /api/v1/random?count=3&q=vegetable

{
  "count": 3,
  "total_matching": 24,
  "data": [
    {
      "id": 87,
      "title": "Broccoli Illustration",
      ...
    }
  ]
}

Get Image by ID

Example

GET /api/v1/images/123
GET /api/v1/images/cute-cat-illustration-abc123

Batch Retrieve

Query Parameters

Parameter	Type	Required	Description
ids	string	REQUIRED	Comma-separated image IDs (max: 100)

Example

GET /api/v1/batch?ids=123,456,789

Categories

Query Parameters

Parameter	Type	Required	Description
min_images	integer	OPTIONAL	Only return categories with at least this many images. Default: 0 (returns all categories). Use min_images=1 to hide empty categories.

Available Categories

Name	Slug	Images
Animals	animals	38
Birds	birds	24
Colors	colors	15
Flags	flags	27
Flowers	flowers	12
Food	food	24
Fruits	fruits	28
Part of body	part-of-body	12
Shapes	shapes	13
Transport	transport	18
Vegetables	vegetables	29

Examples

GET /api/v1/categories

GET /api/v1/categories?min_images=1

Example Response

{
  "success": true,
  "count": 17,
  "data": [
    {
      "id": 1,
      "name": "Animals",
      "slug": "animals",
      "description": "Mammals, birds, reptiles, insects, and sea creatures",
      "image_count": 38
    },
    {
      "id": 13,
      "name": "Birds",
      "slug": "birds",
      "description": "",
      "image_count": 24
    }
  ]
}

Using Categories with Search & Random

Use the slug from this endpoint as the category parameter in Search or Random requests:

// Step 1 — get category list
const cats = await fetch('/api/v1/categories?min_images=1').then(r => r.json());

// Step 2 — use a slug to filter images
const slug = cats.data[0].slug; // e.g. "animals"

// Search images in that category
const images = await fetch(`/api/v1/search?category=${slug}&per_page=20`).then(r => r.json());

// Or get random images from that category
const random = await fetch(`/api/v1/random?category=${slug}&count=6`).then(r => r.json());

Image Sizes

Every image is automatically available in 4 optimized sizes:

Size	Dimensions	Format	Use Case
HQ Print	2000 x 2000	PNG	PDF worksheets, high-quality printables
Standard	1000 x 1000	PNG	Digital content, presentations
Web	500 x 500	PNG	Web applications, previews
Thumbnail	200 x 200	JPG	Galleries, search results

Error Codes

The API uses standard HTTP status codes:

Code	Status	Description
200	OK	Request successful
400	Bad Request	Invalid parameters
401	Unauthorized	Invalid or missing API key
404	Not Found	Resource not found
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error

Error Response Format

{
  "success": false,
  "error": "Invalid API key"
}

Code Examples

PHP

<?php
$apiKey = 'YOUR_API_KEY';
$url = 'https://activityimage.com/api/v1/search?q=cat&per_page=10';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $apiKey
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
foreach ($data['data'] as $image) {
    echo $image['title'] . "\n";
    echo $image['urls']['web'] . "\n\n";
}
?>

Node.js

const axios = require('axios');

const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://activityimage.com/api/v1';

async function searchImages(query) {
  try {
    const response = await axios.get(`${BASE_URL}/search`, {
      params: { q: query, per_page: 10 },
      headers: { 'Authorization': `Bearer ${API_KEY}` }
    });

    return response.data.data;
  } catch (error) {
    console.error('API Error:', error.response.data);
  }
}

// Usage
searchImages('animals').then(images => {
  images.forEach(img => {
    console.log(img.title, img.urls.web);
  });
});

React Hook

import { useState, useEffect } from 'react';

function useActivityImages(query) {
  const [images, setImages] = useState([]);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    const fetchImages = async () => {
      setLoading(true);
      const response = await fetch(
        `https://activityimage.com/api/v1/search?q=${query}`,
        {
          headers: {
            'Authorization': 'Bearer YOUR_API_KEY'
          }
        }
      );
      const data = await response.json();
      setImages(data.data);
      setLoading(false);
    };

    if (query) fetchImages();
  }, [query]);

  return { images, loading };
}

// Component
function ImageGallery() {
  const { images, loading } = useActivityImages('cats');

  if (loading) return <div>Loading...</div>;

  return (
    <div className="gallery">
      {images.map(img => (
        <img key={img.id} src={img.urls.web} alt={img.alt_text} />
      ))}
    </div>
  );
}

Changelog

Version 1.0.0 - January 2026

• Multi-size image support (HQ Print, Standard, Web, Thumbnail)
• Full-text search with category and tag filtering
• Batch retrieval endpoint
• Random image endpoint
• API key authentication
• Rate limiting implementation

Need Help?

Check out our Live API Tester or contact support at support@activityimage.com

© 2026 ActivityImage. All rights reserved.