🎨 Guess The Drawing API | Free Public REST API & WebP Image Server

The fast public REST API for drawing games, Discord trivia bots, and picture guessing applications.

---

📌 Table of Contents

1. Overview
2. Base URL & Connectivity
3. Main Features
4. Response Format & Status Codes
5. Public API Endpoints • Get Batch Drawings for Games • Search Active Drawings • Get Single Drawing Details • WebP Image Stream • System Health Check • Live System Metrics
6. Quick Code Examples • JavaScript Fetch • Python Requests • Discord Bot Example
7. Frequently Asked Questions
8. Developer Search Tags

---

🌐 Overview

Guess The Drawing API is a public web service built for developers who want to create drawing guess games, Discord trivia bots, mobile quiz apps, or web games.

All public endpoints are hosted at gtd.fizzystudio.xyz. No secret keys or login steps are required to read data, search drawings, or stream drawing images.

---

🚀 Base URL & Connectivity

All API requests are sent over secure HTTPS:

https://gtd.fizzystudio.xyz

Key Performance Benefits

• Fast WebP Image Delivery: All drawing images are streamed as compact WebP binary files to minimize load times. • Smart Browser Caching: Uses ETag and Last-Modified headers with 304 Not Modified status to save internet bandwidth. • Fair Rate Limiting: Up to 1000 requests per minute per IP address are supported to guarantee high speed for everyone. • Guild Cooldown Protection: Prevents repeated drawings within a 90 minute window for Discord servers or game rooms. • Cross Origin Enabled: Full CORS support allows direct connection from web pages, mobile apps, and server bots.

---

📋 Standard Response Format

Success Response (200 OK)

{
  "success": true,
  "data": {
    "publicId": "drw_a1b2c3d4e5f6a7b8c9d0e1f2",
    "primaryAnswer": "cat",
    "category": "Animals"
  }
}

Error Response (400 Bad Request or 404 Not Found)

{
  "success": false,
  "error": {
    "code": "ERR_RESOURCE_NOT_FOUND",
    "message": "Drawing with the specified public ID was not found",
    "timestamp": "2026-07-29T16:00:00.000Z",
    "requestId": "req_987654321"
  }
}

🚦 HTTP Status Codes

Status Code	Description	Action
200 OK	Request succeeded	Process returned JSON data or image
304 Not Modified	Image is already cached	Use local cached image
400 Bad Request	Bad parameter values	Check input fields and try again
404 Not Found	Drawing ID does not exist	Verify public ID parameter
429 Too Many Requests	Rate limit hit	Wait 1 minute before sending requests
500 Server Error	Server internal issue	Retry request after short delay

---

⚡ Public API Endpoints

1. Get Batch Drawings for Game Sessions

POST https://gtd.fizzystudio.xyz/api/v1/drawings/batch

Get a random set of active drawings for your game room or Discord bot while avoiding duplicate drawings for the same server.

Request Headers

Content-Type: application/json

Request Body Parameters

• guildId (string, optional): Unique ID of your Discord server or game channel. • count (number, optional, default: 5, max: 25): Amount of drawings requested. • category (string, optional): Filter by drawing category (example: "Animals"). • maxDifficulty (number, optional, 1 to 4): Limit max difficulty level.

Request Body Example

{
  "guildId": "987654321098765432",
  "count": 5,
  "category": "Animals",
  "maxDifficulty": 3
}

Response Example (200 OK)

{
  "success": true,
  "count": 5,
  "guildId": "987654321098765432",
  "cooldownMinutes": 90,
  "data": [
    {
      "publicId": "drw_a1b2c3d4e5f6a7b8c9d0e1f2",
      "answers": ["cat", "kitty", "feline"],
      "primaryAnswer": "cat",
      "category": "Animals",
      "difficulty": 1,
      "tags": ["pet", "cute"],
      "image": {
        "width": 800,
        "height": 600,
        "sizeBytes": 45120,
        "mimeType": "image/webp"
      },
      "status": "ACTIVE",
      "metrics": {
        "timesServed": 142
      },
      "createdAt": "2026-01-15T10:00:00.000Z",
      "updatedAt": "2026-01-15T10:00:00.000Z"
    }
  ]
}

cURL Command Example

curl -X POST https://gtd.fizzystudio.xyz/api/v1/drawings/batch \
  -H "Content-Type: application/json" \
  -d '{"guildId": "987654321098765432", "count": 5}'

---

2. Search Active Drawings

GET https://gtd.fizzystudio.xyz/api/v1/drawings/search

Search through active drawings using text keywords, tags, or category names.

Query Parameters

• query (string, optional): Text word to match in drawing answers or tags. • category (string, optional): Category name filter. • page (number, optional, default: 1): Page number. • limit (number, optional, default: 20, max: 100): Results count per page.

Request Example URL

https://gtd.fizzystudio.xyz/api/v1/drawings/search?query=cat&page=1&limit=20

Response Example (200 OK)

{
  "success": true,
  "data": [
    {
      "publicId": "drw_a1b2c3d4e5f6a7b8c9d0e1f2",
      "primaryAnswer": "cat",
      "answers": ["cat", "kitty"],
      "category": "Animals",
      "difficulty": 1,
      "tags": ["pet"]
    }
  ],
  "pagination": {
    "total": 12,
    "page": 1,
    "limit": 20,
    "totalPages": 1
  }
}

cURL Command Example

curl "https://gtd.fizzystudio.xyz/api/v1/drawings/search?query=cat&page=1&limit=20"

---

3. Get Single Drawing Details

GET https://gtd.fizzystudio.xyz/api/v1/drawings/:publicId

Retrieve complete public metadata for a specific drawing using its public ID.

Path Parameters

• publicId (string, required): The unique drawing public ID.

Request Example URL

https://gtd.fizzystudio.xyz/api/v1/drawings/drw_a1b2c3d4e5f6a7b8c9d0e1f2

Response Example (200 OK)

{
  "success": true,
  "data": {
    "publicId": "drw_a1b2c3d4e5f6a7b8c9d0e1f2",
    "answers": ["cat", "kitty", "feline"],
    "primaryAnswer": "cat",
    "category": "Animals",
    "difficulty": 1,
    "tags": ["pet", "cute"],
    "image": {
      "width": 800,
      "height": 600,
      "sizeBytes": 45120,
      "mimeType": "image/webp"
    },
    "status": "ACTIVE"
  }
}

cURL Command Example

curl "https://gtd.fizzystudio.xyz/api/v1/drawings/drw_a1b2c3d4e5f6a7b8c9d0e1f2"

---

4. WebP Image Stream

GET https://gtd.fizzystudio.xyz/api/v1/images/:publicId

Stream the high quality WebP image binary directly for displaying on web screens or sending in game chat messages.

Path Parameters

• publicId (string, required): Drawing public ID.

Response Headers Returned

• Content-Type: image/webp • Cache-Control: public, max-age=31536000, immutable • ETag: W/"a1b2c3d4e5f6a7b8" • Last-Modified: Fri, 15 Jan 2026 10:00:00 GMT

cURL Command Example

curl -i "https://gtd.fizzystudio.xyz/api/v1/images/drw_a1b2c3d4e5f6a7b8c9d0e1f2"

---

5. Check System Health

GET https://gtd.fizzystudio.xyz/health

Check the real time health status of the API server and database components.

Response Example (200 OK)

{
  "status": "HEALTHY",
  "timestamp": "2026-07-29T16:12:00.000Z",
  "components": {
    "database": {
      "status": "UP"
    },
    "storage": {
      "status": "UP"
    }
  }
}

cURL Command Example

curl "https://gtd.fizzystudio.xyz/health"

---

6. Live System Metrics

GET https://gtd.fizzystudio.xyz/metrics

Get live performance statistics including total request count, cache stats, and drawing counts.

Response Example (200 OK)

{
  "success": true,
  "timestamp": "2026-07-29T16:12:00.000Z",
  "system": {
    "totalRequests": 15420,
    "successfulRequests": 15380,
    "failedRequests": 40,
    "uptimeSeconds": 86400
  },
  "caches": {
    "drawingMetadata": {
      "hits": 12400,
      "misses": 300
    }
  },
  "database": {
    "totalActiveDrawings": 1250
  }
}

cURL Command Example

curl "https://gtd.fizzystudio.xyz/metrics"

---

💻 Quick Code Examples

1. JavaScript Fetch Example

async function getDrawingBatch() {
  const response = await fetch('https://gtd.fizzystudio.xyz/api/v1/drawings/batch', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ guildId: 'my_server_123', count: 5 })
  });

  const result = await response.json();
  console.log('Returned Drawings:', result.data);
}

getDrawingBatch();

2. Python Example

import requests

url = "https://gtd.fizzystudio.xyz/api/v1/drawings/batch"
payload = {"guildId": "my_server_123", "count": 5}

response = requests.post(url, json=payload)
data = response.json()

print(f"Retrieved {data['count']} drawings")
for drawing in data['data']:
    print(f"Drawing ID: {drawing['publicId']}, Primary Answer: {drawing['primaryAnswer']}")

3. Discord Bot Integration Snippet

const { EmbedBuilder } = require('discord.js');
const fetch = require('node-fetch');

async function sendDrawingGame(interaction) {
  const response = await fetch('https://gtd.fizzystudio.xyz/api/v1/drawings/batch', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ guildId: interaction.guildId, count: 1 })
  });

  const body = await response.json();
  const drawing = body.data[0];

  const imageUrl = `https://gtd.fizzystudio.xyz/api/v1/images/${drawing.publicId}`;

  const embed = new EmbedBuilder()
    .setTitle('🎨 Guess The Drawing!')
    .setDescription('Can you guess what this drawing is?')
    .setImage(imageUrl)
    .setColor('#06b6d4');

  await interaction.reply({ embeds: [embed] });
}

---

❓ Frequently Asked Questions

Q1: Is this API completely free to use?

Yes! The public endpoints hosted at gtd.fizzystudio.xyz are 100% free for developers, game builders, and Discord bot creators.

Q2: Do I need an API Key or Access Token?

No key is required for public endpoints like batch drawing retrieval, drawing search, and WebP image streaming.

Q3: How does the server prevent repeat drawings in game sessions?

When you send your server ID in the guildId body parameter, the API remembers which drawings were served to that server during a 90 minute cooldown window and picks fresh drawings.

---

guess-the-drawing-api drawing-game-api discord-drawing-bot free-public-api webp-image-stream-api trivia-game-backend picture-guessing-api drawing-trivia fastify-rest-api gtd-fizzy-studio