> ## Documentation Index
> Fetch the complete documentation index at: https://docs.synapsai.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Model artifacts

> Upload model weights and config files, then deploy them as a SynapsAI model

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](/manage/api-keys) needs upload permission.

When the artifact status is **ready**, deploy it from the [launch wizard](https://platform.synapsai.cloud/launch-model) by choosing that artifact as the model source. The pipeline detected from the files must be one of the [supported tasks](/resources/tasks). Weights should be [Safetensors](/guides/convert-safetensors).

## Create and upload

<Steps>
  <Step title="Create the artifact record">
    Send `display_name` and a `pipeline` such as `text-generation`. The response includes `artifact.id`.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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`).
  </Step>

  <Step title="Complete the upload">
    `POST .../complete` inspects the files and marks the artifact ready or failed. Deploy only after status is `ready`.
  </Step>
</Steps>

## Python SDK

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

```python theme={null}
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

```python theme={null}
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.

```bash theme={null}
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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.