All plans are🏷️30% OFFfor a limited time!www.cyliumos.online
CyliumOS
Back to service
API DOCUMENTATION

Object Visibility & Quality Detection Documentation

Complete API reference, integration examples, authentication guidelines, and response structures.

Try in PlaygroundGet API Key

Overview

Advanced computer vision inspection microservice powered by Cylium Vision and OpenCV. Assesses object framing, optical blur (Laplacian variance), partial occlusion, and border cropping.

Endpoint
POST /detect-visibility
· Base URL:https://vgdt.cyliumos.online

Authentication

Authenticate every HTTP request using the custom X-API-Key header:

X-API-Key: cyk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Do not expose your private key in client-side applications. Proxy requests through your backend service or Edge Workers.

Code Examples

Multi-Language SDKs
cURL — request
curl -X POST "https://vgdt.cyliumos.online/detect-visibility" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: cyk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "image": "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
    "detection_point": true
  }'

Object Visibility & Quality Detection API

Automated computer vision quality inspection evaluating sharpness, obstruction, and framing margins.

Authentication

Pass your universal API key in the X-API-Key header:

Code Snippet
X-API-Key: cyk_live_...

Endpoints

  1. POST /detect-visibility (JSON payload)
  2. POST /detect-visibility/upload (Multipart file upload)

Request Headers

HeaderTypeRequiredDescription
Content-TypestringYesapplication/json or multipart/form-data
X-API-KeystringYesUniversal API Key generated from dashboard

Request Body (JSON)

FieldTypeRequiredDescription
image_urlstringCond.Public URL to image
image_base64stringCond.Base64-encoded image string
image_pathstringCond.Local server path (testing)

(Supply exactly ONE of image_url, image_base64, or image_path)

Response Schema (200 OK)

Code Snippet
{
  "object_name": "Red Apple",
  "visibility": true,
  "confidence": 0.98,
  "message": "The apple is centrally positioned, sharp, and clearly visible.",
  "is_blurry": false,
  "is_occluded": false,
  "is_cut_off": false,
  "blur_score": 312.4,
  "cached": false
}

Code Examples

cURL (URL Input)

Code Snippet
curl -X POST "http://localhost:8003/detect-visibility" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: cyk_live_x9z0abcdef" \
  -d '{
    "image_url": "https://example.com/product.jpg"
  }'

cURL (File Upload)

Code Snippet
curl -X POST "http://localhost:8003/detect-visibility/upload" \
  -H "X-API-Key: cyk_live_x9z0abcdef" \
  -F "[email protected]"

TypeScript / JavaScript

Code Snippet
const res = await fetch("http://localhost:8003/detect-visibility", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "cyk_live_x9z0abcdef",
  },
  body: JSON.stringify({ image_url: "https://example.com/item.png" }),
});
const data = await res.json();
console.log("Visible:", data.visibility, "Blur Score:", data.blur_score);

Error Codes

StatusError CodeDescription
400invalid_imageCorrupt or empty image buffer
401missing_api_keyX-API-Key header missing
401invalid_api_keyKey not found in Firestore
403service_not_subscribedUser has not subscribed to visibility-detection
413image_too_largeImage exceeds 10 MB limit
415unsupported_formatImage format not supported
502vision_provider_errorUpstream Cylium Vision failure

Status & Error Responses

400 Bad Request
Input payload is empty, missing, or malformed.
{
  "detail": {
    "success": false,
    "error": "invalid_payload",
    "message": "Invalid request payload"
  }
}
401 Unauthorized
The X-API-Key header is missing or the key is not recognised.
{
  "detail": {
    "success": false,
    "error": "missing_api_key",
    "message": "X-API-Key header is required"
  }
}
402 Payment Required
No active subscription for this service.
{
  "detail": {
    "success": false,
    "error": "subscription_required",
    "message": "An active subscription is required to access this service"
  }
}
403 Forbidden
The key was revoked or has expired.
{
  "detail": {
    "success": false,
    "error": "api_key_expired",
    "message": "API key has expired or is revoked"
  }
}
429 Too Many Requests
Monthly request quota or rate limit has been reached.
{
  "detail": {
    "success": false,
    "error": "rate_limit_reached",
    "message": "Monthly API request limit reached"
  }
}
500 Internal Error
Server error occurred while processing the request.
{
  "detail": {
    "success": false,
    "error": "internal_error",
    "message": "Internal processing error"
  }
}

Sample Response

Example payload structure returned by this service.

{
  "object_name": "Product Bottle",
  "visibility": true,
  "confidence": 0.98,
  "message": "The bottle is centrally positioned, well-lit, sharp, and clearly visible.",
  "is_blurry": false,
  "is_occluded": false,
  "is_cut_off": false,
  "blur_score": 312.4,
  "cached": false
}
Ready to test?

Head over to the playground to upload your own files and inspect live bounding boxes and classifications.

Open Playground