Uploading a model
The full path from "nothing" to a downloadable version.
Publishing is four steps, and the fourth is the one people miss: a version that has all its bytes is still not downloadable until it is marked ready.
- Create the model (once).
- Create the version, declaring every file up front.
- Upload each file in parts.
- Mark the version ready.
Prerequisites#
create_modelandupload_versionon the namespace — a member role, or an API key carrying those permissions. See Authentication.- The files you want to publish, locally.
1. Make sure the model exists#
Models are created once; versions are added over time. type is required.
1 2 3 4 5 6 7 8 9 10 11 | |
If it already exists you'll get a ConflictError — safe to ignore or catch.
2–4. Publish a version#
The upload session does all three remaining steps. add_file stages a file
and hashes it; complete() creates the version, uploads every part, and marks
the version ready:
1 2 3 4 5 6 7 8 9 10 11 12 | |
Nothing is sent until complete(). The registry needs the whole file list
when the version is created — that is where the version's total_size comes
from — so the version cannot exist until every file is known. add_file
therefore reads and hashes the file but holds it.
Add a whole directory instead of listing files:
1 2 3 4 | |
Check what is staged before committing to the transfer:
1 | |
Progress reporting#
The callback fires per part, as the bytes go up — that is, during
complete(), not during add_file.
1 2 3 4 5 6 7 8 9 10 | |
If something goes wrong#
The session is a context manager: if an exception leaves the with block
before complete(), the upload is aborted — in-flight multipart uploads
are cancelled and a version that was already created is deleted. You can also
call up.abort() explicitly.
versionmust be semver (1.0.0,2.1.0-beta.1) or you get aValidationError. Note the prerelease part allows dots but not hyphens:1.0.0-sha.1a2b3c4d5e6fis valid,1.0.0-sha-1a2b3c4d5e6fis not. Build metadata (+sha.…) is not accepted at all.formatmust be inGET /api/v1/options/formatsor the create step returns400.- Re-using an existing version string returns a
ConflictError. Because the version is created insidecomplete(), that surfaces there rather than when the session is opened.
Async note: upload and download are synchronous-only helpers.
AsyncScaiAtlasexposesnamespaces,models,versions,variants, andsearch, but notupload/download. Run transfers with the sync client (e.g. in a thread executor).
Driving it yourself (REST)#
Any language can do the same four steps. $V is the version root,
/api/v1/namespaces/{ns}/models/{model}/versions/{version}.
| # | Call | Notes |
|---|---|---|
| 1 | POST …/models/{model}/versions |
Declares version, format, and files[]. Returns status uploading. |
| 2 | POST $V/upload/init |
Per file. Returns upload_id, part_size, part_count. |
| 3 | PUT $V/upload/{upload_id}/parts/{n} |
Raw bytes as the body, 1-indexed. Returns the part's etag. |
| 4 | POST $V/upload/{upload_id}/complete |
Send {"parts": [{"part_number", "etag"}, …]}. |
| 5 | PATCH $V |
{"status": "ready"}. Without this the version stays uploading and will not download. |
Two details that bite:
files[]on step 1 does not register the files. It is used to compute the version'stotal_size. The file records are created byupload/init. Send it accurately, and still init every file.- Use the server's
part_size, returned byupload/init, rather than a size of your own.part_counttells you how many parts to expect.
Parts are sent as raw bodies, not form data:
1 2 3 4 5 | |
Abort a file's upload with DELETE $V/upload/{upload_id}.
See Version lifecycle for the states, and the REST API reference for exact schemas.
Add format variants (optional)#
Request an alternative representation of the version — e.g. a GGUF quantization:
1 2 3 4 5 6 | |
This returns immediately; conversion is asynchronous
(pending → converting → available). Creating a variant needs
upload_version; deleting one needs delete_any_model (or ownership plus
delete_own_model). List variants to check status:
1 2 | |
Manage the version later#
1 2 3 4 | |