---
title: "Create a training"
method: POST
path: "/models/{model_owner}/{model_name}/versions/{version_id}/trainings"
---

# Create a training

`POST /models/{model_owner}/{model_name}/versions/{version_id}/trainings`

Start a new training of the model version you specify.

Example request body:

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

Example cURL request:

```console
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:

```json
{
  "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](#trainings.get) endpoint until it has finished.

When a training completes, it creates a new [version](https://replicate.com/docs/how-does-replicate-work#terminology) of the model at the specified destination.

To find some models to train on, check out the [trainable language models collection](https://replicate.com/collections/trainable-language-models).

## Path parameters

- `model_owner` string, required
- `model_name` string, required
- `version_id` string, required

## Request body

- SchemasTrainingRequest
  - `destination` string, required — A string representing the desired model to push to in the format `{destination_model_owner}/{destination_model_name}`. This should be an existing model owned by the user or organization making the API request. If the destination is invalid, the server will return an appropriate 4XX response.
  - `input` object, required — An object containing inputs to the Cog model's `train()` function.
  - `webhook` string — An HTTPS URL for receiving a webhook when the training completes. The webhook will be a POST request where the request body is the same as the response body of the [get training](#trainings.get) operation. If there are network problems, we will retry the webhook a few times, so make sure it can be safely called more than once. Replicate will not follow redirects when sending webhook requests to your service, so be sure to specify a URL that will resolve without redirecting.
  - `webhook_events_filter` string[] — By default, we will send requests to your webhook URL whenever there are new outputs or the training has finished. You can change which events trigger webhook requests by specifying `webhook_events_filter` in the training request: - `start`: immediately on training start - `output`: each time a training generates an output (note that trainings can generate multiple outputs) - `logs`: each time log output is generated by a training - `completed`: when the training reaches a terminal state (succeeded/canceled/failed) For example, if you only wanted requests to be sent at the start and end of the training, you would provide: ```json { "destination": "my-organization/my-model", "input": { "text": "Alice" }, "webhook": "https://example.com/my-webhook", "webhook_events_filter": ["start", "completed"] } ``` Requests for event types `output` and `logs` will be sent at most once every 500ms. If you request `start` and `completed` webhooks, then they'll always be sent regardless of throttling.

## Response `201`

Success

- SchemasTrainingResponse
  - `completed_at` string, date-time — The time when the training completed
  - `created_at` string, date-time — The time when the training was created
  - `error` string, nullable — Error message if the training failed
  - `id` string — The unique ID of the training
  - `input` object — The input parameters used for the training
  - `logs` string — The logs from the training process
  - `metrics` object — Metrics about the training process
    - `predict_time` number — The amount of CPU or GPU time, in seconds, that the training used while running
    - `total_time` number — The total time, in seconds, that the training took to complete
  - `model` string — The name of the model in the format owner/name
  - `output` object — The output of the training process
    - `version` string — The version of the model created by the training
    - `weights` string — The weights of the trained model
  - `source` 'web' | 'api' — How the training was created
  - `started_at` string, date-time — The time when the training started
  - `status` 'starting' | 'processing' | 'succeeded' | 'failed' | 'canceled' — The current status of the training
  - `urls` object — URLs for interacting with the training
    - `cancel` string, uri — URL to cancel the training
    - `get` string, uri — URL to get the training details
  - `version` string — The ID of the model version used for training

## Changes

- **2025-10-07** `8b68f03c8602` — 1 info
  - added the optional property `metrics/total_time` to the response with the `201` status
- **2025-04-16** `2788217b7ad7` — 1 info
  - added the media type `application/json` for the response with the status `201`

[Change history](https://skmtc.dev/replicate/apis/replicate-http-api/changes/models/:model_owner/:model_name/versions/:version_id/trainings/post.md)

---

[API](https://skmtc.dev/replicate/apis/replicate-http-api.md) · [All operations](https://skmtc.dev/replicate/apis/replicate-http-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/replicate/replicate-http-api/revisions/7a537f433b0b/schema)