Platform
ScaiWave ScaiGrid ScaiCore ScaiBot ScaiDrive ScaiKey Models Tools & Services
Solutions
Organisations Developers Internet Service Providers Managed Service Providers AI-in-a-Box
Resources
Support Documentation Blog Downloads
Company
About Research Careers Investment Opportunities Contact
Log in

Downloading a model

Pull a whole version, a single file, or stream bytes — with resume and checksum verification.

Download a whole version#

python
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
from pathlib import Path
from scaiatlas import ScaiAtlas

client = ScaiAtlas.from_env()

files = client.download.version(
    "poolnoodle", "noodletron", "1.0.0",
    destination=Path("./noodletron"),
    resume=True,             # continue partial files instead of restarting
    verify_checksum=True,    # SHA-256 every file; raises ChecksumError on mismatch
)
for f in files:
    print("saved", f)

Use latest to always get the newest published version:

python
1
client.download.version("poolnoodle", "noodletron", "latest", destination="./noodletron")

latest skips versions that are still uploading and versions that have been deprecated, so it keeps serving the current release while the next one is being pushed. A model with nothing published yet returns 404.

Download a single file#

python
1
2
3
4
5
6
path = client.download.file(
    "poolnoodle", "noodletron", "1.0.0",
    file_path="config.json",
    destination="./config.json",
    verify_checksum=True,
)

Stream without touching disk#

python
1
2
3
4
5
buf = bytearray()
for chunk in client.download.stream("poolnoodle", "noodletron", "1.0.0",
                                    file_path="config.json"):
    buf.extend(chunk)
print(len(buf), "bytes")

Progress reporting#

python
1
2
3
4
5
6
7
8
from scaiatlas.resources.download import DownloadProgress

def on_progress(p: DownloadProgress):
    print(f"{p.file_name}: {p.percent_complete:.1f}%")

client.download.version("poolnoodle", "noodletron", "1.0.0",
                        destination="./noodletron",
                        progress_callback=on_progress)

Downloading a specific variant#

By default you get the primary variant. To pull a conversion (e.g. the GGUF build), target it over REST with the variant query parameter:

bash
1
GET /api/v1/namespaces/poolnoodle/models/noodletron/versions/1.0.0/download?variant=gguf-q4_k_m

List variants first to see what's available and available:

python
1
2
for v in client.variants.list_all("poolnoodle", "noodletron", "1.0.0"):
    print(v.variant_name, v.status)

The version has to be published first#

download returns 400 while a version is still uploading:

json
1
{"detail": "Version is not available (current: uploading)"}

That means the version was created and its files uploaded, but nobody marked it ready. It is not a transfer failure. See Version lifecycle.

How resume + verification behave#

  • Resume (resume=True): if a partial file exists, the client issues a Range request and appends from the last byte. A fully-present file whose checksum already matches is skipped.
  • Verification (verify_checksum=True, the default): after writing, the client recomputes SHA-256 and compares against the registry's value. On mismatch it raises ChecksumError carrying expected and actual.

Errors to handle#

Exception When
NotFoundError Namespace, model, version, variant, or file doesn't exist.
AuthorizationError You lack download permission on the namespace.
ChecksumError Downloaded bytes don't match the recorded checksum.
DownloadError Transfer failed (network, storage).
python
1
2
3
4
5
6
7
8
from scaiatlas.exceptions import NotFoundError, ChecksumError

try:
    client.download.version("poolnoodle", "noodletron", "9.9.9", destination="./x")
except NotFoundError:
    print("no such version")
except ChecksumError as e:
    print("corrupt download:", e.expected, "!=", e.actual)

Under the hood (REST)#

  • GET …/versions/{version}/download — file metadata + URLs (optional variant, file).
  • GET …/versions/{version}/download/files/{path} — streamed bytes, Range-aware (206 Partial Content, X-Checksum-SHA256, Accept-Ranges: bytes, Content-Range).

Downloads require the namespace DOWNLOAD permission and the version to be in an available/ready state.

Range is passed to storage, so the cost of a read does not depend on how far into the file it starts: resuming a 2.4 GB image at its last byte is as quick as reading its first. All three forms work — bytes=0-999, bytes=500- and bytes=-500 for the final 500 bytes — and an end past the last byte is clamped rather than refused.

A Range that cannot be satisfied, such as a first byte at or past the end of the file, returns 416. A Range that is not valid syntax returns 400 rather than being ignored.

Redirecting to storage#

Add ?redirect=true to a file download and the registry answers 307 with a short-lived pre-signed storage URL instead of streaming the bytes itself. Follow it with the same Range header; ranges work on the redirect exactly as they do on the proxied path.

gdscript
1
2
GET …/versions/{version}/download/files/{path}?redirect=true
  -> 307, Location: https://<storage>/...?X-Amz-Signature=...

It is off by default, because it requires the client to reach object storage directly, which not every network allows. Turn it on where the machine doing the pulling can.

The URL is a bearer token for that one object, so it is deliberately short-lived — minutes, enough to start a transfer. Storage does not cut a download already in progress when the URL expires, so a slow pull of a large image is fine. Treat the URL as a secret and do not log or share it.

The download is recorded at the moment of the redirect, since the registry never sees the transfer itself. That means the log counts downloads started, not bytes delivered.

Who downloaded what#

GET /api/v1/access-logs?action=download returns the download history. Each entry carries api_key_id and api_key_name, the model_name, version_id, file_path, the address and the user agent.

Read api_key_id to answer "which machine pulled this". For a download made with an API key, user_id is the key's owner of record — the person who created the key — not someone who performed the download.

A namespace-scoped key sees only its own namespaces' history.

Updated 2026-10-17 15:44:57 View source (.md) rev 5