Image Evaluation API

Try it

Run a real evaluation against the live API, right here — no API key needed on your end. This uses a public demo key on a small shared quota, so it's for getting a feel of the response, not for real integration testing.

Submitted as originalUrl — we derive our own preview from it server-side, there's no separate preview URL to provide. Must respond 200 directly (no redirects) and serve JPEG/PNG/TIFF/BMP/HEIC. Demo quota is small and shared by every visitor — if it's exhausted, try again shortly, or use your own key (see Getting Started).

Authentication

Every request requires an x-api-key header. Keys are issued manually — contact us to get one; there's no self-serve signup.

x-api-key: <your-api-key>

A missing or invalid key returns 403 Forbidden.

Rate limits

Third-party keys are metered:

• 5 requests/second, burst 10
• 1,000 requests/month

Contact us if you need a higher limit.

Getting Started

A minimal path from zero to your first evaluation result.

1. Get an API key

Keys are issued manually — contact us to request one. There's no self-serve signup.

2. Submit your first evaluation

This example is runnable as-is — it points at a public test image, so you can copy/paste it and get a real result without hosting anything yourself first.

curl -X POST https://api.vonango.com/evaluations \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "originalUrl": "https://httpbin.org/image/jpeg"
  }'

{ "evaluationId": "07fc0511-e795-4cad-919f-e661c316a19c", "status": "processing" }

Save the evaluationId — you'll need it to poll for the result.

3. Poll for the result

curl https://api.vonango.com/evaluations/07fc0511-e795-4cad-919f-e661c316a19c \
  -H "x-api-key: $API_KEY"

Repeat every 3–5 seconds until status is no longer "processing". Most evaluations complete in under a minute.

4. Read the result

When status is "completed", the result field contains contentAnalysis (what the AI sees) and preprocessing (measured metadata, color, and sharpness) — see The result object below for the full field reference. When status is "failed", see Troubleshooting below.

Same flow, in code

import requests
import time

API_KEY = "your-api-key"
BASE_URL = "https://api.vonango.com"

def evaluate(original_url):
    response = requests.post(
        f"{BASE_URL}/evaluations",
        headers={"x-api-key": API_KEY},
        json={"originalUrl": original_url},
    )
    response.raise_for_status()
    evaluation_id = response.json()["evaluationId"]

    while True:
        time.sleep(3)
        result = requests.get(
            f"{BASE_URL}/evaluations/{evaluation_id}",
            headers={"x-api-key": API_KEY},
        ).json()
        if result["status"] != "processing":
            return result

result = evaluate("https://httpbin.org/image/jpeg")
print(result)

const API_KEY = "your-api-key";
const BASE_URL = "https://api.vonango.com";

async function evaluate(originalUrl) {
  const submit = await fetch(`${BASE_URL}/evaluations`, {
    method: "POST",
    headers: { "x-api-key": API_KEY, "Content-Type": "application/json" },
    body: JSON.stringify({ originalUrl }),
  });
  const { evaluationId } = await submit.json();

  while (true) {
    await new Promise((r) => setTimeout(r, 3000));
    const poll = await fetch(`${BASE_URL}/evaluations/${evaluationId}`, {
      headers: { "x-api-key": API_KEY },
    });
    const result = await poll.json();
    if (result.status !== "processing") return result;
  }
}

const result = await evaluate("https://httpbin.org/image/jpeg");
console.log(result);

Troubleshooting

Common reasons an evaluation ends in status: "failed", and what to do about each:

A 403 Forbidden on the request itself — before you ever get an evaluationId — means the x-api-key header is missing or invalid, including on /health.

Endpoints

{
  "originalUrl": "https://example.com/original.jpg",
  "services": ["upscale"],
  "contentPolicy": "strict"
}

{
  "evaluationId": "07fc0511-e795-4cad-919f-e661c316a19c",
  "status": "processing"
}

Content moderation

Every submission is checked against Amazon Rekognition's content moderation before anything else runs — the check happens first, gating the whole pipeline, so rejected content is never analyzed, upscaled, or stored beyond the rejection itself.

The contentPolicy request field controls how much nudity is tolerated:

Regardless of contentPolicy, two things are never permitted and cannot be resubmitted at any tier:

• Graphic sexual acts.
• Any apparent sexualized depiction of a minor. Content flagged for this is quarantined, not simply rejected.

If content is rejected, the evaluation ends in status: "failed" (the same shape as any other ingest-time failure — see Troubleshooting), not a 4xx on the submit request itself, since the URL/request were well-formed and the rejection only becomes known after fetching and inspecting the image.

A note on the age-based check specifically: this uses an automated age estimate (Amazon Rekognition's DetectFaces) as a triage signal, not a definitive determination — it only fires on a detectable, mostly-frontal face, and estimated ages carry real error margins. It is intentionally conservative in the direction of over-flagging rather than under-flagging.

The result object

Present when status: "completed". Two top-level parts always present: contentAnalysis (what the AI sees) and preprocessing (measured metadata, color, and size-aware sharpness). A third, upscale, appears only when "upscale" or "upscale-hd" was requested in services — see below.

contentAnalysis

AI vision analysis of the preview image.

preprocessing

Deterministic metadata/pixel analysis of the original file.

printSizeCategories

One entry per standard print-size product category. Each reports what the native resolution actually delivers at that size.

† Open-ended — reported at a 48" reference size.

sharpness.assessmentByPrintSize

AI visual sharpness judgment, one per category, keyed the same as printSizeCategories.

colorAnalysis.dominantColors

Top colors by pixel frequency, computed directly from pixel data — no AI. Each entry is a hex value and the percentage of sampled pixels it accounts for.

exposureAnalysis

Deterministic exposure/lighting statistics computed directly from pixel data — no AI, same spirit as colorAnalysis.

upscale

Present only when "upscale" or "upscale-hd" was requested in services — see POST /evaluations. Two tiers of 4x upscaling: a failed upscale never fails the overall evaluation, the contentAnalysis/preprocessing fields above are still returned normally.

Both are non-generative — they sharpen/enlarge the pixels already in your source image rather than inventing new detail. If both values are included in the same request, "upscale-hd" takes precedence — they aren't cumulative.

Source size limit. The upscale add-on (both tiers) currently rejects source files over 50MB, separate from and much smaller than the 1.5GB limit for the core evaluation. This is an adjustable operational setting, not a fixed platform limit — if this page and the API's actual behavior ever disagree, trust the error message you get back, since that always reflects the live configured value:

"upscale": {
  "status": "failed",
  "errorType": "SourceImageTooLargeException",
  "errorCause": "Source image (87.3 MB) exceeds the maximum size for upscaling (50.0 MB). The core evaluation still completed normally - resubmit without the upscale add-on, or with a smaller source file, to get an upscaled result."
}

// abbreviated — full example in the written reference
{
  "contentAnalysis": {
    "subjectMatter": "A tabby cat resting on a light-colored couch.",
    "composition": "Centered subject, shallow depth of field.",
    "obviousIssues": [],
    "containsInappropriateContent": false,
    "contentWarnings": []
  },
  "preprocessing": {
    "nativeWidthPx": 2400, "nativeHeightPx": 1602,
    "colorSpace": "RGB",
    "hasEmbeddedColorProfile": true,
    "embeddedColorProfileName": "sRGB IEC61966-2.1",
    "printSizeCategories": {
      "extraSmall": { "width": 6.0, "height": 4.0, "dpi": 400.0, "grade": "excellent", "recommendedViewingDistanceInches": 8.6 },
      "large":      { "width": 36.0, "height": 24.0, "dpi": 66.67, "grade": "poor", "recommendedViewingDistanceInches": 51.57 }
    },
    "sharpness": {
      "assessmentByPrintSize": {
        "extraSmall": { "score": 36, "grade": "excellent", "reasoning": "…" },
        "large":      { "score": 11, "grade": "poor", "reasoning": "…" }
      }
    },
    "colorAnalysis": {
      "dominantColors": [{ "hex": "#cfcfce", "percentage": 31.0 }]
    },
    "exposureAnalysis": {
      "meanBrightness": 132.4, "contrastStdDeviation": 54.2,
      "lightingUniformityDelta": 12.6, "flags": [],
      "summary": "Exposure and contrast look good for printing."
    }
  },
  // only present when "upscale" or "upscale-hd" was requested in services
  "upscale": {
    "status": "completed", "tier": "basic", "provider": "real-esrgan", "scaleFactor": 4,
    "upscaledImageUrl": "https://fwimageeval-assets.s3.amazonaws.com/07fc.../upscaled.jpg?X-Amz-Signature=..."
  }
}