🛡️ image-guard

Introduction

image-guard is a REST API that detects copyright-protected content (characters, brand logos, trademarks) and NSFW content in images. Results are streamed in real-time via Server-Sent Events (SSE).

Authentication

All requests to /api/* require an API key passed as a request header:

Requests without a valid key return 401 Unauthorized.

How it works

Detection runs in two stages:

Early exit: if Stage 1 detects copyright or NSFW, Stage 2 is skipped. The full pipeline only runs for images that pass Stage 1.

GET /health

Response

"status": "ok",
"version": "1.1.0"

POST /api/check

Request

Response

Content-Type: text/event-stream. Each event is a JSON object prefixed with data: .

SSE Events

Events arrive in order. The final event is always result.

{
  "type": "vision",
  "copyright": true,          // boolean — copyright content detected
  "identified": "Mickey Mouse (Disney)",  // string — what was found, or null
  "nsfw": false,               // boolean — NSFW content detected
  "nsfwReason": null,           // string | null
  "editPrompt": null            // string | null — only set if image is safe
}

{
  "type": "provider_result",
  "provider": "openai",        // "openai" | "gemini"
  "blocked": false             // true = content policy blocked = flagged
}

{
  "type": "result",
  "safe": false,               // true = safe to use, false = flagged
  "reason": "copyright",        // "copyright" | "nsfw" | "provider" | null
  "identified": "Mickey Mouse (Disney)",
  "earlyExit": true             // true = Stage 2 was skipped
}

Complete flow — FLAGGED (early exit)

data: {"type":"vision","copyright":true,"identified":"Mickey Mouse (Disney)","nsfw":false,"nsfwReason":null,"editPrompt":null}

data: {"type":"result","safe":false,"reason":"copyright","identified":"Mickey Mouse (Disney)","earlyExit":true}

Complete flow — SAFE (full pipeline)

data: {"type":"vision","copyright":false,"identified":null,"nsfw":false,"nsfwReason":null,"editPrompt":"Replace the dog with a cat"}

data: {"type":"provider_result","provider":"openai","blocked":false}

data: {"type":"provider_result","provider":"gemini","blocked":false}

data: {"type":"result","safe":true,"reason":null,"identified":null,"earlyExit":false}

Error Responses

Code Examples

cURL

curl -X POST https://image-guard.readingtester.com/api/check \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "image=@/path/to/image.jpg" \
  --no-buffer

JavaScript (Node.js / fetch)

import fs from "fs";

const form = new FormData();
form.append("image", new Blob([fs.readFileSync("image.jpg")]), "image.jpg");

const res = await fetch("https://image-guard.readingtester.com/api/check", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" },
  body: form,
});

const reader = res.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  const lines = decoder.decode(value).split("\n");
  for (const line of lines) {
    if (line.startsWith("data: ")) {
      const event = JSON.parse(line.slice(6));
      console.log(event);
      if (event.type === "result") {
        console.log("Safe:", event.safe, "| Reason:", event.reason);
      }
    }
  }
}

Python

import requests

with open("image.jpg", "rb") as f:
    response = requests.post(
        "https://image-guard.readingtester.com/api/check",
        headers={"X-API-Key": "YOUR_API_KEY"},
        files={"image": ("image.jpg", f, "image/jpeg")},
        stream=True,
    )

for line in response.iter_lines():
    if line.startswith(b"data: "):
        import json
        event = json.loads(line[6:])
        print(event)
        if event["type"] == "result":
            print("Safe:", event["safe"])

Limits & Notes