Downloading a model
Pull a whole version, a single file, or stream bytes — with resume and checksum verification.
Download a whole version#
1 2 3 4 5 6 7 8 9 10 11 12 13 | |
Use latest to always get the newest published version:
1 | |
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#
1 2 3 4 5 6 | |
Stream without touching disk#
1 2 3 4 5 | |
Progress reporting#
1 2 3 4 5 6 7 8 | |
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:
1 | |
List variants first to see what's available and available:
1 2 | |
The version has to be published first#
download returns 400 while a version is still uploading:
1 | |
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 aRangerequest 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 raisesChecksumErrorcarryingexpectedandactual.
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). |
1 2 3 4 5 6 7 8 | |
Under the hood (REST)#
GET …/versions/{version}/download— file metadata + URLs (optionalvariant,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.
1 2 | |
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.