HF Wrapper
    │
    ├─1─▶ GET /upload-url (get presigned S3 URL)
    │
    ├─2─▶ PUT image directly to S3 (free, bypasses API Gateway)
    │
    ├─3─▶ POST /detect {"job_id", "s3_url"} (tiny payload)
    │
    └─4─▶ GET /status/{job_id} (poll until complete)

API Format

Input

Accepts images in multiple formats:

json

// HTTP URL
{"inputs": "https://example.com/image.jpg"}

// Data URL (base64 encoded)
{"inputs": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA..."}

// Raw base64
{"inputs": "iVBORw0KGgoAAAANSUhEUgAAAAUA..."}

Output

Returns EMCO-compatible format:

json

{
  "predictions": [
    {
      "id": 1,
      "label": "callout",
      "class_id": 0,
      "confidence": 0.95,
      "bbox": {
        "x1": 100,
        "y1": 200,
        "x2": 300,
        "y2": 400
      }
    }
  ],
  "total_detections": 1,
  "image": "base64_encoded_image",
  "image_width": 1920,
  "image_height": 1080
}

Bounding Box Format

Input from Lambda: [x, y, width, height] (xywh format)
Output to LearningStudio: {"x1", "y1", "x2", "y2"} (xyxy format)

The wrapper automatically converts between these formats.

Configuration

This endpoint requires the following secrets to be configured in HuggingFace Inference Endpoint settings:

Secret	Description
`API_GATEWAY_URL`	Full URL of the API Gateway endpoint (e.g., `https://xxx.execute-api.us-east-1.amazonaws.com/dev`)
`API_KEY`	API key for authentication

Usage

Python

python

import requests

HF_ENDPOINT = "https://your-endpoint.endpoints.huggingface.cloud"
HF_TOKEN = "your-hf-token"

response = requests.post(
    HF_ENDPOINT,
    headers={"Authorization": f"Bearer {HF_TOKEN}"},
    json={"inputs": "https://example.com/architectural-drawing.png"}
)

result = response.json()
print(f"Found {result['total_detections']} callouts")
for pred in result["predictions"]:
    print(f"  Callout {pred['id']}: {pred['bbox']}, confidence={pred['confidence']}")

cURL

bash

curl -X POST https://your-endpoint.endpoints.huggingface.cloud \
  -H "Authorization: Bearer $HF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"inputs": "https://example.com/architectural-drawing.png"}'

Processing Time

Typical processing time is 30-120 seconds depending on image size and complexity. The wrapper polls the backend every 5 seconds with a maximum timeout of 15 minutes.

Error Handling

Errors are returned in a consistent format:

json

{
  "error": "Description of the error",
  "predictions": [],
  "total_detections": 0,
  "image": ""
}

License

Apache 2.0

torinittechnologies/learningstudio-callout-wrapper

LearningStudio Callout Detection Wrapper

Overview

Architecture

API Format

Input

Output

Bounding Box Format

Configuration

Usage

Python

cURL

Processing Time

Error Handling

License

torinittechnologies/
learningstudio-callout-wrapper