Quickstart

This walkthrough takes you through the full workflow with runnable curl and Python: upload an image (one call), run a prediction, wait for it, and download the resulting ROIs as GeoJSON — entirely over the API.

Before you start

Get an API key

Create one in the dashboard (Settings → API Keys) and export it:

export HALFPAGE_API_KEY="hp_live_xxxxxxxxxxxxxxxxxxxxxxxx"
export BASE="https://api.halfpagetechnologies.com/backend/api/v1"

See Authentication for details.

Install tooling (for the bash examples)

The curl snippets use jq to read JSON responses. The Python snippets use requests (pip install requests).

1. Upload your image

One request does everything: POST /upload streams the file in, creates the image record for you (named after the file), converts it, and returns the record already ready. No pre-registration, no polling.

IMAGE_ID=$(curl -s -X POST "$BASE/upload" \
  -H "Authorization: Bearer $HALFPAGE_API_KEY" \
  -F "file=@image.tif" | jq -r .image.id)
echo "image: $IMAGE_ID"
# The returned image is already "ready" — no polling needed.

import os
import requests

BASE_URL = "https://api.halfpagetechnologies.com/backend/api/v1"
FILE_PATH = "image.tif"

session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['HALFPAGE_API_KEY']}"

# One call: creates the record, uploads and converts the pixels.
with open(FILE_PATH, "rb") as f:
    upload = session.post(f"{BASE_URL}/upload", files={"file": f})
upload.raise_for_status()
IMAGE_ID = upload.json()["image"]["id"]

Each image counts against your plan’s storage cap; POST /upload returns 402 once the cap is reached. Files can be up to 4 GB, but for anything larger than a few hundred MB — or a connection that might drop — use the resumable upload below.

2. Pick a model and run a prediction

List the models available to your organization, then run a prediction on your image. GET /models returns shared public base models (such as cpsam, the Cellpose-SAM generalist) alongside any custom models your org has trained.

# Pick the public cpsam base model (or the first available model).
MODEL_ID=$(curl -s "$BASE/models" -H "Authorization: Bearer $HALFPAGE_API_KEY" \
  | jq -r '(map(select(.name == "cpsam")) + .)[0].id')

# Run the prediction. Returns a prediction_id to poll.
PREDICTION_ID=$(curl -s -X POST "$BASE/predict" \
  -H "Authorization: Bearer $HALFPAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"model_id\": \"$MODEL_ID\", \"image_id\": \"$IMAGE_ID\"}" | jq -r .prediction_id)
echo "prediction: $PREDICTION_ID"

models = session.get(f"{BASE_URL}/models").json()
model_id = next((m["id"] for m in models if m["name"] == "cpsam"), models[0]["id"])

prediction = session.post(
    f"{BASE_URL}/predict",
    json={"model_id": model_id, "image_id": IMAGE_ID},
).json()
prediction_id = prediction["prediction_id"]

Each organization runs one prediction at a time. If you already have one running, POST /predict returns 400 — wait for it to finish. If an identical prediction is already queued, the response comes back with status: "skipped" and the existing prediction_id.

3. Wait for it to finish

Segmentation runs asynchronously on GPU workers, so poll GET /predict/{prediction_id} until status is COMPLETED. The completed response carries the segmentation_id you’ll export, plus the cell_count detected.

until [ "$(curl -s "$BASE/predict/$PREDICTION_ID" \
  -H "Authorization: Bearer $HALFPAGE_API_KEY" | jq -r .status)" = "COMPLETED" ]; do
  echo "segmenting..." && sleep 5
done
DONE=$(curl -s "$BASE/predict/$PREDICTION_ID" -H "Authorization: Bearer $HALFPAGE_API_KEY")
SEG_ID=$(jq -r .segmentation_id <<< "$DONE")
echo "segmentation: $SEG_ID ($(jq -r .cell_count <<< "$DONE") cells)"

import time

while True:
    prediction = session.get(f"{BASE_URL}/predict/{prediction_id}").json()
    if prediction["status"] == "COMPLETED":
        segmentation_id = prediction["segmentation_id"]
        print(f"found {prediction['cell_count']} cells")
        break
    if prediction["status"] == "FAILED":
        raise RuntimeError("prediction failed")
    time.sleep(5)

status moves through SUBMITTED → STARTED → COMPLETED (or FAILED).

4. Export the results

Download the segmentation in whichever format you need. The overlay PNG is a presentation RGB image with masks composited over HalfPage’s normalized preview. It does not preserve original TIFF bit depth, microscopy metadata, or scientific display settings. GeoJSON is handy for GIS and web tools; the CSV is one row per cell; the ZIP is an ImageJ/FIJI ROI archive.

# Presentation image with masks overlaid (PNG)
curl -s "$BASE/export/$SEG_ID/overlay.png" \
  -H "Authorization: Bearer $HALFPAGE_API_KEY" -o overlay.png

# GeoJSON ROIs
curl -s "$BASE/export/$SEG_ID/rois.geojson" \
  -H "Authorization: Bearer $HALFPAGE_API_KEY" -o rois.geojson

# Per-cell measurements (CSV)
curl -s "$BASE/export/$SEG_ID/measurements.csv" \
  -H "Authorization: Bearer $HALFPAGE_API_KEY" -o measurements.csv

# ImageJ ROI archive (ZIP)
curl -s "$BASE/export/$SEG_ID/rois.zip" \
  -H "Authorization: Bearer $HALFPAGE_API_KEY" -o rois.zip

geojson = session.get(f"{BASE_URL}/export/{segmentation_id}/rois.geojson")
geojson.raise_for_status()
with open("rois.geojson", "wb") as out:
    out.write(geojson.content)

# Also available:
#   GET /export/{segmentation_id}/overlay.png       -> presentation RGB image with masks
#   GET /export/{segmentation_id}/measurements.csv  -> per-cell measurements
#   GET /export/{segmentation_id}/rois.zip          -> ImageJ ROI archive

That’s the whole loop: upload → predict → export. 🎉

Large files: the resumable upload

For multi-GB files or unreliable connections, upload the pixels straight to object storage in chunks instead of through the API. It’s the same POST /upload endpoint — just send JSON ({name, size}) instead of a file. No bytes travel on that request; you get back presigned part URLs. PUT each chunk to its URL, call /complete, and poll until the image is ready. If a chunk fails, retry that one PUT; nothing else is lost.

The presigned PUT requests go straight to object storage — do not send your Authorization header on them. All other calls are authenticated with your API key as usual.

# a) Same endpoint, JSON body: creates the record AND returns the upload plan.
CREATE=$(curl -s -X POST "$BASE/upload" \
  -H "Authorization: Bearer $HALFPAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"name\": \"image.tif\", \"size\": $(wc -c < image.tif)}")
IMAGE_ID=$(jq -r .image.id <<< "$CREATE")
PART_SIZE=$(jq -r .upload.part_size <<< "$CREATE")

# b) Split the file into part_size chunks and PUT each to its presigned URL.
split -b "$PART_SIZE" image.tif hp_part_
i=0
for chunk in hp_part_*; do
  curl -sf -X PUT --data-binary "@$chunk" \
    "$(jq -r ".upload.urls[$i].url" <<< "$CREATE")" -o /dev/null
  i=$((i+1))
done

# c) Finish the upload — no body needed; the server verifies the parts itself.
curl -s -X POST "$BASE/upload/$IMAGE_ID/complete" \
  -H "Authorization: Bearer $HALFPAGE_API_KEY"
# -> {"status": "processing"}

# d) Conversion runs asynchronously: poll until the image is ready.
until [ "$(curl -s "$BASE/upload/$IMAGE_ID" \
  -H "Authorization: Bearer $HALFPAGE_API_KEY" | jq -r .upload_status)" = "ready" ]; do
  echo "converting..." && sleep 3
done
echo "image ready"

import time

# a) Same endpoint, JSON body: creates the record AND returns the upload plan.
create = session.post(
    f"{BASE_URL}/upload",
    json={"name": os.path.basename(FILE_PATH), "size": os.path.getsize(FILE_PATH)},
).json()
IMAGE_ID = create["image"]["id"]

# b) PUT each chunk directly to storage (no auth header on these).
with open(FILE_PATH, "rb") as f:
    for part in create["upload"]["urls"]:
        chunk = f.read(create["upload"]["part_size"])
        requests.put(part["url"], data=chunk).raise_for_status()

# c) Finish the upload — no body needed; the server verifies the parts itself.
session.post(f"{BASE_URL}/upload/{IMAGE_ID}/complete").raise_for_status()

# d) Conversion runs asynchronously: poll until the image is ready.
while True:
    image = session.get(f"{BASE_URL}/upload/{IMAGE_ID}").json()
    if image["upload_status"] == "ready":
        break
    if image["upload_status"] == "failed":
        raise RuntimeError(f"upload failed: {image.get('upload_error')}")
    time.sleep(3)

size must be the file’s exact byte size — the part plan is computed from it.

From here, continue at step 2 — everything downstream is identical.

The record counts against your storage cap from the moment it is created, and keeps counting until you delete it. If you abandon an upload, DELETE /upload/{image_id} frees the slot — it aborts anything still in flight and removes the record.

Full Python script

segment.py — the complete workflow in one file

import os
import time
import requests

BASE_URL = "https://api.halfpagetechnologies.com/backend/api/v1"
API_KEY = os.environ["HALFPAGE_API_KEY"]
FILE_PATH = "image.tif"

session = requests.Session()
session.headers["Authorization"] = f"Bearer {API_KEY}"


def upload_image(file_path: str) -> str:
    """One call: creates the record, uploads and converts the pixels, and
    returns the id of the ready-to-segment image."""
    with open(file_path, "rb") as f:
        upload = session.post(f"{BASE_URL}/upload", files={"file": f})
    upload.raise_for_status()
    return upload.json()["image"]["id"]


def predict(image_id: str) -> str:
    models = session.get(f"{BASE_URL}/models").json()
    model_id = next((m["id"] for m in models if m["name"] == "cpsam"), models[0]["id"])
    prediction = session.post(
        f"{BASE_URL}/predict",
        json={"model_id": model_id, "image_id": image_id},
    ).json()
    prediction_id = prediction["prediction_id"]
    while True:
        status = session.get(f"{BASE_URL}/predict/{prediction_id}").json()
        if status["status"] == "COMPLETED":
            return status["segmentation_id"]
        if status["status"] == "FAILED":
            raise RuntimeError("prediction failed")
        time.sleep(5)


def export(segmentation_id: str, out_path: str = "rois.geojson") -> None:
    resp = session.get(f"{BASE_URL}/export/{segmentation_id}/rois.geojson")
    resp.raise_for_status()
    with open(out_path, "wb") as out:
        out.write(resp.content)


if __name__ == "__main__":
    image_id = upload_image(FILE_PATH)
    segmentation_id = predict(image_id)
    export(segmentation_id)
    print(f"done — wrote rois.geojson for segmentation {segmentation_id}")

Get started

AI & agents

Before you start

1. Upload your image

2. Pick a model and run a prediction

3. Wait for it to finish

4. Export the results

Large files: the resumable upload

Full Python script

Next steps

API reference

Using with AI agents

​Before you start

​1. Upload your image

​2. Pick a model and run a prediction

​3. Wait for it to finish

​4. Export the results

​Large files: the resumable upload

​Full Python script

​Next steps

API reference

Using with AI agents

Before you start

1. Upload your image

2. Pick a model and run a prediction

3. Wait for it to finish

4. Export the results

Large files: the resumable upload

Full Python script

Next steps