API base URL

https://api.shelfaivision.com

Use analyze for structured JSON and visualize for a rendered image with boxes and tags.

curl -X POST https://api.shelfaivision.com/v1/analyze \
  -H "X-API-Key: $SHELF_AI_API_KEY" \
  -F "image=@shelf.jpg"

Authentication

Direct private clients can use X-API-Key or Authorization: Bearer <key>. RapidAPI customers use RapidAPI's normal subscription headers; RapidAPI should inject X-RapidAPI-Proxy-Secret only on the private gateway-to-origin hop.

X-RapidAPI-Proxy-Secret is not a user-facing key. Do not expose origin secrets or internal worker tokens to public clients.

Endpoints

Endpoint	Request	Response
POST`/v1/analyze`	`multipart/form-data` with field `image`	`application/json`
POST`/v1/visualize`	`multipart/form-data` with field `image`	`image/jpeg` or `image/png`

Analyze response

{
  "request_id": "...",
  "image_path": "demo-shelf-before.jpg",
  "image_size": {"width": 1008, "height": 490},
  "model_versions": {
    "detector": "detector_v1_yolo11l_1280",
    "classifier": "classifier_v1_multitask_v4_v3core_bs128_lr1e4",
    "taxonomy": "tag_class_taxonomy_v2"
  },
  "defaults": {
    "detection_conf": 0.25,
    "detection_iou": 0.45,
    "classification_batch_size": 32,
    "classifier_bbox_padding": 0.05,
    "max_detections": 300
  },
  "detections_count": 1,
  "detections": [
    {
      "index": 0,
      "detector_class_id": 0,
      "detector_class_name": "product",
      "bbox_xyxy": [184.135, 93.219, 234.845, 185.733],
      "detection_score": 0.937166,
      "final_classes": {
        "product_supercategory": "beverages",
        "product_type": "energy_drink",
        "packaging_format": "can",
        "packaging_material": "metal",
        "storage_class": "ambient_shelf_stable"
      },
      "class_scores": {
        "product_supercategory": 0.895886,
        "product_type": 0.994563,
        "packaging_format": 0.993435,
        "packaging_material": 0.984227,
        "storage_class": 0.971812
      }
    }
  ]
}

Classification heads

product_supercategory
product_type
packaging_format
packaging_material
storage_class

Current taxonomy: tag_class_taxonomy_v2. Example values include beverages, energy_drink, can, metal, and ambient_shelf_stable. Clients should ignore unknown fields and read scores by key.

Validation and limits

Formats	JPEG, PNG, WEBP
Upload size	25 MB default maximum
Image dimensions	128×128 minimum, 8000×8000 maximum, 30 MP maximum
Aspect ratio	Maximum 6:1 after EXIF orientation
Default rate limits	30 requests/min, 1000 requests/day, 2 concurrent requests per identity

Error model

{
  "error": "invalid_image",
  "message": "Uploaded file is not a valid image",
  "request_id": "req_..."
}

`empty_upload`	No image bytes were uploaded.
`payload_too_large`	The file exceeds upload limits.
`invalid_image`	The upload is not a valid image.
`unsupported_image_format`	Only JPEG, PNG, and WEBP are accepted.
`rate_limited`	The request identity exceeded configured quota. Respect the limit and retry after the quota window resets.
`service_busy`	Receivers or workers are temporarily saturated. Retry with exponential backoff.
`inference_timeout`	The model request exceeded the execution deadline. Retry later or use a less crowded image.
`too_many_detections`	The detector found more products than the public processing limit allows.

RapidAPI notes

Publish /v1/analyze and /v1/visualize. Configure RapidAPI to pass a private proxy secret to X-RapidAPI-Proxy-Secret on origin requests. Keep direct public API keys only for internal smoke tests and private integrations. For the first public launch, keep the origin cap at 2 concurrent requests per identity.

base_url: https://api.shelfaivision.com
origin_secret_header: X-RapidAPI-Proxy-Secret
contract: https://docs.shelfaivision.com/api-contract.yaml