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,
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 (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 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. This coverage-scl-v2 contract requires SDK 0.2.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_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; 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 SCL-compatible
client with uv add "hypersr>=0.2.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
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.2.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.2.0.tar.gz | 91.2 kB | Without provenance | Details for hypersr-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| hypersr-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for hypersr-0.2.0-py3-none-any.whl |
Total release size: 106.7 kB
Release files / hypersr-0.2.0.tar.gz
| Download URL | hypersr-0.2.0.tar.gz |
|---|---|
| Size | 91.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3a4ac35c9216ea26836723ccb1d7e6e341ee498f7162feedf79a99a959171759
|
|
BLAKE2b-256 checksum How to use checksums |
a52a6073bb2ef720872f8f8daed954ae1e5a43f48864be7bc86d87a5808efe77
|
| 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.2.0-py3-none-any.whl
| Download URL | hypersr-0.2.0-py3-none-any.whl |
|---|---|
| Size | 15.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1563c1e0b2d5a919ef3adfdb4efb1f2f4665b5d7e9ca253b5f0b2560db952126
|
|
BLAKE2b-256 checksum How to use checksums |
8999320d667d941c6f17b97db0abc5f79dc9cb8fd230e1cc2c1c5201461477f8
|
| 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.2.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.