Documentation | Trainings

{
  "destination": "{new_owner}/{new_name}",
  "input": {
    "train_data": "https://example.com/my-input-images.zip",
  },
  "webhook": "https://example.com/my-webhook",
}

Example cURL request:

curl -s -X POST \
  -d '{"destination": "{new_owner}/{new_name}", "input": {"input_images": "https://example.com/my-input-images.zip"}}' \
  -H "Authorization: Bearer $REPLICATE_API_TOKEN" \
  -H 'Content-Type: application/json' \
  https://api.replicate.com/v1/models/stability-ai/sdxl/versions/da77bc59ee60423279fd632efb4795ab731d9e3ca9705ef3341091fb989b7eaf/trainings

The response will be the training object:

{
  "id": "zz4ibbonubfz7carwiefibzgga",
  "model": "stability-ai/sdxl",
  "version": "da77bc59ee60423279fd632efb4795ab731d9e3ca9705ef3341091fb989b7eaf",
  "input": {
    "input_images": "https://example.com/my-input-images.zip"
  },
  "logs": "",
  "error": null,
  "status": "starting",
  "created_at": "2023-09-08T16:32:56.990893084Z",
  "urls": {
    "web": "https://replicate.com/p/zz4ibbonubfz7carwiefibzgga",
     "get": "https://api.replicate.com/v1/predictions/zz4ibbonubfz7carwiefibzgga",
     "cancel": "https://api.replicate.com/v1/predictions/zz4ibbonubfz7carwiefibzgga/cancel"
  }
}

As models can take several minutes or more to train, the result will not be available immediately. To get the final result of the training you should either provide a webhook HTTPS URL for us to call when the results are ready, or poll the get a training endpoint until it has finished.

When a training completes, it creates a new version of the model at the specified destination.

To find some models to train on, check out the trainable language models collection.

client.trainings.list() -> SyncCursorURLPage[

TrainingListResponse

]

get/trainings

Get a paginated list of all trainings created by the user or organization associated with the provided API token.

This will include trainings created from the API and the website. It will return 100 records per page.

Example cURL request:

curl -s \
  -H "Authorization: Bearer $REPLICATE_API_TOKEN" \
  https://api.replicate.com/v1/trainings

The response will be a paginated JSON array of training objects, sorted with the most recent training first:

{
  "next": null,
  "previous": null,
  "results": [
    {
      "completed_at": "2023-09-08T16:41:19.826523Z",
      "created_at": "2023-09-08T16:32:57.018467Z",
      "error": null,
      "id": "zz4ibbonubfz7carwiefibzgga",
      "input": {
        "input_images": "https://example.com/my-input-images.zip"
      },
      "metrics": {
        "predict_time": 502.713876
      },
      "output": {
        "version": "...",
        "weights": "..."
      },
      "started_at": "2023-09-08T16:32:57.112647Z",
      "source": "api",
      "status": "succeeded",
      "urls": {
        "web": "https://replicate.com/p/zz4ibbonubfz7carwiefibzgga",
        "get": "https://api.replicate.com/v1/trainings/zz4ibbonubfz7carwiefibzgga",
        "cancel": "https://api.replicate.com/v1/trainings/zz4ibbonubfz7carwiefibzgga/cancel"
      },
      "model": "stability-ai/sdxl",
      "version": "da77bc59ee60423279fd632efb4795ab731d9e3ca9705ef3341091fb989b7eaf",
    }
  ]
}

id will be the unique ID of the training.

source will indicate how the training was created. Possible values are web or api.

status will be the status of the training. Refer to get a single training for possible values.

urls will be a convenience object that can be used to construct new API requests for the given training.

version will be the unique ID of model version used to create the training.

Returns

class TrainingListResponse:

id: Optional[str]

The unique ID of the training

completed_at: Optional[datetime]

(format: date-time)

The time when the training completed

created_at: Optional[datetime]

(format: date-time)

The time when the training was created

error: Optional[str]

Error message if the training failed

input: Optional[Dict[str,

object

]]

The input parameters used for the training

logs: Optional[str]

The logs from the training process

metrics: Optional[

Metrics

]

Metrics about the training process

model: Optional[str]

The name of the model in the format owner/name

output: Optional[

Output

]

The output of the training process

source: Optional[Literal["web", "api"]]

How the training was created

started_at: Optional[datetime]

(format: date-time)

The time when the training started

status: Optional[Literal["starting", "processing", "succeeded", "failed", "canceled"]]

The current status of the training

urls: Optional[

URLs

]

URLs for interacting with the training

version: Optional[str]

The ID of the model version used for training

Request example

from replicate import Replicate

replicate = Replicate(
    bearer_token="My Bearer Token",
)
page = replicate.trainings.list()
page = page.results[0]
print(page.id)

200Example

{
  "next": "next",
  "previous": "previous",
  "results": [
    {
      "id": "id",
      "completed_at": "2019-12-27T18:11:19.117Z",
      "created_at": "2019-12-27T18:11:19.117Z",
      "error": "error",
      "input": {
        "foo": "bar"
      },
      "logs": "logs",
      "metrics": {
        "predict_time": 0,
        "total_time": 0
      },
      "model": "model",
      "output": {
        "version": "version",
        "weights": "weights"
      },
      "source": "web",
      "started_at": "2019-12-27T18:11:19.117Z",
      "status": "starting",
      "urls": {
        "cancel": "https://example.com",
        "get": "https://example.com"
      },
      "version": "version"
    }
  ]
}

client.trainings.get() ->

TrainingGetResponse

get/trainings/{training_id}

Get the current state of a training.

Example cURL request:

curl -s \
  -H "Authorization: Bearer $REPLICATE_API_TOKEN" \
  https://api.replicate.com/v1/trainings/zz4ibbonubfz7carwiefibzgga

The response will be the training object:

{
  "completed_at": "2023-09-08T16:41:19.826523Z",
  "created_at": "2023-09-08T16:32:57.018467Z",
  "error": null,
  "id": "zz4ibbonubfz7carwiefibzgga",
  "input": {
    "input_images": "https://example.com/my-input-images.zip"
  },
  "logs": "...",
  "metrics": {
    "predict_time": 502.713876
  },
  "output": {
    "version": "...",
    "weights": "..."
  },
  "started_at": "2023-09-08T16:32:57.112647Z",
  "status": "succeeded",
  "urls": {
    "web": "https://replicate.com/p/zz4ibbonubfz7carwiefibzgga",
    "get": "https://api.replicate.com/v1/trainings/zz4ibbonubfz7carwiefibzgga",
    "cancel": "https://api.replicate.com/v1/trainings/zz4ibbonubfz7carwiefibzgga/cancel"
  },
  "model": "stability-ai/sdxl",
  "version": "da77bc59ee60423279fd632efb4795ab731d9e3ca9705ef3341091fb989b7eaf",
}

status will be one of:

starting: the training is starting up. If this status lasts longer than a few seconds, then it's typically because a new worker is being started to run the training.
processing: the train() method of the model is currently running.
succeeded: the training completed successfully.
failed: the training encountered an error during processing.
canceled: the training was canceled by its creator.

In the case of success, output will be an object containing the output of the model. Any files will be represented as HTTPS URLs. You'll need to pass the Authorization header to request them.

In the case of failure, error will contain the error encountered during the training.

Terminated trainings (with a status of succeeded, failed, or canceled) will include a metrics object with a predict_time property showing the amount of CPU or GPU time, in seconds, that the training used while running. It won't include time waiting for the training to start. The metrics object will also include a total_time property showing the total time, in seconds, that the training took to complete.

client.trainings.cancel() ->

TrainingCancelResponse

post/trainings/{training_id}/cancel

Cancel a training