Upload a LoRA adapter

Run inference on your own low-rank adapter (LoRA) by uploading it to Together AI and deploying it for dedicated model inference. You can import an adapter from Hugging Face Hub or upload it from an S3 archive, whether or not you trained it on Together AI. You can also upload a full fine-tuned model instead of an adapter.

You don’t need to upload adapters created with post-training, because their inference checkpoints are already registered on the platform. Checkpoints on some base models aren’t registered, so you can’t deploy them.On supported base models, you can also attach several post-training adapters to one running multi-LoRA deployment of their base model and choose an adapter per request.

Requirements

An adapter is eligible for upload if it meets these requirements:

Source: Hugging Face Hub or an S3 presigned URL.
Files: The adapter directory must contain adapter_config.json and adapter_model.safetensors.
Base model: The adapter must target a base model that Together AI supports for dedicated inference.

If you’re uploading from S3, you must package the adapter files in a single archive (.zip or .tar.gz) with the files at the root of the archive, not nested inside an extra top-level directory. The presigned URL must point to the archive and have an expiration of at least 100 minutes.

Create the adapter

Register the adapter in your project before you upload weights. Every adapter must reference a supported base model via baseModelId. Give the adapter a readable name (for example my-stsb-lora), rather than a Hugging Face repo ID. If you pass an org-prefixed name like predibase/glue_stsb, the prefix will be stored on top of your project slug, and the catalog will render a doubled slug (for example your-project/predibase/glue_stsb).

Strip the org and pass only the bare repo name. An adapter that already has a doubled name can’t be renamed, so the only fix is to delete it and re-upload under the correct name.

List supported models and copy the id of the architecture the adapter targets (for example ml_CbJNwQC2ZqCU2iFT3mrCh).

tg models create my-stsb-lora \
  --type adapter \
  --base-model ml_CbJNwQC2ZqCU2iFT3mrCh

from together import Together

client = Together()
identity = client.whoami()
if identity.type != "project_api_key":
    raise RuntimeError("TOGETHER_API_KEY must be a project API key")
project_id = identity.project.id

adapter = client.models.create(
    project_id=project_id,
    type="adapter",
    name="my-stsb-lora",
    base_model_id="ml_CbJNwQC2ZqCU2iFT3mrCh",
)
print(adapter)

import Together from 'together-ai';

const client = new Together();
const identity = await client.whoami();
if (identity.type !== "project_api_key") {
  throw new Error("TOGETHER_API_KEY must be a project API key");
}
const projectId = identity.project.id;

const adapter = await client.models.create({
  projectId,
  type: 'adapter',
  name: 'my-stsb-lora',
  baseModelId: 'ml_CbJNwQC2ZqCU2iFT3mrCh',
});
console.log(adapter);

Save the returned model id (for example ml_abc123). You pass this value to the upload command in the next step. The --type adapter you set on create marks the record as a LoRA adapter, so the upload commands derive the type from the record and take no type flag.

Create request fields

Field	Required	Description
`name`	Yes	Inference-addressable name for the uploaded adapter.
`base_model_id`	Yes	`id` of the supported base model the adapter targets.
`description`	No	Description shown in your project catalog.

Upload the adapter

After creating the adapter record, upload its weights. Use a local upload when the files are on your machine, or a remote upload to stream them from Hugging Face or a presigned S3 URL. The adapter’s type and base model come from the record you created, so you don’t pass them again here.

Upload from your machine

Point the CLI at your local adapter directory:

CLI

tg models upload ml_abc123 ./path/to/adapter-dir

Upload from Hugging Face or S3

A remote upload streams the weights server-side. Pass the source URL as --from (use --token for gated or private Hugging Face repos). For S3, pass the presigned archive URL as --from (no token needed):

tg models remote-uploads create ml_abc123 \
  --from https://huggingface.co/your-org/your-adapter \
  --token hf_your_token

from together import Together

client = Together()
identity = client.whoami()
if identity.type != "project_api_key":
    raise RuntimeError("TOGETHER_API_KEY must be a project API key")
project_id = identity.project.id

job = client.models.remote_uploads.create(
    project_id=project_id,
    model_id="ml_abc123",
    remote_url="https://huggingface.co/your-org/your-adapter",
    token="hf_your_token",
)
print(job)

import Together from 'together-ai';

const client = new Together();
const identity = await client.whoami();
if (identity.type !== "project_api_key") {
  throw new Error("TOGETHER_API_KEY must be a project API key");
}
const projectId = identity.project.id;

const job = await client.models.remoteUploads.create({
  projectId,
  modelId: 'ml_abc123',
  remoteUrl: 'https://huggingface.co/your-org/your-adapter',
  token: 'hf_your_token',
});
console.log(job);

The response is the upload job object, with id, modelId, and status at the top level. Save the job id. You use it to poll for status.

Upload from the console

The console combines creating the adapter record and uploading its weights into a single form.

Set the upload type

Set Upload type to Adapter (LoRA).

Choose the source

Under Model source, select Import from Hugging Face and enter the repo path or URL (add a Hugging Face token for gated or private repos), or select Download from S3 and paste a presigned archive URL. Upload from your machine shows a CLI command instead, so use tg models upload for files on your machine.

Name and configure the adapter

Enter a Model name, choose a Visibility, and select the Compatible base model the adapter runs on top of.

Import

Select Import. The upload runs server-side, with progress shown below the form. You can leave the form: the adapter appears under My models with an Uploading badge while the job is pending or running.

Check upload status

Poll the remote-upload job until status is REMOTE_UPLOAD_STATUS_SUCCEEDED. The adapter is ready to deploy at that point.

# One upload job
tg models remote-uploads retrieve job_abc123

# All upload jobs in the project
tg models remote-uploads list

from together import Together

client = Together()
identity = client.whoami()
if identity.type != "project_api_key":
    raise RuntimeError("TOGETHER_API_KEY must be a project API key")
project_id = identity.project.id

# One upload job
job = client.models.remote_uploads.retrieve(
    "job_abc123",
    project_id=project_id,
)
print(job.status)

# All upload jobs in the project
jobs = client.models.remote_uploads.list(project_id=project_id)
print(jobs)

import Together from 'together-ai';

const client = new Together();
const identity = await client.whoami();
if (identity.type !== "project_api_key") {
  throw new Error("TOGETHER_API_KEY must be a project API key");
}
const projectId = identity.project.id;

// One upload job
const job = await client.models.remoteUploads.retrieve('job_abc123', {
  projectId,
});
console.log(job.status);

// All upload jobs in the project
const jobs = await client.models.remoteUploads.list({ projectId });
console.log(jobs);

Once the job reaches REMOTE_UPLOAD_STATUS_SUCCEEDED, confirm the files landed:

CLI

tg models ls-files ml_abc123

You can also track uploads on the My models page in the console. While a remote upload is pending or running, the adapter floats to the top of My models with an Uploading badge. Open the adapter to watch the live Upload progress event log on the model detail page. The revisions table appears after the upload finishes. That list also includes Internal-visibility adapters from other projects in your organization. Use the Visibility filter to show only Internal or only Private adapters.

Check revision validation

After files land, Together validates the revision’s weights automatically. Validation checks that the weights are in safetensors format and that the adapter is compatible with its base model. A revision must reach REVISION_VALIDATION_STATUS_SUCCESS before you can deploy it when you pin that revision explicitly. List revisions for an adapter:

CLI

tg models ls-revisions ml_abc123

The list and retrieve revision APIs also return validation fields on each revision. Replace $PROJECT_ID with your project ID (proj_...):

Shell

# All revisions
curl -s -H "Authorization: Bearer $TOGETHER_API_KEY" \
  "https://api.together.ai/v2/projects/$PROJECT_ID/models/ml_abc123/revisions"

# One revision
curl -s -H "Authorization: Bearer $TOGETHER_API_KEY" \
  "https://api.together.ai/v2/projects/$PROJECT_ID/models/ml_abc123/revisions/rv_abc123"

Each revision in the response includes:

{
  "data": [
    {
      "revisionId": "rv_abc123",
      "createdAt": "2026-07-02T20:05:00Z",
      "validationStatus": "REVISION_VALIDATION_STATUS_SUCCESS",
      "lastValidatedAt": "2026-07-02T20:06:00Z",
      "validationErrors": []
    }
  ],
  "object": "list"
}

Revision validation fields

Field	Description
`validationStatus`	Validation state for this revision. See the table below.
`lastValidatedAt`	When validation last ran for this revision. Omitted until validation has started.
`validationErrors`	Errors from the last validation run. Empty when validation succeeded or is still pending.

`validationStatus` values

Value	Meaning
`REVISION_VALIDATION_STATUS_PENDING`	Validation is queued or running. Poll until the status changes.
`REVISION_VALIDATION_STATUS_SUCCESS`	Weights validated successfully. The revision is ready to deploy.
`REVISION_VALIDATION_STATUS_FAILED`	Validation failed. Read `validationErrors` for the cause.
`REVISION_VALIDATION_STATUS_ERROR`	Validation could not complete due to an internal error. Retry later or contact support.
`REVISION_VALIDATION_STATUS_UNSPECIFIED`	Validation has not started yet.

When validation fails, each entry in validationErrors includes rule, severity, and message describing what went wrong.

Deploy the adapter

Once the upload completes, your adapter has a model ID (ml_...) in your project, linked to its base model. Deploy it the same way as a base model, using a config for its base model. The CLI’s deploy command creates the endpoint, attaches a deployment, and routes all traffic to it in one step. For an adapter, pass --merge, which deploys the adapter merged into its base model. The SDK has no single equivalent, so the Python and TypeScript samples run the same steps individually:

tg endpoints deploy ml_abc123 \
  --endpoint my-adapter \
  --merge \
  --config cr_CbzGdmn14t3HYrXXitmKa \
  --project your_project_id

from together import Together

client = Together()
identity = client.whoami()
if identity.type != "project_api_key":
    raise RuntimeError("TOGETHER_API_KEY must be a project API key")
project_id = identity.project.id

model = f"projects/{project_id}/models/ml_abc123"
config = f"projects/{project_id}/configs/cr_CbzGdmn14t3HYrXXitmKa"

# 1. Create the endpoint.
endpoint = client.endpoints.create(
    project_id=project_id,
    name="my-adapter",
)

# 2. Create a deployment bound to your adapter and config.
deployment = client.endpoints.deployments.create(
    endpoint.id,
    project_id=project_id,
    name="prod",
    model=model,
    config=config,
    autoscaling={"min_replicas": 1, "max_replicas": 1},
)

# 3. Route 100% of traffic to the deployment.
client.endpoints.update(
    endpoint.id,
    project_id=project_id,
    traffic_split=[{"deployment_id": deployment.id, "weight": 1}],
)
print(endpoint.name)

import Together from 'together-ai';

const client = new Together();
const identity = await client.whoami();
if (identity.type !== "project_api_key") {
  throw new Error("TOGETHER_API_KEY must be a project API key");
}
const projectId = identity.project.id;

const model = `projects/${projectId}/models/ml_abc123`;
const config = `projects/${projectId}/configs/cr_CbzGdmn14t3HYrXXitmKa`;

// 1. Create the endpoint.
const endpoint = await client.endpoints.create({
  projectId,
  name: 'my-adapter',
});

// 2. Create a deployment bound to your adapter and config.
const deployment = await client.endpoints.deployments.create(
  endpoint.id,
  {
    projectId,
    name: 'prod',
    model,
    config,
    autoscaling: { minReplicas: 1, maxReplicas: 1 },
  },
);

// 3. Route 100% of traffic to the deployment.
await client.endpoints.update(endpoint.id, {
  projectId,
  trafficSplit: [{ deploymentId: deployment.id, weight: 1 }],
});
console.log(endpoint.name);

See Manage deployments for the full deployment lifecycle.

Run inference

Once the deployment is READY and routable, call the endpoint by its endpoint string (<project_slug>/<endpoint_name>), the same as any other dedicated endpoint. Dedicated model inference is served at https://api-inference.together.ai:

curl -s -X POST https://api-inference.together.ai/v1/chat/completions \
  -H "Authorization: Bearer $TOGETHER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-project-slug/my-adapter",
    "messages": [{"role": "user", "content": "What is the capital of France?"}],
    "max_tokens": 128
  }' | jq .

from together import Together

client = Together(base_url="https://api-inference.together.ai")

response = client.chat.completions.create(
    model="your-project-slug/my-adapter",
    messages=[{"role": "user", "content": "What is the capital of France?"}],
    max_tokens=128,
)
print(response.choices[0].message.content)

import Together from 'together-ai';

const client = new Together({
  baseURL: 'https://api-inference.together.ai',
});

const response = await client.chat.completions.create({
  model: 'your-project-slug/my-adapter',
  messages: [{ role: 'user', content: 'What is the capital of France?' }],
  max_tokens: 128,
});
console.log(response.choices[0].message.content);

Troubleshooting

“Model name already exists”: Each uploaded adapter needs a unique name. Adapter versioning isn’t supported, so re-upload under a new name. “Model not found” during upload: Create the adapter record with tg models create --type adapter, then pass the returned id to the upload command. 401 or 403 during upload: For CLI uploads, run tg whoami to confirm you’re logged in. For SDK uploads, confirm that TOGETHER_API_KEY is set. If your Together AI credentials are valid, check that your Hugging Face token has permission for private repos, or that your S3 presigned URL is valid and hasn’t expired. Upload job stuck in Processing: The job usually can’t reach the source. For S3, confirm the presigned URL hasn’t expired. For Hugging Face, confirm your token has access to the repo. Missing required files: Confirm that both adapter_config.json and adapter_model.safetensors are at the root of your S3 archive, or in the repo’s Files and versions tab on Hugging Face. Base model incompatibility: Confirm that the base model you trained the adapter against is one of the supported models for dedicated model inference. Adapter delete fails with the model is referenced by a live deployment (HTTP 400): A deployment still references this adapter. Stop the deployment, wait for DEPLOYMENT_STATE_STOPPED, delete the deployment, then delete the adapter with tg models rm <adapter_id>.

GET STARTED

SERVERLESS

INFERENCE APIS

DEDICATED MODEL INFERENCE

DEDICATED CONTAINER INFERENCE

POST-TRAINING

FINE-TUNING

GPU CLUSTERS

CODE EXECUTION

ADMINISTRATION

Requirements

Create the adapter

Create request fields

Upload the adapter

Upload from your machine

Upload from Hugging Face or S3

Upload from the console

Check upload status

Check revision validation

Revision validation fields

`validationStatus` values

Deploy the adapter

Run inference

Troubleshooting

​Requirements

​Create the adapter

​Create request fields

​Upload the adapter

​Upload from your machine

​Upload from Hugging Face or S3

​Upload from the console

​Check upload status

​Check revision validation

​Revision validation fields

​validationStatus values

​Deploy the adapter

​Run inference

​Troubleshooting

Requirements

Create the adapter

Create request fields

Upload the adapter

Upload from your machine

Upload from Hugging Face or S3

Upload from the console

Check upload status

Check revision validation

Revision validation fields

`validationStatus` values

Deploy the adapter

Run inference

Troubleshooting