create fine tuning job
create_fine_tuning_jobStart supervised or spec-draft fine-tuning of a catalog base model on your uploaded file or workspace dataset, with validated hyperparameters, then poll the returned job ID for status.
Instructions
Start a supervised (SFT/LoRA) or spec-draft fine-tune of a catalog base model on an uploaded file or a workspace dataset, with bounds-checked hyperparameters — the way a customer trains a custom model from their own data. POST /v1/fine_tuning/jobs (API-key scope: platform:write). SPENDS MONEY: this starts billable work on the workspace wallet. Returns: 201 {id (job id for all other /v1/fine_tuning/jobs/{id} calls), provider_job_id}. Poll GET /v1/fine_tuning/jobs/{id} for status and fine_tuned_model. Notes: MONEY: the wallet must hold a prepay runway of (1,000,000 estimated trained tokens × the model's per-token rate incl. markup) or the call fails 402 "Insufficient balance: starting a fine-tune requires at least $X of runway. Top up and try again."; the final charge is metered from real trained tokens on completion (billed_cost_usd). Requires OWNER/ADMIN minting user (403). Rate limited per workspace: 20 creates per 60s → 429 with Retry-After. 400 "Invalid JSON body" or "Invalid body: — " (e.g. missing training data: pass training or training_file_id). 400 when no price is configured for the model ("No fine-tuning price is set for this model yet."). Top-level keys accept both snake_case and camelCase; nested hyperparameter/integration/mapping keys are snake_case only. Feature-flag gated (404 when fineTuning is off). Scopes not enforced on this route today.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Display name for the job (≤300 chars). | |
| seed | No | Training seed, integer 0..2147483647. | |
| method | No | "supervised" (SFT / LoRA; default) or "spec-draft" (train a draft speculator for speculative decoding). Default: "supervised". | |
| suffix | No | Suffix appended to the fine-tuned model name (≤120 chars). | |
| training | No | Training data source (required unless training_file_id is given). Either {kind:"file", file_id: string (a provider_file_id from /v1/fine_tuning/files; alias fileId)} or {kind:"dataset", provider_dataset_id: string (alias providerDatasetId; a workspace dataset's provider id), version?: string (≤200), mapping: <column mapping>}. mapping is one of: {type:"text", text:{type:"column", name}} | {type:"prompts", prompt:{type:"column", name}, completion:{type:"column", name}} | {type:"messages", messages:{type:"column", name}} | {type:"pretokenized", input_ids:{type:"column", name}, labels?:{type:"column", name}, attention_mask?:{type:"column", name}}. Datasets are converted to a training file after the wallet gate. The file/dataset MUST belong to this workspace (404 "Training file not found" / "Dataset not found" otherwise). | |
| base_model | Yes | Base model id from the fine-tunable catalog (1..300 chars). Supervised jobs accept only the curated fine-tunable list (400 "This model isn't available for fine-tuning. Pick one from the list."); spec-draft jobs need a model in the spec-draft catalog. camelCase alias baseModel also accepted (camelCase wins if both present). | |
| validation | No | Optional held-out/validation data source, same shape as training ({kind:"file", file_id} or {kind:"dataset", provider_dataset_id, version?, mapping}). Providing one is what makes a later bake-off (POST /v1/fine_tuning/jobs/{id}/bakeoff) possible. | |
| integrations | No | Up to 10 export integrations; ONLY these two types are accepted (anything else is 400): {type:"wandb", wandb:{project (1..200), api_key (1..500), name? (≤200), entity? (≤200), tags? (≤50 strings ≤100)}} or {type:"hf", hf:{output_repo_name (1..200), api_token (1..500)}}. | |
| hyperparameters | No | Supervised hyperparameters, all optional and bounds-checked (400 naming the field otherwise): n_epochs (int 1..100), learning_rate (number >0 and ≤1), batch_size (int 1..1024), context_length (int 128..262144), warmup_ratio (0..1), weight_decay (0..1), packing (boolean), max_grad_norm (>0 and ≤1000), lora (boolean; some bases are full-parameter only → 400 "… supports full-parameter fine-tuning only"), lora_r (int 1..512), lora_alpha (int 1..1024), lora_dropout (0..1). Keys are snake_case only. | |
| training_file_id | No | Legacy shortcut: a provider_file_id to train on (1..500 chars); equivalent to training:{kind:"file", file_id}. Ignored when training is present. Alias trainingFileId. | |
| validation_file_id | No | Legacy shortcut for validation:{kind:"file", file_id}. Alias validationFileId. | |
| spec_draft_hyperparameters | No | Spec-draft hyperparameters (used when method="spec-draft"): the common fields n_epochs, learning_rate, batch_size, context_length, warmup_ratio, weight_decay, packing, max_grad_norm (same bounds as above) plus architecture (string ≤200), num_decoding_heads (int 1..16), loss (string ≤100). Alias specDraftHyperparameters. |