HorusEngine API guide for integrators

The API categorizes image processing into two groups: Scene context modes (obstacles, nearby, social, full) and Task modes (identify, find). Integrators must understand these definitions and the usage restrictions below.

These modes return structured spatial descriptions from a still image. They must NEVER be used for: autonomous passenger vehicles; real-time spatial pathfinding or walking guidance for blind or visually impaired individuals; or any mission-critical physical movement where delayed, missing, or incorrect API output could cause injury or property damage. For robotics, use only as a semantic layer alongside local deterministic sensors. (see Robotics & Multi-Sensor Fusion below)

While this API must never be used as a standalone, real-time safety system for physical movement, it is highly effective when deployed as a Semantic Reasoning Layer alongside deterministic sensors like LiDAR or Radar.

Integrators building robotic applications must separate Safety/Control loops from Cognitive/Intent loops:

• The Sensor Layer (LiDAR/Sonar): Must handle all real-time distance calculations, immediate obstacle avoidance, and emergency stopping. This layer must operate locally and independently of the API.

• The API Layer (Semantic context): Receives static image frames to provide informational context. It helps classify or describe what objects appear in the scene (e.g. "locate the charging dock sign"). It does not control movement, braking, or emergency stops."

Wearable form-factors (e.g., smart glasses, action cameras, smartwatches, visual pins) present unique real-time risks. If your integration processes images sourced from a wearable device, you must strictly enforce the following constraints:

• Prohibited: Using images from a wearable device to perform automated medical triage, skin lesion analysis, or physical health assessments.

• Prohibited: Utilizing the API to scan public spaces via a wearable camera to match faces, track individuals, or create biometric databases.

Our API is designed for discrete, frame-based requests and is not optimized for persistent, high-frequency live video streams. Integrators using wearables should capture imagery on a trigger basis (e.g., user-initiated button press or voice command) rather than sending continuous live video frames.

The context field is optional. It tells HorusEngine what the user is doing or where they are, not what the camera shows.

The target field is used with the find mode only

For repeat calls in acceptable use cases (e.g. low-speed robotics with local LiDAR/radar handling safety), you may pass snippets from the previous response so HorusEngine reports what changed instead of repeating everything. This is not permitted for continuous wearable walking guidance. Wearables must use user-initiated, single-shot requests only (see Wearable restrictions above).

Multipart upload fields: previous_speakable_summary, previous_primary_alert_message. JSON body: previous_scan object.

• Chain the last response using speakable_summary and primary_alert_message from call N and send them on call N+1.

• For permitted repeat calls (robotics with local sensors): use obstacles + brief + previous_scan at a slow interval (e.g. 10–30 seconds) or on scene-change triggers only.

• Respect silence_ok when true, your TTS layer may skip speaking if nothing immediate has changed. Meaningful for permitted repeat-request loops only.

• Re-scan after scene changes. If the user turns a corner or enters a new room, clear previous_scan or expect a fresh description.

Task modes (identify, find) generally force silence_ok: false when there is output to speak. Do not use silence_ok to suppress identify/find results.

HorusEngine analyzes one still frame per request. Capture choices affect spatial field accuracy, bearings, and task-mode accuracy.

Navigation modes treat the center-lower third of the frame as the primary subject region for scene context modes. Typical phone or fixed camera FOV (~4:3 to 16:9) works best. Avoid ultrawide or body-mounted panoramic capture unless cropped before upload.

• The primary subject region becomes a thin horizontal strip, objects look smaller and bearings are less reliable.

• Targets in identify / find shrink in the frame, signs and handheld objects are harder to read.

• Very wide frames may compress more aggressively before analysis, reducing effective detail.

Instead: Crop to the subject or scene region you care about before upload. For identify and find, fill the frame with the subject when you can.

• Pause video before grabbing a frame, motion blur lowers confidence (preflight may reject very blurry frames).

• Move closer or crop tight before retrying a low-confidence identify result.

• Server normalization is a backstop; sensible capture on the client still matters.

For identify and find, use speakable_summary (and identified_objects[ ] / find_matches[ ] for UI). primary_alert is always null — do not expect scene-context-style alerts on task calls.

• If your app presents spoken output, you may prefer speakable_summary. The primary_alert field is optional structured text and not a safety alarm. Integrators must validate all output before presenting it to end users.

• Else speak speakable_summary.

• If silence_ok is true in an acceptable use case repeat-request loop, your output layer may consider skipping the TTS.

• Blurry or distant objects may return low confidence or empty identified_objects[ ] which is a valid result, not a failure.

• Do not treat high-confidence identified_objects[ ] entries as ground truth if they contradict speakable_summary.

• Crop toward the object or move closer before retrying.

Responses may include content_flags (distressing, adult). Spoken output should stay factual and non-graphic. Handle flags in your UI policy (warnings, alternate phrasing).

Only when LiDAR/radar/sonar handles real-time safety locally. Slow interval or scene-change trigger.

Your stack moves; our API doesn’t hold state. Send optional headers (X-Horus-Frame-Id, X-Horus-Client-Timestamp, or X-Horus-Client-Metadata) with each analyze call. The response will return the same data in client_metadata so you can sync semantics with LiDAR, odometry, and frame buffers. Metadata never goes to the model and isn’t stored.

Single request per user action (button press or voice command). Do not loop. Example: read a sign or identify and object:

Crop so the object fills the frame when possible.

HorusEngine analyzes one still image per request. How you capture, send, and schedule those requests drives cost, response time, and user experience.

A typical analyze call takes about 3–10 seconds from request to JSON response. Complex scenes or task modes may take longer.

Set your HTTP client timeout to at least 120 seconds so slow responses are not cut off mid-scan.

Plan your UX for asynchronous results — show a “scanning” state, queue TTS, or show a loading state until the response arrives.

Send individual still frames (JPEG/PNG upload or a public image URL). HorusEngine does not accept continuous video streams.

Send one still frame per POST. For robotics (with local sensors), you may repeat at 10–30 second intervals or on scene change. For wearables, send one frame per user-initiated action only, not on a timer while moving. For kiosks, typically one request per user interaction.

Do not use full or detailed on a tight repeat loop (e.g. sub-10 second) unless local sensors handle safety and you are on a robotics use case. Use obstacles + brief + previous_scan instead — lower cost and faster, focused answers.

HorusEngine does not prescribe how often you call the API. Choose an interval that matches how quickly your user can hear or act on updates:

• Robots and platforms: often 10–30 seconds, or only when the scene changes. (required: local LiDAR/radar/sonar for safety)

• Handheld / button press: one request per user action. Required pattern for wearables.

Sending frames faster than your output layer can use them increases cost and spoken-output fatigue without improving outcome.

If the image is already on the phone, glasses, or robot, use POST /v1/analyze/upload.

Use image_url only when the image is already available at a public http or https URL.

If you send too many requests in a short period, the API may respond with 429 Too Many Requests. Back off and reduce send rate. Rate limits (120/180 per min).

Typical integrator cadences are well within limits. Avoid sub-second repeat intervals or spending unchanged frames repeatedly.

See /docs/pricing for SKU matrix and list prices.

Listing a workflow under Acceptable Use Cases does not constitute a technical endorsement, warranty, or guarantee of safety by our company. Integrators bear sole legal and operational responsibility for testing, validating, and ensuring the safety of their applications, including the implementation of necessary hardware backups (such as LiDAR) and human-in-the-loop reviews.