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

# Start Training

> Queue a LoRA training run on any trainer.

Starts a LoRA training run. `trainer_id` picks the trainer, and each trainer takes its own fields. Pick your trainer in the **Body** tabs below for a ready-to-send request. The parameter list describes every field; switch its body type to your trainer.

## Request

Make a `POST` request to the endpoint below with the required parameters.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
POST https://modelslab.com/api/v6/trainer/train
```

### Body

> [tab] Flux LoRA
>
> Trains a LoRA for Flux Dev. Ready to generate with on ModelsLab after training.
>
> ```json json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
>     "key": "your_api_key",
>     "trainer_id": "flux_lora_trainer",
>     "images": [
>         "https://raw.githubusercontent.com/pnavitha/sampleImages/master/1.png",
>         "https://raw.githubusercontent.com/pnavitha/sampleImages/master/2.png",
>         "https://raw.githubusercontent.com/pnavitha/sampleImages/master/3.png",
>         "https://raw.githubusercontent.com/pnavitha/sampleImages/master/4.png",
>         "https://raw.githubusercontent.com/pnavitha/sampleImages/master/5.png"
>     ],
>     "trigger_word": "pinkpanda",
>     "hf_username": "your_hf_username",
>     "hf_token": "hf_your_write_token",
>     "training_steps": 750,
>     "resolution": 1024
> }
> ```

> [tab] Z-Image Turbo
>
> Needs `training_id`: the name of the Hugging Face repo the LoRA is uploaded to. Use at least 15 images for a good result. Ready to generate with on ModelsLab after training.
>
> ```json json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
>     "key": "your_api_key",
>     "trainer_id": "z-image-turbo-lora-trainer",
>     "images": [
>         "https://raw.githubusercontent.com/pnavitha/sampleImages/master/1.png",
>         "https://raw.githubusercontent.com/pnavitha/sampleImages/master/2.png",
>         "https://raw.githubusercontent.com/pnavitha/sampleImages/master/3.png",
>         "https://raw.githubusercontent.com/pnavitha/sampleImages/master/4.png",
>         "https://raw.githubusercontent.com/pnavitha/sampleImages/master/5.png"
>     ],
>     "trigger_word": "pinkpanda",
>     "hf_username": "your_hf_username",
>     "hf_token": "hf_your_write_token",
>     "training_id": "my-pinkpanda-lora",
>     "training_steps": 750,
>     "resolution": 1024
> }
> ```

> [tab] Stable Diffusion
>
> Uses `instance_prompt` instead of `trigger_word`. Set `base_model_type` to `sdxl` (1024 resolution) or `sd15` (512 resolution). Ready to generate with on ModelsLab after training.
>
> ```json json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
>     "key": "your_api_key",
>     "trainer_id": "sd-trainer",
>     "images": [
>         "https://raw.githubusercontent.com/pnavitha/sampleImages/master/1.png",
>         "https://raw.githubusercontent.com/pnavitha/sampleImages/master/2.png",
>         "https://raw.githubusercontent.com/pnavitha/sampleImages/master/3.png",
>         "https://raw.githubusercontent.com/pnavitha/sampleImages/master/4.png",
>         "https://raw.githubusercontent.com/pnavitha/sampleImages/master/5.png"
>     ],
>     "instance_prompt": "photo of sks man",
>     "hf_username": "your_hf_username",
>     "hf_token": "hf_your_write_token",
>     "base_model_type": "sdxl",
>     "training_steps": 750,
>     "resolution": 1024,
>     "seed": 298329,
>     "batch_size": 4,
>     "mixed_precision": "fp16",
>     "rank": 4,
>     "alpha": 2,
>     "learning_rate": 0.0001
> }
> ```

> [tab] FLUX.2 Klein 9B
>
> Needs `training_id`: the name of the Hugging Face repo the LoRA is uploaded to. Use at least 15 images for a good result. The LoRA is uploaded to your Hugging Face repo; it is not loaded for inference on ModelsLab.
>
> ```json json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
>     "key": "your_api_key",
>     "trainer_id": "flux2-klein-9b-lora-trainer",
>     "images": [
>         "https://raw.githubusercontent.com/pnavitha/sampleImages/master/1.png",
>         "https://raw.githubusercontent.com/pnavitha/sampleImages/master/2.png",
>         "https://raw.githubusercontent.com/pnavitha/sampleImages/master/3.png",
>         "https://raw.githubusercontent.com/pnavitha/sampleImages/master/4.png",
>         "https://raw.githubusercontent.com/pnavitha/sampleImages/master/5.png"
>     ],
>     "trigger_word": "pinkpanda",
>     "hf_username": "your_hf_username",
>     "hf_token": "hf_your_write_token",
>     "training_id": "my-pinkpanda-lora",
>     "training_steps": 750,
>     "resolution": 1024
> }
> ```

> [tab] FLUX.3 Klein
>
> Needs `training_id`: the name of the Hugging Face repo the LoRA is uploaded to. Use at least 15 images for a good result. The LoRA is uploaded to your Hugging Face repo; it is not loaded for inference on ModelsLab.
>
> ```json json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
>     "key": "your_api_key",
>     "trainer_id": "flux3-klein-lora-trainer",
>     "images": [
>         "https://raw.githubusercontent.com/pnavitha/sampleImages/master/1.png",
>         "https://raw.githubusercontent.com/pnavitha/sampleImages/master/2.png",
>         "https://raw.githubusercontent.com/pnavitha/sampleImages/master/3.png",
>         "https://raw.githubusercontent.com/pnavitha/sampleImages/master/4.png",
>         "https://raw.githubusercontent.com/pnavitha/sampleImages/master/5.png"
>     ],
>     "trigger_word": "pinkpanda",
>     "hf_username": "your_hf_username",
>     "hf_token": "hf_your_write_token",
>     "training_id": "my-pinkpanda-lora",
>     "training_steps": 750,
>     "resolution": 1024
> }
> ```

> [tab] MOSS Image
>
> Uses `instance_prompt` instead of `trigger_word`. `learning_rate` goes up to 0.01. The LoRA is uploaded to your Hugging Face repo; it is not loaded for inference on ModelsLab.
>
> ```json json theme={"theme":{"light":"github-light","dark":"github-dark"}}
> {
>     "key": "your_api_key",
>     "trainer_id": "moss-image-lora-trainer",
>     "images": [
>         "https://raw.githubusercontent.com/pnavitha/sampleImages/master/1.png",
>         "https://raw.githubusercontent.com/pnavitha/sampleImages/master/2.png",
>         "https://raw.githubusercontent.com/pnavitha/sampleImages/master/3.png",
>         "https://raw.githubusercontent.com/pnavitha/sampleImages/master/4.png",
>         "https://raw.githubusercontent.com/pnavitha/sampleImages/master/5.png"
>     ],
>     "instance_prompt": "photo of sks man",
>     "hf_username": "your_hf_username",
>     "hf_token": "hf_your_write_token",
>     "training_steps": 750,
>     "resolution": 1024,
>     "seed": 298329,
>     "batch_size": 4,
>     "mixed_precision": "fp16",
>     "rank": 4,
>     "alpha": 2,
>     "learning_rate": 0.005
> }
> ```

## Response

A new run is always queued first. Keep the `id`: you need it to check the status or stop the run.

```json json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
    "status": "success",
    "message": "Training request is being processed",
    "data": {
        "status": "pending",
        "id": "9b2f6c1e-4d3a-4f8e-a1b2-3c4d5e6f7a8b",
        "meta": {
            "trainer_id": "flux_lora_trainer",
            "images": ["https://raw.githubusercontent.com/pnavitha/sampleImages/master/1.png"],
            "trigger_word": "pinkpanda",
            "hf_username": "your_hf_username",
            "training_steps": 750
        }
    },
    "id": "9b2f6c1e-4d3a-4f8e-a1b2-3c4d5e6f7a8b",
    "fetch_result": "https://modelslab.com/api/v6/trainer/status/9b2f6c1e-4d3a-4f8e-a1b2-3c4d5e6f7a8b"
}
```

## Errors

Errors come back with HTTP 200 and `"status": "error"`.

| Message | What to do |
| :- | :- |
| `Invalid trainer ID` | Use one of the `trainer_id` values from the [trainers table](https://docs.modelslab.com/image-generation/train-model/overview.md#trainers). |
| `Insufficient funds. Please top up your wallet to proceed with training.` | Add at least one hour of training to your wallet. |
| `code: validation_error` | `errors` lists each field that is wrong, for example an image URL that could not be downloaded or an invalid Hugging Face token. |


## OpenAPI

````yaml image-generation/train-model/openapi.json POST /train
openapi: 3.1.0
info:
  title: ModelsLab Train Model API
  description: >-
    Train your own LoRA on Flux, FLUX.2 Klein 9B, FLUX.3 Klein, Z-Image Turbo,
    Stable Diffusion (SDXL / SD 1.5) and MOSS Image, then check its progress or
    stop it.
  license:
    name: MIT
  version: 6.0.0
servers:
  - url: https://modelslab.com/api/v6/trainer
    description: LoRA training endpoints
security: []
paths:
  /train:
    post:
      summary: Start Training
      description: >-
        Queues a LoRA training run on the trainer named by `trainer_id`. Each
        trainer takes its own set of fields; pick one of the request shapes
        below.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/FluxLoraTrainRequest'
                - $ref: '#/components/schemas/Flux2Klein9bTrainRequest'
                - $ref: '#/components/schemas/Flux3KleinTrainRequest'
                - $ref: '#/components/schemas/ZImageTurboTrainRequest'
                - $ref: '#/components/schemas/StableDiffusionTrainRequest'
                - $ref: '#/components/schemas/MossImageTrainRequest'
      responses:
        '200':
          description: The run was queued, or an error describing why it was not.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/TrainSuccessResponse'
                  - $ref: '#/components/schemas/ValidationErrorResponse'
                  - $ref: '#/components/schemas/ErrorResponse'
        '400':
          $ref: '#/components/responses/StandardErrorResponse'
        '401':
          $ref: '#/components/responses/StandardErrorResponse'
        '500':
          $ref: '#/components/responses/StandardErrorResponse'
components:
  schemas:
    FluxLoraTrainRequest:
      title: Flux LoRA
      type: object
      required:
        - key
        - trainer_id
        - images
        - trigger_word
        - hf_username
        - hf_token
      properties:
        key:
          $ref: '#/components/schemas/Key'
        trainer_id:
          type: string
          enum:
            - flux_lora_trainer
          description: Selects the Flux LoRA trainer.
        images:
          $ref: '#/components/schemas/Images'
        trigger_word:
          $ref: '#/components/schemas/TriggerWord'
        hf_username:
          $ref: '#/components/schemas/HfUsername'
        hf_token:
          $ref: '#/components/schemas/HfToken'
        training_steps:
          allOf:
            - $ref: '#/components/schemas/TrainingSteps'
          minimum: 1
          examples:
            - 1000
        resolution:
          $ref: '#/components/schemas/Resolution'
    Flux2Klein9bTrainRequest:
      title: FLUX.2 Klein 9B LoRA
      type: object
      required:
        - key
        - trainer_id
        - images
        - trigger_word
        - hf_username
        - hf_token
        - training_id
      properties:
        key:
          $ref: '#/components/schemas/Key'
        trainer_id:
          type: string
          enum:
            - flux2-klein-9b-lora-trainer
          description: Selects the FLUX.2 Klein 9B LoRA trainer.
        images:
          $ref: '#/components/schemas/Images'
        trigger_word:
          $ref: '#/components/schemas/TriggerWord'
        hf_username:
          $ref: '#/components/schemas/HfUsername'
        hf_token:
          $ref: '#/components/schemas/HfToken'
        training_id:
          $ref: '#/components/schemas/RepoName'
        training_steps:
          allOf:
            - $ref: '#/components/schemas/TrainingSteps'
          minimum: 500
          examples:
            - 2000
        resolution:
          $ref: '#/components/schemas/Resolution'
    Flux3KleinTrainRequest:
      title: FLUX.3 Klein LoRA
      type: object
      required:
        - key
        - trainer_id
        - images
        - trigger_word
        - hf_username
        - hf_token
        - training_id
      properties:
        key:
          $ref: '#/components/schemas/Key'
        trainer_id:
          type: string
          enum:
            - flux3-klein-lora-trainer
          description: Selects the FLUX.3 Klein LoRA trainer.
        images:
          $ref: '#/components/schemas/Images'
        trigger_word:
          $ref: '#/components/schemas/TriggerWord'
        hf_username:
          $ref: '#/components/schemas/HfUsername'
        hf_token:
          $ref: '#/components/schemas/HfToken'
        training_id:
          $ref: '#/components/schemas/RepoName'
        training_steps:
          allOf:
            - $ref: '#/components/schemas/TrainingSteps'
          minimum: 500
          examples:
            - 2000
        resolution:
          $ref: '#/components/schemas/Resolution'
    ZImageTurboTrainRequest:
      title: Z-Image Turbo LoRA
      type: object
      required:
        - key
        - trainer_id
        - images
        - trigger_word
        - hf_username
        - hf_token
        - training_id
      properties:
        key:
          $ref: '#/components/schemas/Key'
        trainer_id:
          type: string
          enum:
            - z-image-turbo-lora-trainer
          description: Selects the Z-Image Turbo LoRA trainer.
        images:
          $ref: '#/components/schemas/Images'
        trigger_word:
          $ref: '#/components/schemas/TriggerWord'
        hf_username:
          $ref: '#/components/schemas/HfUsername'
        hf_token:
          $ref: '#/components/schemas/HfToken'
        training_id:
          $ref: '#/components/schemas/RepoName'
        training_steps:
          allOf:
            - $ref: '#/components/schemas/TrainingSteps'
          minimum: 500
          examples:
            - 2000
        resolution:
          $ref: '#/components/schemas/Resolution'
    StableDiffusionTrainRequest:
      title: Stable Diffusion (SDXL / SD 1.5) LoRA
      type: object
      required:
        - key
        - trainer_id
        - images
        - instance_prompt
        - hf_username
        - hf_token
      properties:
        key:
          $ref: '#/components/schemas/Key'
        trainer_id:
          type: string
          enum:
            - sd-trainer
          description: Selects the Stable Diffusion LoRA trainer.
        images:
          $ref: '#/components/schemas/Images'
        instance_prompt:
          type: string
          maxLength: 2000
          description: >-
            A prompt describing your subject with a unique token, e.g. `photo of
            sks man`. Use the same phrase in prompts when you generate.
        hf_username:
          $ref: '#/components/schemas/HfUsername'
        hf_token:
          $ref: '#/components/schemas/HfToken'
        base_model_type:
          type: string
          enum:
            - sdxl
            - sd15
          default: sdxl
          description: '`sdxl` trains an SDXL LoRA. Any other value trains an SD 1.5 LoRA.'
        training_steps:
          allOf:
            - $ref: '#/components/schemas/TrainingSteps'
          examples:
            - 1500
        resolution:
          type: integer
          minimum: 512
          maximum: 1024
          examples:
            - 1024
          description: >-
            Resolution the images are trained at. Use 1024 for SDXL and 512 for
            SD 1.5.
        seed:
          type: integer
          maximum: 999999
          description: Random seed, for reproducible runs.
        batch_size:
          type: integer
          minimum: 1
          maximum: 128
          examples:
            - 4
          description: Images processed per step.
        mixed_precision:
          type: string
          enum:
            - fp16
          description: Training precision.
        rank:
          type: integer
          minimum: 1
          maximum: 512
          examples:
            - 4
          description: LoRA rank. Higher learns more detail and makes a larger file.
        alpha:
          type: integer
          minimum: 1
          maximum: 1024
          examples:
            - 2
          description: LoRA alpha (scaling). Usually half of `rank` or equal to it.
        learning_rate:
          type: number
          maximum: 1
          examples:
            - 0.0001
          description: Learning rate.
    MossImageTrainRequest:
      title: MOSS Image LoRA
      type: object
      required:
        - key
        - trainer_id
        - images
        - instance_prompt
        - hf_username
        - hf_token
      properties:
        key:
          $ref: '#/components/schemas/Key'
        trainer_id:
          type: string
          enum:
            - moss-image-lora-trainer
          description: Selects the MOSS Image LoRA trainer.
        images:
          $ref: '#/components/schemas/Images'
        instance_prompt:
          type: string
          maxLength: 2000
          description: >-
            A prompt describing your subject with a unique token, e.g. `photo of
            sks man`.
        hf_username:
          $ref: '#/components/schemas/HfUsername'
        hf_token:
          $ref: '#/components/schemas/HfToken'
        training_steps:
          allOf:
            - $ref: '#/components/schemas/TrainingSteps'
          examples:
            - 1500
        resolution:
          type: integer
          minimum: 512
          maximum: 1024
          examples:
            - 1024
          description: Resolution the images are trained at.
        seed:
          type: integer
          maximum: 999999
          description: Random seed, for reproducible runs.
        batch_size:
          type: integer
          minimum: 1
          maximum: 128
          examples:
            - 4
          description: Images processed per step.
        mixed_precision:
          type: string
          enum:
            - fp16
          description: Training precision.
        rank:
          type: integer
          minimum: 1
          maximum: 512
          examples:
            - 4
          description: LoRA rank.
        alpha:
          type: integer
          minimum: 1
          maximum: 1024
          examples:
            - 2
          description: LoRA alpha (scaling).
        learning_rate:
          type: number
          maximum: 0.01
          examples:
            - 0.005
          description: Learning rate.
    TrainSuccessResponse:
      type: object
      properties:
        status:
          type: string
          enum:
            - success
        message:
          type: string
          examples:
            - Training request is being processed
        data:
          type: object
          properties:
            status:
              type: string
              enum:
                - pending
              description: Every new run starts queued.
            id:
              type: string
              format: uuid
            meta:
              type: object
              additionalProperties: true
              description: The fields you sent, without your Hugging Face token.
        id:
          type: string
          format: uuid
          description: The training ID. Use it to check status or stop the run.
        fetch_result:
          type: string
          format: uri
          description: The status URL for this run.
    ValidationErrorResponse:
      type: object
      properties:
        status:
          type: string
          enum:
            - error
        code:
          type: string
          enum:
            - validation_error
        message:
          type: string
        errors:
          type: object
          description: Field names mapped to what is wrong with them.
          additionalProperties:
            type: array
            items:
              type: string
    ErrorResponse:
      type: object
      required:
        - status
        - message
      properties:
        status:
          type: string
          enum:
            - error
        message:
          type: string
    Key:
      type: string
      description: Your API key. Get one from https://modelslab.com/dashboard/api-keys.
    Images:
      type: array
      description: >-
        Public URLs of your training images, 1 to 100 of them. Every URL is
        downloaded before the run starts; one that needs a login or does not
        return an image fails the request.
      minItems: 1
      maxItems: 100
      items:
        type: string
        format: uri
    TriggerWord:
      type: string
      maxLength: 50
      pattern: ^[\p{L}\p{M}\p{N} _.\-]+$
      description: >-
        A unique word you put in prompts to call up what the LoRA learned.
        Letters, numbers, spaces, `_`, `.` and `-` only.
    HfUsername:
      type: string
      minLength: 3
      maxLength: 50
      description: >-
        Your Hugging Face username. The trained LoRA is uploaded to a repo under
        this account.
    HfToken:
      type: string
      minLength: 10
      description: >-
        A Hugging Face access token (starts with `hf_`) with **write** access,
        so the trainer can create the repo and upload your LoRA.
    TrainingSteps:
      type: integer
      maximum: 2000
      description: >-
        How many steps to train for. A good starting point is 100 to 150 steps
        per image. Values above 2000 are trained at 2000.
    Resolution:
      type: integer
      minimum: 520
      maximum: 1024
      default: 1024
      description: Resolution the images are trained at.
    RepoName:
      type: string
      maxLength: 96
      pattern: ^[A-Za-z0-9]+(-[A-Za-z0-9]+)*$
      description: >-
        Name of the Hugging Face repo the LoRA is uploaded to, e.g.
        `my-product-lora`. Letters, numbers and single hyphens only, with no
        hyphen at the start or end.
  responses:
    StandardErrorResponse:
      description: Error response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'

````

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