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

# Start training a model

`POST /training/start`

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/fastapi.md) · [All operations](https://skmtc.dev/phospho/apis/fastapi/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/phospho/fastapi/revisions/93e83588fc02/schema)