API reference · Fine-tuning
Create a fine-tuning job (reserves its estimated cost; 402 when credit is short)
/v1/fine-tunes- TypeScript
client.fineTuning.create()- Python
client.fine_tuning.create()- CLI
hayonix fine-tunes create
The job is billed per training and evaluation token, never for the hardware. Just before training starts the exact token count replaces the estimate and the reserved credit is resized to it; if the credit cannot cover it the job stops with insufficient_credit and nothing is charged. A succeeded job produces a fine-tuned model.
Project API key (Authorization: Bearer sk_…), or a console session. Requires the fine_tune_job:create permission (a key's scope, or a role that includes it).
Examples
The samples read API_KEY and API_BASE_URL from the environment (see Setup). Values are examples.
curl -sS "$API_BASE_URL/fine-tunes" \
-H "Authorization: Bearer $API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"model": "HuggingFaceTB/SmolLM2-135M-Instruct",
"training_file_id": "file_01jc5zq4m8k3v6x9t2w7r0b1e4",
"method": {
"type": "supervised"
},
"adapter": {
"type": "lora",
"rank": 8
},
"hyperparameters": {
"epochs": 2,
"learning_rate": 0.0002
}
}'Request
| Header | Required | Description |
|---|---|---|
Authorization | yes | Bearer and your API key. The key implies its project. |
X-Project-Id | session only | The project to act in, for console sessions. Requests with an API key leave it out. |
Idempotency-Key | no | Makes a retry safe: the same key and request within 24 hours return the original response (see Idempotency). The SDKs send one for you. |
Body
JSON (application/json): CreateFineTuneRequest.
modelstringrequiredA fine-tunable base model (GET /v1/fine-tunes/base-models): slug or ID
1–200 characters
training_file_idstringrequiredID of the training file
ID with prefix file_
validation_file_idstring | nullID of the validation file
ID with prefix file_
methodFineTuneMethodDefault supervised
adapterFineTuneAdapterDefault LoRA
hyperparametersFineTuneHyperparametersShowHide 11 fields of
hyperparametersepochsintegerDefault 1
1–20
batch_sizeintegerDefault 8
1–256
gradient_accumulation_stepsintegerBatches accumulated per optimizer step (default 1)
1–64
learning_ratenumberDefault 0.0001
1e-7–0.01
lr_schedulerstringHow the learning rate changes over the run (default linear)
One of
linearcosineconstantwarmup_rationumberShare of the steps over which the learning rate ramps up from 0 (default 0)
0–0.5
weight_decaynumberWeight decay (default 0)
0–1
max_grad_normnumberGradients are clipped to this norm (default 1)
0–100
max_seq_lengthintegerLonger examples are truncated (default: the model limit, up to 2048)
32–131072
max_stepsinteger | nullStop after this many optimizer steps, whatever `epochs` says; null or omitted: no step limit
1–1000000
seedintegerRandom seed, for repeatable runs (default 42)
0–2147483647
evaluationobjectEvaluations per epoch on the validation file (default 1)
ShowHide 1 field of
evaluationevals_per_epochintegerTimes per epoch the validation file is evaluated, 0–20 (default 1); evaluation tokens are billed
0–20
early_stoppingobject | nullStop when evaluation loss has not improved for `patience` evaluations
ShowHide 2 fields of
early_stoppingpatienceintegerEvaluations in a row without improvement before training stops (default 2)
1–50
min_deltanumberSmallest drop in evaluation loss that counts as an improvement (default 0)
0–10
checkpointsintegerCheckpoints saved over the run, the final one included (default 1)
1–10
merge_weightsbooleanLoRA: also produce merged full weights (default true)
continue_from_checkpoint_idstring | nullContinue training from a checkpoint of an earlier job
ID with prefix ftc_
suffixstring | nullLowercase letters, digits and dashes; part of the result model name
1–40 characters
hardwareobjectWhere the job trains: `sku` (default: the base model's first listed SKU) and, for a GPU SKU, `gpu_count` (1–8, default 1; 0 for a CPU SKU). Training is billed per token whatever the hardware.
ShowHide 2 fields of
hardwareskustringHardware type code
1–64 characters
gpu_countintegerNumber of GPUs
0–8
integrationsFineTuneIntegrationsShowHide 2 fields of
integrationswandbobjectLog training to Weights & Biases (the key is a project secret)
ShowHide 5 fields of
wandbapi_key_secret_idstringrequiredID of the api key secret
ID with prefix sec_
projectstringrequiredThe Weights & Biases project to log to
1–128 characters
entitystringTeam or user that owns the project; default: the key owner
1–128 characters
run_namestringName of the run; default: the job ID
1–128 characters
base_urlstring (uri)A self-hosted Weights & Biases server; default: the public service
up to 512 characters
hugging_faceobjectUpload the result to the Hugging Face Hub (the token is a project secret)
ShowHide 4 fields of
hugging_facetoken_secret_idstringrequiredID of the token secret
ID with prefix sec_
repositorystringrequiredThe model repository to upload to, as `<namespace>/<name>`
3–193 characters
privatebooleanCreate the repository as private when it does not exist yet (default true); an existing repository keeps its visibility
artifactstringWhat to upload: the LoRA `adapter` (default) or the `merged` full weights
One of
adaptermerged
Response
201 FineTune — The queued job
idstringrequiredUnique ID (`ftj_…`)
ID with prefix ftj_
objectstringrequiredAlways `fine_tune`: the type of this object
One of
fine_tuneproject_idstringrequiredProject it belongs to
ID with prefix prj_
statestringrequiredqueued (credit reserved, waiting for compute) → launching (the training environment is starting) → training → succeeded | failed | cancelled | stopped (stopped by billing: out of credit, spend limit or suspension)
One of
queuedlaunchingtrainingsucceededfailedcancelledstoppedstagestring | nullrequiredFiner detail of what the job is doing while launching or training, such as `waiting_for_compute` or `training`; null otherwise
modelstringrequiredBase model slug
base_model_idstringrequiredID of the base model
ID with prefix mdl_
methodstringrequiredThe training method (see `config.method`)
One of
supervisedpreferenceadapter_typestringrequired`lora`: trains a low-rank adapter; `full`: updates every weight
One of
lorafulltraining_file_idstringrequiredID of the training file
ID with prefix file_
validation_file_idstring | nullrequiredID of the validation file
ID with prefix file_
continue_from_checkpoint_idstring | nullrequiredID of the continue from checkpoint
ID with prefix ftc_
suffixstring | nullrequiredPart of the result model's name, as given at creation; null when none was given
configobjectrequiredMethod, adapter, hyperparameters, evaluation, early stopping and checkpoint settings, defaults filled in
integrationsobjectrequiredExport hooks (secret IDs only, never values)
hardwareobjectrequiredWhere the job trains: SKU, GPUs (0 on a CPU SKU) and region
ShowHide 3 fields of
hardwareskustringrequiredHardware type code
gpu_countintegerrequiredNumber of GPUs
regionstringrequiredRegion code
progressobjectrequiredHow far training has got
ShowHide 6 fields of
progresssteps_completedintegerrequiredOptimizer steps done
total_stepsinteger | nullrequiredOptimizer steps the run will take; null until training starts
epochs_completednumberrequiredPasses over the training file, fractional while one is under way
trained_tokensintegerrequiredBillable training tokens processed so far
evaluation_tokensintegerrequiredBillable evaluation tokens processed so far
early_stoppedbooleanrequiredTraining stopped early because evaluation loss stopped improving
billingobjectrequiredWhat the job costs: billed per training and evaluation token, from credit reserved at creation
ShowHide 6 fields of
billingestimated_tokensintegerrequiredThe estimate at creation (from the files: characters / 4 plus overhead)
planned_tokensinteger | nullrequiredExact billable tokens counted just before training starts; the reserved credit is resized to their cost. Null until then.
reservedstringrequiredInteger nano-USD as a decimal string
pattern ^-?[0-9]+$
chargedstring | nullrequiredSet when the job ends: tokens processed × price, never above the reservation
pattern ^-?[0-9]+$
priceTrainingPrice | any JSON | nullrequiredThe training price the job is billed at (the price book in force when it was created)
ShowHide 5 fields of
priceunit_pricestringrequiredInteger nano-USD as a decimal string
pattern ^-?[0-9]+$
unit_quantitystringrequiredTokens the unit price is for
per_million_tokensstringrequiredInteger nano-USD as a decimal string
pattern ^-?[0-9]+$
display_unitstring | nullrequiredLabel of the unit for display; null when none is set
price_book_versionintegerrequiredVersion of the price book the price comes from
accruedstringrequiredCost of the tokens processed so far at that price, never above the reservation; equals `charged` once the job has ended
pattern ^-?[0-9]+$
errorobject | nullrequiredWhy the job failed, was cancelled or was stopped (for example `cancelled`, `insufficient_credit`); null otherwise
ShowHide 2 fields of
errorcodestringrequiredMachine-readable code
messagestringrequiredOne sentence for people
resultobject | nullrequiredThe fine-tuned model of a succeeded job
ShowHide 1 field of
resultShowHide 14 fields of
fine_tuned_modelidstringrequiredUnique ID (`ftm_…`)
ID with prefix ftm_
objectstringrequiredAlways `fine_tuned_model`: the type of this object
One of
fine_tuned_modelproject_idstringrequiredProject it belongs to
ID with prefix prj_
namestringrequiredThe model name, unique in the org
fine_tune_idstringrequiredID of the fine-tuning job
ID with prefix ftj_
checkpoint_idstringrequiredID of the checkpoint
ID with prefix ftc_
base_modelobjectrequiredThe model that was fine-tuned
ShowHide 2 fields of
base_modelidstringrequiredUnique ID (`mdl_…`)
ID with prefix mdl_
slugstringrequiredThe base model's name (`publisher/name`)
methodstringrequiredThe training method of the job that produced it
One of
supervisedpreferenceadapter_typestringrequired`lora`: a low-rank adapter on the base model; `full`: full weights
One of
lorafulladapterobject | nullrequiredThe LoRA adapter; null for a full fine-tune
ShowHide 6 fields of
adapterformatstringrequiredFile format of the adapter
bytesintegerrequiredSize in bytes
filesarray of objectrequiredThe files that make up the adapter
rankinteger | nullrequiredLoRA rank; null when not recorded
alphainteger | nullrequiredLoRA alpha; null when not recorded
target_modulesstring | array of string | any JSON | nullrequiredLayers the adapter was trained on (`all-linear` or module names); null: the model's usual LoRA targets
merged_weightsobject | nullrequiredFull weights: the base model with the adapter merged in, or the result of a full fine-tune; null when a LoRA job was created with `merge_weights: false`
ShowHide 3 fields of
merged_weightsformatstringrequiredFile format of the weights
bytesintegerrequiredSize in bytes
filesarray of objectrequiredThe files that make up the weights
catalog_model_idstring | nullrequiredID of the catalog model
ID with prefix mdl_
servingobjectrequiredHow the model can be served: per token on the shared pool of its base model (`shared`), or on a dedicated endpoint (create one with `model.source = fine_tuned_model`)
ShowHide 4 fields of
servingavailablebooleanrequiredCallable per token right now under `name` (shared serving is ready)
sharedobjectrequiredShared (per-token) serving
dedicatedobjectrequiredWhether a dedicated endpoint deployment on each engine finds weights for this model (false: creating one answers `artifact_unavailable`; llama.cpp needs the merged GGUF, which older models lack)
formatsarray of stringrequiredServing formats the model has besides its safetensors: adapter_gguf, merged_gguf (llama.cpp engines)
created_atstring (date-time)requiredWhen it was created (ISO 8601, UTC)
created_atstring (date-time)requiredWhen it was created (ISO 8601, UTC)
launched_atstring (date-time) | nullrequiredTime launched (ISO 8601, UTC)
started_atstring (date-time) | nullrequiredWhen it started (null until then) (ISO 8601, UTC)
finished_atstring (date-time) | nullrequiredWhen it finished (null until then) (ISO 8601, UTC)
updated_atstring (date-time)requiredWhen it last changed (ISO 8601, UTC)
Example response
{
"id": "ftj_01jc5zq4m8k3v6x9t2w7r0b1e4",
"object": "fine_tune",
"project_id": "prj_01jc5zq4m8k3v6x9t2w7r0b1e4",
"state": "queued",
"stage": "string",
"model": "string",
"base_model_id": "mdl_01jc5zq4m8k3v6x9t2w7r0b1e4",
"method": "supervised",
"adapter_type": "lora",
"training_file_id": "file_01jc5zq4m8k3v6x9t2w7r0b1e4",
"validation_file_id": "file_01jc5zq4m8k3v6x9t2w7r0b1e4",
"continue_from_checkpoint_id": "ftc_01jc5zq4m8k3v6x9t2w7r0b1e4",
"suffix": "string",
"config": {},
"integrations": {},
"hardware": {
"sku": "string",
"gpu_count": 1,
"region": "string"
},
"progress": {
"steps_completed": 1,
"total_steps": 1,
"epochs_completed": 1.5,
"trained_tokens": 1,
"evaluation_tokens": 1,
"early_stopped": true
},
"billing": {
"estimated_tokens": 1,
"planned_tokens": 1,
"reserved": "1500000000",
"charged": "1500000000",
"price": {
"unit_price": "1500000000",
"unit_quantity": "string",
"per_million_tokens": "1500000000",
"display_unit": "string",
"price_book_version": 1
},
"accrued": "1500000000"
},
"error": {
"code": "string",
"message": "string"
},
"result": {
"fine_tuned_model": {
"id": "ftm_01jc5zq4m8k3v6x9t2w7r0b1e4",
"object": "fine_tuned_model",
"project_id": "prj_01jc5zq4m8k3v6x9t2w7r0b1e4",
"name": "string",
"fine_tune_id": "ftj_01jc5zq4m8k3v6x9t2w7r0b1e4",
"checkpoint_id": "ftc_01jc5zq4m8k3v6x9t2w7r0b1e4",
"base_model": {
"id": "mdl_01jc5zq4m8k3v6x9t2w7r0b1e4",
"slug": "string"
},
"method": "supervised",
"adapter_type": "lora",
"adapter": {
"format": "string",
"bytes": 1,
"files": [
{
"path": "string",
"bytes": 1,
"sha256": "string"
}
],
"rank": 1,
"alpha": 1,
"target_modules": "string"
},
"merged_weights": {
"format": "string",
"bytes": 1,
"files": [
{
"path": "string",
"bytes": 1,
"sha256": "string"
}
]
},
"catalog_model_id": "mdl_01jc5zq4m8k3v6x9t2w7r0b1e4",
"serving": {
"available": true,
"shared": {
"state": "disabled",
"status": "disabled",
"reason": "string",
"changed_at": "2026-01-01T00:00:00.000Z",
"price": {
"currency": "USD",
"unit": "nano_usd_per_1m_tokens",
"input": "1500000000",
"cached_input": "1500000000",
"output": "1500000000",
"batch": {
"input": null,
"cached_input": null,
"output": null
}
},
"blocked": {
"code": "not_an_adapter",
"message": "string"
}
},
"dedicated": {
"llama_cpp": true,
"vllm": true
},
"formats": [
"string"
]
},
"created_at": "2026-01-01T00:00:00.000Z"
}
},
"created_at": "2026-01-01T00:00:00.000Z",
"launched_at": "2026-01-01T00:00:00.000Z",
"started_at": "2026-01-01T00:00:00.000Z",
"finished_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z"
}Errors
Errors use the standard envelope. What this operation can answer:
| Status | Type | When |
|---|---|---|
400 | invalid_request_error | A parameter or body field is missing or not allowed; param names it. |
401 | authentication_error | The key or session is missing, revoked or expired. |
403 | permission_error | The credential lacks the permission this needs, or the organization is suspended. |
402 | insufficient_credit_error | The organization is out of credit or over a spend limit. |
409 | conflict_error idempotency_in_progress | A request with the same Idempotency-Key is still running. |
422 | idempotency_error idempotency_key_reused | The Idempotency-Key was used with a different request. |
429 | rate_limit_error rate_limited | Too many requests; retry after retry-after seconds. |