API Reference

The Ice9 API accepts image uploads and returns structured analysis from a coordinated ensemble of machine learning services. Submit an image, receive an image_id, poll until processing is complete, then retrieve the results.

Overview

Ice9 routes each image through multiple specialized ML services in parallel — object detection, image captioning, segmentation, color analysis, and more. Because these services run asynchronously, the API follows a submit-then-poll pattern:

1. Submit — POST /analyze queues the image and returns an image_id immediately.
2. Poll — GET /status/{image_id} returns live progress and results as services complete.
3. Retrieve — GET /results/{image_id} returns the complete payload once all services are done.

Results are available progressively — you can render partial output as each service finishes rather than waiting for everything.

Authentication

Every request must include your API key in the X-API-Key header. Keys are never embedded in query parameters or request bodies.

X-API-Key: ice9_your_key_here

A missing or invalid key returns 401 with the same message in both cases — no information is leaked about whether a key exists. Keys are rate-limited individually; see each endpoint for limits.

Quickstart

A complete end-to-end example using curl:

1. Submit an image

curl -X POST https://app.ice9.ai/analyze \
  -H "X-API-Key: ice9_your_key_here" \
  -F "file=@photo.jpg"

{
  "image_id":           4821,
  "trace_id":           "a3f7c2d1-...",
  "services_submitted": ["blip", "moondream", "yolo_v8", "..."],
  "image_width":        1920,
  "image_height":       1080
}

2. Poll for completion

curl https://app.ice9.ai/status/4821 \
  -H "X-API-Key: ice9_your_key_here"

Repeat until is_complete is true. Results populate progressively as services finish.

3. Get the final results

curl https://app.ice9.ai/results/4821 \
  -H "X-API-Key: ice9_your_key_here"

POST /analyze

Submit an image for analysis. The image is validated, normalized, and dispatched to the configured set of ML services. Returns immediately with an image_id — processing happens asynchronously.

Request

Content-Type must be multipart/form-data.

Tiers

Response — 202 Accepted

GET /status/{image_id}

Returns current processing state plus all results available so far. Call this repeatedly until is_complete is true. Results are included progressively — you can render useful output before all services have finished.

Path parameter

Response — 200 OK

Includes all image metadata, per-service completion state, and the full results payload (see Response fields). Status-specific fields:

GET /results/{image_id}

Returns the complete analysis payload for an image. Functionally equivalent to the final /status response but without the polling state fields. Call this after is_complete is true, or use it for already-processed images.

Path parameter

Returns the same results payload described in Response fields below, plus image metadata fields.

Response fields

Both /status and /results include a results payload. Fields are null until the corresponding stage has completed — check the *_complete flags on /status to know what is ready.

Polling pattern

Processing time varies based on image complexity and which services are running. A reasonable polling strategy is to start at 1–2 seconds and back off gradually.

# Python example
import time, requests

BASE = "https://app.ice9.ai"
HEADERS = {"X-API-Key": "ice9_your_key_here"}

# 1. Submit
resp = requests.post(f"{BASE}/analyze", headers=HEADERS,
                     files={"file": open("photo.jpg", "rb")})
image_id = resp.json()["image_id"]

# 2. Poll
interval = 1.5
while True:
    data = requests.get(f"{BASE}/status/{image_id}", headers=HEADERS).json()
    if data["is_complete"]:
        break
    time.sleep(interval)
    interval = min(interval * 1.3, 10)  # cap at 10s

# 3. Use results (or read them from the final status response above)
results = requests.get(f"{BASE}/results/{image_id}", headers=HEADERS).json()

Error codes

All error responses include a JSON body with an "error" string field.