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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.