Modaicmodaic % docs

Search Modaic documentation

Find a Modaic guide or API reference

Reference›API›Fine-tuning

Create fine-tune job

Start a fine-tuning job. Returns 202 Accepted.

POST/v1/fine-tunes

Authorization

Authorizationstringrequired

Send a Modaic bearer token in the Authorization header.

Headers

Idempotency-Keystring
Optional, 8–255 characters. Reuse only for the identical request.

Body

modelstringrequired
mo/mo-1.3.1, or an existing workspace/model using that base. Mo Fast returns 422 fine_tune_base_model_unsupported.
training_filestringrequired
Completed uploaded dataset name. Training datasets are limited to 8 GiB and 1,000,000 rows. Rows may contain named image assets; a referenced image requires a vision-capable base, and the current text-only mo base returns fine_tune_modality_unsupported.
training_typehead_only | loradefault: head_only
Training mode.
destinationstring
Required with a base model: workspace/model. For an existing model, omit or match its name.
branchstringdefault: main
Existing destination branch. Omit it to publish to main.
tagstring
Optional immutable name created at the completed checkpoint.
sourceCommitShastring
Optional 40-character lowercase hex source revision.
validation_filestring
Optional uploaded dataset used for validation. When omitted, validation rows are selected deterministically from training_file.
eval_only_datasetstring
Optional uploaded eval-only-dataset used for final held-out evaluation. When omitted, evaluation rows are selected deterministically from training_file.
from_checkpointstring
Checkpoint reference to continue compatible training.
suffixstring
Optional label, 1–64 letters, digits, underscores, or hyphens.
lora_rinteger
LoRA rank; only admitted recipes are accepted.
lora_alphanumber
LoRA scaling.
lora_dropoutnumber
LoRA dropout.
max_seq_lengthintegerdefault: 262144
1–262144.
n_epochsintegerdefault: 1
1–100.
max_stepsinteger | nulldefault: null
Optional 1–1000000 optimizer-step ceiling. Sampling is deterministic for the same dataset and random seed.
max_eval_examplesinteger | nulldefault: null
Optional 1–1000000 per-partition evaluation-example ceiling. Selection is deterministic for the same dataset and random seed.
n_checkpointsintegerdefault: 1
1–10.
n_evalsintegerdefault: 0
0–1000.
batch_sizeinteger | maxdefault: max
1–1024 or max.
gradient_accumulation_stepsintegerdefault: 1
0–1024; 0 resolves to 1.
learning_ratenumberdefault: 0.00001
Greater than 0, at most 1.
warmup_rationumberdefault: 0
0 inclusive to 1 exclusive.
max_grad_normnumberdefault: 1
0–1000000.
weight_decaynumberdefault: 0
0–1.
random_seedinteger | nulldefault: 131031
0–9007199254740991; null uses default.
early_stopping_enabledbooleandefault: false
Requires sufficient n_evals.
early_stopping_patienceintegerdefault: 2
1–1000.
early_stopping_min_deltanumberdefault: 0
Nonnegative.
early_stopping_warmup_evalsinteger | nulldefault: 1
0–1000; null uses default.
lr_schedulerobject
lr_scheduler_type: constant (default), linear, or cosine. Optional lr_scheduler_args: min_lr_ratio (0–1, default 0) and num_cycles (positive, at most 100, default 0.5).
wandb_api_keystring
Optional Weights & Biases tracking setting. Keep credentials secret.
wandb_base_urlstring
Optional Weights & Biases tracking setting.
wandb_project_namestring
Optional Weights & Biases tracking setting.
wandb_namestring
Optional Weights & Biases tracking setting.
wandb_entitystring
Optional Weights & Biases tracking setting.
multimodal_paramsobject
Only { "train_vision": false } is supported; vision weights remain frozen.

Early stopping requires n_evals at least patience + warmup evaluations + 1.

{
  "model": "acme/support-priority",
  "training_file": "support-labels",
  "training_type": "head_only"
}

Response

idUUID

Job ID.

repositoryIdUUID

Destination model ID.

training_filestring

Uploaded dataset name.

statusqueued | training | committing | publishing | done | failed | cancelled

Check status and error before using a result.

training_typehead_only | lora

Training mode.

branchstring

Destination branch.

sourceCommitShastring

Starting revision.

resultCommitShastring | null

Published revision; null before publication.

datasetIdUUID

Dataset ID.

datasetCommitShastring

Pinned dataset revision.

datasetSha256string

Dataset checksum.

presetstring

Applied training preset.

progressobject | null

Current progress when available.

resultobject | null

Metrics, evaluation, advisory qualityGate, readinessAssessment, servingQualification, and publication when available. Readiness checks use passed, warning, or unknown; unavailable evaluation does not unpublish valid trained weights. Serving qualification identifies the training data as datasetSha256; it has no task ID. Publication includes commitSha, branch, and the optional immutable tag.

errorobject | null

Failure code and message. fine_tune_modality_unsupported means the dataset references an image but the selected base is text-only.

createdAtdatetime
updatedAtdatetime
startedAtdatetime | null
finishedAtdatetime | null
Was this page helpful?