Model artifacts

A model artifact is a set of model files you store on SynapsAI before deployment: weights, config.json, tokenizer files, and anything else the model needs to load. Use an artifact when the weights are not in a Hugging Face repository you want the platform to pull. Send requests to https://api.synapsai.cloud/v1/model-artifacts. Your API key needs upload permission. When the artifact status is ready, deploy it from the launch wizard by choosing that artifact as the model source. The pipeline detected from the files must be one of the supported tasks. Weights should be Safetensors.

Create and upload

Create the artifact record

Send display_name and a pipeline such as text-generation. The response includes artifact.id.

Start an upload session

POST /v1/model-artifacts/{artifact_id}/uploads returns upload_id. The artifact must not already be ingesting, and it cannot be in use by a deployment.

Send each file

PUT /v1/model-artifacts/{artifact_id}/uploads/{upload_id}/files?path= streams the raw bytes. path is the relative path stored in the artifact (config.json, model.safetensors).

Complete the upload

POST .../complete inspects the files and marks the artifact ready or failed. Deploy only after status is ready.

Python SDK

pip install --upgrade synapsai-python. client.model_artifacts creates the record, uploads a file or a directory, and reads the artifact back.

from synapsai import SynapsAI

client = SynapsAI(timeout=3600.0)

created = client.model_artifacts.create(
    display_name="My weights",
    pipeline="text-generation",
)
artifact_id = created.artifact.id

artifact = client.model_artifacts.upload(
    "./my-model",  # a file or a directory
    artifact_id=artifact_id,
)
print(artifact.id, artifact.status, artifact.size_gb)

upload() starts a session, sends every file, and completes it. Directory uploads keep relative paths. A single file is stored under its filename. pipeline is set only by create().

SDK method	HTTP
`create(display_name, pipeline)`	`POST /v1/model-artifacts`
`retrieve(artifact_id)`	`GET /v1/model-artifacts/{id}`
`start_upload(artifact_id)`	`POST /v1/model-artifacts/{id}/uploads`
`upload_file(artifact_id, upload_id, path, file)`	`PUT …/files?path=`
`complete_upload(artifact_id, upload_id)`	`POST …/complete`
`upload(path, artifact_id=...)`	start, upload each file, complete

AsyncSynapsAI has these methods too. Raise timeout for large weight files. The example above uses 3600 seconds.

Step by step

session = client.model_artifacts.start_upload(artifact_id)
client.model_artifacts.upload_file(
    artifact_id,
    session.upload_id,
    path="model.safetensors",
    file="./model.safetensors",
)
client.model_artifacts.upload_file(
    artifact_id,
    session.upload_id,
    path="config.json",
    file="./config.json",
)
result = client.model_artifacts.complete_upload(artifact_id, session.upload_id)
print(result.artifact.status)

CLI

The package installs a synapsai command. The artifact must already exist.

synapsai upload-model ./my-model --artifact-id artifact-demo-abc12345

--timeout defaults to 3600 seconds.

API reference

Method	Path	Action
`POST`	`/v1/model-artifacts`	Create an artifact (`display_name`, `pipeline`)
`GET`	`/v1/model-artifacts/{artifact_id}`	Retrieve an artifact
`POST`	`/v1/model-artifacts/{artifact_id}/uploads`	Start an upload session
`PUT`	`/v1/model-artifacts/{artifact_id}/uploads/{upload_id}/files?path=`	Upload one file
`POST`	`/v1/model-artifacts/{artifact_id}/uploads/{upload_id}/complete`	Finish the upload

A 409 means ingest is already running or the artifact is attached to a deployment. A 403 on start means the storage quota is full. Ephemeral upload keys cannot create a new artifact record.

Getting started

Products

Guides

Examples

Manage

Platform

Resources

Support

Legal

Create and upload

Python SDK

Step by step

CLI

API reference

​Create and upload

​Python SDK

​Step by step

​CLI

​API reference

Create and upload

Python SDK

Step by step

CLI

API reference