Skip to main content

HyperSR Python SDK

hypersr is a typed, synchronous Python client for the HyperSR asynchronous Sentinel-2 super-resolution API. It requires Python 3.11 or newer.

Install

python -m pip install hypersr
# or, in a uv-managed project:
uv add hypersr

Set an API key through the environment or a secret manager:

export HYPERSR_API_KEY="hs_live_..."
export HYPERSR_SCENE_ID="<provider scene identifier>"
export HYPERSR_BBOX='[2.10, 41.30, 2.11, 41.31]'

The default endpoint is https://api.hypersr.com/v1. Pass base_url to use a local or staging API, for example HyperSR(api_key=key, base_url="http://localhost:8000/v1"). Replace the example bounding box with [west, south, east, north] coordinates covered by your selected scene. Installing the client does not activate the hosted service; a reachable API and an account with an API key are required.

Discover, quote, submit, and poll

For tiled coverage, call client.scenes.coverage_plan(...) first. Pass its plan_id to client.jobs.quote(...) with an acceptance policy. Review mode is the default; automatic mode requires a positive max_usd_micros cap. Submit with the exact returned plan hash and a confirm, automatic, or explicit quality override decision. The SDK forwards server-computed approval values; it never calculates cloud, overlap or pricing locally.

The server owns model availability and pricing. Discover enabled models first, then request a quote for a provider scene and WGS84 bounding box. A quote contains integer required_usd_micros; the client never calculates or submits a billable amount. Confirmation is an explicit jobs.submit call using the quote ID and an idempotency key.

import json
import os
from uuid import uuid4

from hypersr import HyperSR, HyperSRError

with HyperSR(
    os.environ["HYPERSR_API_KEY"],
    base_url=os.environ.get("HYPERSR_BASE_URL", "https://api.hypersr.com/v1"),
) as client:
    bbox = json.loads(os.environ["HYPERSR_BBOX"])
    models = client.models()
    model = next(item for item in models if item.slug == "hypersr_v1" and item.enabled)
    quote = client.jobs.quote(
        scene_id=os.environ["HYPERSR_SCENE_ID"],
        bbox=bbox,
        model=model.slug,
    )
    print(f"quote {quote.id}: ${quote.required_usd_micros / 1_000_000:.6f}")
    try:
        job = client.jobs.submit(quote_id=quote.id, idempotency_key=f"quickstart-{uuid4()}")
        result = client.jobs.wait(job.id, timeout=1800)
    except HyperSRError as exc:
        print(f"HyperSR request failed: {exc}")
    else:
        print(result.status, result.error_code, result.error_message)

wait returns all service terminal outcomes: completed, failed, and cancelled. It raises hypersr.TimeoutError when its deadline expires. A failed or cancelled queued job does not consume the reserved processing USD balance. Amounts are integer USD micros; for example, client.balance().available_usd_micros / 1_000_000 gives the displayed balance. Balance expiry is available through balance_lots and next_expiry.

Download the product bundle

New jobs expose five typed artifacts: reflectance, scl, cloud_mask, provenance, and bundle. Each has its own signed URL and checksum. The URLs are short-lived bearer capabilities; do not log or share them.

import os
from pathlib import Path

from hypersr import HyperSR

with HyperSR(
    os.environ["HYPERSR_API_KEY"],
    base_url=os.environ.get("HYPERSR_BASE_URL", "https://api.hypersr.com/v1"),
) as client:
    job = client.jobs.get(os.environ["HYPERSR_JOB_ID"])
    if job.status == "completed":
        output_dir = Path("hypersr-output")
        for role in ("reflectance", "scl", "cloud_mask", "provenance", "bundle"):
            suffix = ".zip" if role == "bundle" else ".json" if role == "provenance" else ".tif"
            client.jobs.download_role(job.id, role, output_dir / f"{role}{suffix}")

Set HYPERSR_JOB_ID to the ID returned by submission. Downloads use a separate HTTP client without the API key, stream to a temporary file, verify available size/SHA-256 metadata and replace the destination only after success.

Rasterio is optional. Install hypersr[rasterio] to inspect a downloaded reflectance COG; see examples/rasterio_metadata.py.

Retries, errors, and service limits

Safe reads retry transient HTTP failures. Mutations retry only when an idempotency key is present and the server operation supports replay; reuse the same key when retrying a submission. Key creation and saved-area creation are never automatically retried because their secrets/results cannot be replayed. HyperSRError is the common exception, with typed APIError subclasses for authentication, validation, not-found, conflict, and rate-limit responses. Retries are bounded (max_retries=2 by default), and each wait call has a deadline.

The service validates scene identifiers, WGS84 boxes, supported bands, model availability, quote expiry, area and queue limits. SR orders require at least $1.00 per order plus $0.025 per km² at the base model rate; the default maximum is 1,000 km² per job. The server measures geodetic area and rejects smaller processing areas with INVALID_AOI instead of rounding them up to the minimum. Scene search and saved AOIs can cover smaller areas. It may reject a well-formed request when a model or provider scene is unavailable. The initial release is asynchronous and supports Sentinel-2 Level-2A scenes covered by an enabled model; a 2.5 m output grid is reconstructed output spacing, not a native 2.5 m observation. See the repository API guide for the current contract and examples/ for runnable scripts.

The client also exposes saved AOIs (aois, get_aoi, create_aoi, update_aoi, delete_aoi), notification preferences, account summaries, server-configured billing packages, and filtered/paginated job history. Use client.scenes.search(bbox=bbox, target_date="2026-11-01", coverage_mode="intersects") to discover provider acquisitions before requesting a quote. Search returns a selected scene plus candidates and does not create a job or reserve balance. For a region that may cross tile boundaries, call client.scenes.coverage_plan(...). The short lived plan joins same acquisition tiles using only native 20 m SCL AOI windows. plan.source_plan.mask_preview.values contains classes 0–11; plan.source_plan.review.scl_class_percentages contains percentages indexed by class, using all AOI SCL cells including gaps. No spectral bands are downloaded at this stage. Billing includes covered clouds, shadows, water and snow; only no-data/defective classes 0/1 are excluded. Full spectral validation starts after submission. Provider spectral NoData within covered cells is filled per band with zero reflectance before inference; outside-area and SCL-uncovered cells remain NoData. Output tags/provenance record the fill policy and sample counts; filled inputs are not observations. This coverage-scl-v2 contract requires SDK 0.3.0 or newer; older plan formats are not supported. Request a quote with source_plan_id=plan.plan_id; set accept_partial_coverage=True only after explicitly accepting uncovered areas. When the server returns `quote.pricing`, it contains the authoritative fee and area breakdown; clients should continue to treat required_usd_micros as the total to reserve and should not calculate a replacement quote locally.

MCP access

Agent integrations use the separate HyperSR MCP connection and its scoped OAuth or dedicated MCP credential; do not send an MCP credential to the REST API. The intended endpoint is https://api.hypersr.com/mcp; hosted MCP access is currently disabled pending OAuth/provider acceptance. See docs/MCP_CLIENTS.md for client setup, approval requirements and the local stdio bridge.

Coverage planning uses a bounded 120-second request allowance for real imagery preflight; other operations retain the client timeout. Install the USD-compatible client with uv add "hypersr>=0.3.0". A source-plan quote still requires explicit submission and never starts a GPU merely by planning or quoting.

The bundle ZIP contains native-resolution original Sentinel-2 crops, the SR full ten-band physical-reflectance raster, masks, provenance, and a small SR_<area_><scene_id>_overview.png (maximum dimension 512 pixels). Only the PNG is independently stretched at the 2nd and 98th percentiles for display; it is not quantitative reflectance. Use SDK 0.1.3+ for the new bundle role. Old four-artifact jobs remain downloadable.

from pathlib import Path

bundle = next(output for output in client.jobs.outputs(job.id) if output.role == "bundle")
client.jobs.download_role(job.id, "bundle", Path(bundle.filename).name)

Coverage and billing follow the accepted SCL plan. Spectral gaps discovered during processing remain masked in outputs; they do not reject or reprice the order. Model context can enlarge the masked output area.

New jobs accept client.jobs.submit(quote_id=quote.id, area_name="North Field", idempotency_key="stable-request"). Names are hypersr_north_field_<job_id>.zip and SR_north_field_<scene_id>.tif; omit area_name for the scene-only TIFF and job-only ZIP. Use output roles and the returned filename; legacy jobs keep their existing filenames. The area label is frozen at submission and must be unchanged on retries. See filename contract.

Metadata

Release files for hypersr 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for hypersr 0.3.0
File Size Uploaded Provenance Actions
hypersr-0.3.0.tar.gz 92.4 kB Without provenance Details for hypersr-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for hypersr 0.3.0
File Interpreter ABI Platform Actions
hypersr-0.3.0-py3-none-any.whl Python 3 none any Details for hypersr-0.3.0-py3-none-any.whl

Total release size: 108.3 kB

Release files / hypersr-0.3.0.tar.gz

Download URL hypersr-0.3.0.tar.gz
Size 92.4 kB
Tags Source
SHA-256 checksum
How to use checksums
090d2cb81fecf7f80fab5290af0232d685921006d988d3c7a38cdc72ff2d71f8
BLAKE2b-256 checksum
How to use checksums
136285e4355197713739971aeedac7681d739ea3e47a4f678149e23e2ae2a938
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.24 {"installer":{"name":"uv","version":"0.11.24","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / hypersr-0.3.0-py3-none-any.whl

Download URL hypersr-0.3.0-py3-none-any.whl
Size 15.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9d2f58af4aa27ef2c99c65c1eb727db2684ad5df11740bf2112eb929b6141a8b
BLAKE2b-256 checksum
How to use checksums
e15dbfe072308d10db67080c4a819ea14ee93fa0bc0e546fe58b4c7e796622fe
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.24 {"installer":{"name":"uv","version":"0.11.24","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for hypersr 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page