---
title: "Start training a model"
method: POST
path: "/training/start"
tags: ["training"]
---

# Start training a model

`POST /training/start`

## Request

- The document declares no server URL.
- Auth: none required

Start training an ACT or gr00t model on the specified dataset. This will upload a trained model to the Hugging Face Hub using the main branch of the specified dataset.

## Request body

- TrainingRequest: Pydantic model for training request validation. This version consolidates all model name and parameter logic into a single validator to prevent redundant operations and fix the duplicate suffix bug.
  - `dataset_name` string, required: Dataset repository ID on Hugging Face, should be a public dataset
  - `model_name` string, nullable: Name of the trained model to upload to Hugging Face, should be in the format phospho-app/<model_name> or <model_name>
  - `model_type` 'ACT' | 'ACT_BBOX' | 'gr00t' | 'pi0' | 'custom', required: Type of model to train, supports 'ACT', 'gr00t', and 'pi0'
  - `private_mode` boolean: Whether to use private training (PRO users only)
  - `training_params` union: Training parameters for the model.
    - TrainingParamsAct: Training parameters are left to None by default and are set depending on the dataset in the training pipeline.
      - `batch_size` integer, nullable: Batch size for training, we run this on an A10G. Leave it to None to auto-detect based on your dataset
      - `save_freq` integer: Number of steps between saving the model.
      - `steps` integer, nullable: Number of training steps. Leave it to None to auto-detect based on your dataset
    - TrainingParamsActWithBbox: Training parameters for ACT with bounding box
      - `batch_size` integer, nullable: Batch size for training, we run this on an A10G. Leave it to None to auto-detect based on your dataset
      - `image_key` string: Key for the image to run detection on, e.g. 'main' or 'images.main'
      - `image_keys_to_keep` string[]: Optional list of image keys to keep. If none, all image keys will be dropped.
      - `save_freq` integer: Number of steps between saving the model.
      - `steps` integer, nullable: Number of training steps. Leave it to None to auto-detect based on your dataset
      - `target_detection_instruction` string: Instruction for the target object to detect, e.g. 'red/orange lego brick'
    - TrainingParamsGr00T
      - `batch_size` integer, nullable: Batch size for training. Decrease it if you get an Out Of Memory (OOM) error
      - `data_dir` string: The directory to save the dataset to
      - `learning_rate` number: Learning rate for training.
      - `num_epochs` integer: Number of epochs to train for.
      - `output_dir` string: The directory to save the model to
      - `save_steps` integer: Number of steps between saving the model.
      - `validation_data_dir` string, nullable: Optional directory to save the validation dataset to. If None, validation is not run.
      - `validation_dataset_name` string, nullable: Optional dataset repository ID on Hugging Face to use for validation
    - TrainingParamsPi0: Training parameters for Pi0 model
      - `batch_size` integer, nullable: Batch size for training, leave it to None to auto-detect based on your dataset
      - `data_dir` string: The directory to save the dataset to
      - `epochs` integer: Number of epochs to train for, default is 10
      - `learning_rate` number: Learning rate for training, default is 0.0001
      - `output_dir` string: The directory to save the model to
      - `path_to_pi0_repo` string: The path to the openpi repo. If not provided, will assume we are in the repo.
      - `train_test_split` number: Train test split ratio, default is 1.0 (no split), should be between 0 and 1
      - `validation_dataset_name` string, nullable: Optional dataset repository ID on Hugging Face to use for validation
  - `user_hf_token` string, nullable: User's personal HF token for private training
  - `wandb_api_key` string, nullable: WandB API key for tracking training, you can find it at https://wandb.ai/authorize

## Response `200`

Successful Response

- StartTrainingResponse
  - `message` string, nullable
  - `model_url` string, nullable: URL to the Hugging Face model card.
  - `status` 'ok' | 'error'
  - `training_id` integer, nullable, required: ID of the training to start. This is the ID returned by the training request.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/phospho/apis/phospho-api.md) - [All operations](https://skmtc.dev/phospho/apis/phospho-api/llms.txt) - [OpenAPI document](https://skmtc.dev/phospho/apis/phospho-api/revisions/93e83588fc02?raw)