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_credit_units 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_credits; 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_credits} internal units")
    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 credits. One displayed credit equals 1,000 internal units; for example, client.credits().available / 1000 gives the displayed balance. Credit expiry is available through credit_lots and next_expiry on the balance response.

Download the product bundle

New jobs expose five typed artifacts: reflectance, scl, cloud_mask, and provenance. 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"):
            suffix = ".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 per order plus €0.025 per km² at the base model rate (4 credits plus 0.1 credits/km²); 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 credits. For a region that may cross tile boundaries, call client.scenes.coverage_plan(...). The short lived plan joins same acquisition tiles and reports native mask coverage. 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_credits` 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, but the hosted endpoint is currently disabled and has not been deployed. See docs/MCP_CLIENTS.md for client setup, approval requirements and the local stdio bridge.

Coverage planning in SDK 0.1.3 uses a bounded 120-second request allowance for real imagery preflight; other operations retain the client timeout. This patch is built locally at dist/hypersr-0.1.3-py3-none-any.whl; install that wheel until the release is published. 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 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.

client.jobs.download_role(job.id, "bundle", "hypersr_results.zip")

Metadata

Release files for hypersr 0.1.3

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.1.3
File Size Uploaded Provenance Actions
hypersr-0.1.3.tar.gz 93.4 kB Without provenance Details for hypersr-0.1.3.tar.gz

Built distribution (wheel)

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

Total release size: 108.6 kB

Release files / hypersr-0.1.3.tar.gz

Download URL hypersr-0.1.3.tar.gz
Size 93.4 kB
Tags Source
SHA-256 checksum
How to use checksums
7c08fb83d10a09d31c5997f6f2b0f79ceaec2cbee18e878c244d94493026fa5c
BLAKE2b-256 checksum
How to use checksums
052829557ba3b293bd4cdcbec9c9a26da1b7ab968ff2d14f498e947994983a40
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.1.3-py3-none-any.whl

Download URL hypersr-0.1.3-py3-none-any.whl
Size 15.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
04921309241eabc3cae2232043a5a1009a38fb05d6eeeb3a58f11394a0f6532b
BLAKE2b-256 checksum
How to use checksums
728da06fa5d4217c49ebf1ad5b8dcf6fe18aeb6ff5adf5e50e1f1b355f47b7e0
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.1.3

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