Platform
ScaiWave ScaiGrid ScaiCore ScaiBot ScaiDrive ScaiKey Modellen Tools & Services
Oplossingen
Organisaties Ontwikkelaars Internet Service Providers Managed Service Providers AI-in-a-Box
Kenniscentrum
Ondersteuning Documentation Blog Downloads
Bedrijf
Over ons Onderzoek Vacatures Investeren Contact
Inloggen

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.

  1. Create the model (once).
  2. Create the version, declaring every file up front.
  3. Upload each file in parts.
  4. Mark the version ready.

Prerequisites#

  • create_model and upload_version on 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.

python
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
from scaiatlas import ScaiAtlas
client = ScaiAtlas.from_env()

client.models.create(
    "poolnoodle", "noodletron",
    type="llm",                       # required; see the model-types reference
    display_name="Noodletron",
    description="A demo language model.",
    license="apache-2.0",
    tags=["demo", "8b"],
)

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:

python
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
with client.upload.version(
    "poolnoodle", "noodletron", "1.0.0",
    format="safetensors",
    release_notes="Initial release.",
    requirements={"transformers": ">=4.40"},
) as up:
    up.add_file("model.safetensors")
    up.add_file("config.json")
    up.add_file("tokenizer.json")
    version = up.complete()

print(version.full_name, version.status)   # poolnoodle/noodletron:1.0.0 ready

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:

python
1
2
3
4
with client.upload.version("poolnoodle", "noodletron", "1.0.0",
                           format="safetensors") as up:
    up.add_directory("./noodletron/", pattern="*", recursive=True)
    up.complete()

Check what is staged before committing to the transfer:

python
1
print(up.staged_files)   # ['config.json', 'model.safetensors', ...]

Progress reporting#

The callback fires per part, as the bytes go up — that is, during complete(), not during add_file.

python
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
from scaiatlas.resources.upload import UploadProgress

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

with client.upload.version("poolnoodle", "noodletron", "1.0.0",
                           format="safetensors",
                           progress_callback=on_progress) as up:
    up.add_file("model.safetensors")
    up.complete()

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.

  • version must be semver (1.0.0, 2.1.0-beta.1) or you get a ValidationError. Note the prerelease part allows dots but not hyphens: 1.0.0-sha.1a2b3c4d5e6f is valid, 1.0.0-sha-1a2b3c4d5e6f is not. Build metadata (+sha.…) is not accepted at all.
  • format must be in GET /api/v1/options/formats or the create step returns 400.
  • Re-using an existing version string returns a ConflictError. Because the version is created inside complete(), that surfaces there rather than when the session is opened.

Async note: upload and download are synchronous-only helpers. AsyncScaiAtlas exposes namespaces, models, versions, variants, and search, but not upload/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's total_size. The file records are created by upload/init. Send it accurately, and still init every file.
  • Use the server's part_size, returned by upload/init, rather than a size of your own. part_count tells you how many parts to expect.

Parts are sent as raw bodies, not form data:

bash
1
2
3
4
5
curl -X PUT \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/octet-stream' \
  --data-binary @part-001.bin \
  "$V/upload/$UPLOAD_ID/parts/1"

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:

python
1
2
3
4
5
6
client.variants.create(
    "poolnoodle", "noodletron", "1.0.0",
    variant_name="gguf-q4_k_m",
    format="gguf",
    quantization="Q4_K_M",
)

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:

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

Manage the version later#

python
1
2
3
4
client.versions.update("poolnoodle", "noodletron", "1.0.0",
                       release_notes="Patched tokenizer.")
client.versions.update("poolnoodle", "noodletron", "1.0.0", status="deprecated")
client.versions.delete("poolnoodle", "noodletron", "1.0.0")
Updated 2026-10-17 01:53:58 View source (.md) rev 2