Model Upload

Upload and manage your custom AI models on the Runware platform. Integrate your own checkpoints, LoRAs, and other model types into your workflow.

Introduction

The Model Upload API lets you integrate custom models into the Runware platform. Upload your own checkpoints, LoRAs, or other supported model types and use them in generation tasks just like any other model on the platform.

Uploaded models are automatically optimized for the Sonic Inference Engine®, enhancing speed and efficiency without compromising output quality. Once processed, models are distributed across our infrastructure and can be referenced by their assigned identifiers in any API request.

Supported model categories

Checkpoints: Base models across multiple architectures including Stable Diffusion (1.x, 2.x, XL, 3.x) and FLUX.
LoRAs: Low-Rank Adaptation models for style and concept fine-tuning.
LyCORIS: An advanced alternative to LoRA for model fine-tuning.
VAE: Variational Autoencoder models for image encoding and decoding.
Embeddings: Textual Inversion embeddings for custom concepts and styles.

Visibility and versioning

You have full control over who can access your models. Set them as public (accessible to all platform users) or private (restricted to your organization). The API also supports multiple versions of the same model, allowing you to iterate on weights or configurations while maintaining a clean version history.

Storage pricing

Model upload is currently in beta and free of charge. There are no costs for uploading or storing models during this period.

After the beta period, storage will be charged at $0.05 per GB per month, rounded up to the nearest GB and calculated daily. We will not retroactively charge for storage used during the beta. A positive account balance is required to upload new models.

Request

The Runware API always accepts an array of objects as input, where each object represents a specific task to be performed. The structure of the object varies depending on the type of the task. For this section, we will focus on the parameters related to the model upload task.

The following JSON snippet shows the basic structure of a request object.

import { createClient } from '@runware/sdk'

const client = await createClient({ apiKey: process.env.RUNWARE_API_KEY })
await client.connect()

const result = await client.modelUpload({
  category: 'checkpoint',
  architecture: 'flux',
  format: 'safetensors',
  air: 'myorg:42@1',
  uniqueIdentifier: 'abc123def456',
  name: 'My Custom Model',
  version: 'v1',
  downloadURL: 'https://example.com/models/my-model.safetensors',
  private: true
})

import asyncio
import os

from runware import Runware


async def main():
    async with Runware(api_key=os.environ["RUNWARE_API_KEY"]) as client:
        result = await client.model_upload({
            "category": "checkpoint",
            "architecture": "flux",
            "format": "safetensors",
            "air": "myorg:42@1",
            "uniqueIdentifier": "abc123def456",
            "name": "My Custom Model",
            "version": "v1",
            "downloadURL": "https://example.com/models/my-model.safetensors",
            "private": True
        })


asyncio.run(main())

curl https://api.runware.ai/v1 \
  -H "Authorization: Bearer $RUNWARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "taskType": "modelUpload",
      "taskUUID": "b92ea202-349f-4560-adae-abb55a8146ee",
      "category": "checkpoint",
      "architecture": "flux",
      "format": "safetensors",
      "air": "myorg:42@1",
      "uniqueIdentifier": "abc123def456",
      "name": "My Custom Model",
      "version": "v1",
      "downloadURL": "https://example.com/models/my-model.safetensors",
      "private": true
    }
  ]'

runware model upload \
  --category checkpoint \
  --architecture flux \
  --format safetensors \
  --air myorg:42@1 \
  --unique-identifier abc123def456 \
  --name "My Custom Model" \
  --version v1 \
  --download-url https://example.com/models/my-model.safetensors \
  --private true

{
  "taskType": "modelUpload",
  "taskUUID": "b92ea202-349f-4560-adae-abb55a8146ee",
  "category": "checkpoint",
  "architecture": "flux",
  "format": "safetensors",
  "air": "myorg:42@1",
  "uniqueIdentifier": "abc123def456",
  "name": "My Custom Model",
  "version": "v1",
  "downloadURL": "https://example.com/models/my-model.safetensors",
  "private": true
}

taskType stringrequiredvalue: modelUpload: Identifier for the type of task being performed

taskUUID stringUUID v4: UUID v4 identifier for tracking tasks and matching async responses. Must be unique per task.

category stringrequired: Category of the model.
Allowed values5 values

format stringrequired: Format of the model file.
Allowed values1 value

air string: Artificial Intelligence Resource identifier. Format: provider:model@version.

uniqueIdentifier string: Unique identifier for the model.

name stringrequired: Name of the model.

version stringrequired: Version of the model.

downloadURL stringrequiredURI: URL where the model file is hosted.

private booleandefault: true: Whether the model should be private.

heroImageURL stringURI: URL of the hero image.

tags array of strings: Tags associated with the model.

shortDescription string: Short description of the model.

comment string: Additional comments or notes.

Checkpoints

When category is set to checkpoint, the following additional parameters are available:

type string: Type of the model (specific to category).
Allowed values2 values

architecture stringrequired: Architecture of the model.
Allowed values13 values

defaultScheduler string: Default scheduler.

defaultSteps integermin: 1: Default number of inference steps.

defaultCFG floatmin: 0: Default classifier-free guidance scale.

defaultStrength floatmin: 0max: 1: Default strength for img2img.

LoRAs

When category is set to lora, the following additional parameters are available:

type string: Type of the model (specific to category).
Allowed values2 values

architecture stringrequired: Architecture of the model.
Allowed values26 values

defaultWeight float: Default weight for the model.

positiveTriggerWords string: List of positive trigger words.

LyCORIS

When category is set to lycoris, the following additional parameters are available:

type string: Type of the model (specific to category).
Allowed values2 values

architecture stringrequired: Architecture of the model.
Allowed values25 values

defaultWeight float: Default weight for the model.

positiveTriggerWords string: List of positive trigger words.

VAE

When category is set to vae, the following additional parameters are available:

architecture stringrequired: Architecture of the model.
Allowed values7 values

Embeddings

When category is set to embeddings, the following additional parameters are available:

type string: Type of the model (specific to category).
Allowed values2 values

architecture stringrequired: Architecture of the model.
Allowed values7 values

Response

The API streams a sequence of status messages as your model progresses through the upload pipeline. Each message uses the same structure but indicates the current processing phase:

Validated: Model parameters and configuration have been verified.
Downloaded: Model file has been retrieved from the provided URL.
Optimized: Model has been optimized for the Sonic Inference Engine.
Stored: Model has been uploaded to distributed storage.
Ready: Model is deployed and available for use in generation tasks.

{
  "data": [
    {
      "taskType": "modelUpload",
      "taskUUID": "b92ea202-349f-4560-adae-abb55a8146ee",
      "status": "ready",
      "message": "Model successfully deployed and ready for use.",
      "air": "myorg:42@1"
    }
  ]
}

taskType stringvalue: modelUpload: Identifier for the type of task this response belongs to.

taskUUID stringrequiredUUID v4: UUID v4 identifier echoed from the original request, used to match async responses to their tasks.

status stringrequired: Status of the upload operation phase.
Possible values6 values

message stringrequired: Status message or error details.

air string: The AIR identifier of the uploaded model.