Skip to content
Hayonix

API reference · Fine-tuning

Create a fine-tuning job (reserves its estimated cost; 402 when credit is short)

POST/v1/fine-tunes
API keyfine_tune_job:createProjectIdempotency-Key
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

Headers
HeaderRequiredDescription
AuthorizationyesBearer and your API key. The key implies its project.
X-Project-Idsession onlyThe project to act in, for console sessions. Requests with an API key leave it out.
Idempotency-KeynoMakes 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.

  • modelstringrequired

    A fine-tunable base model (GET /v1/fine-tunes/base-models): slug or ID

    1–200 characters

  • training_file_idstringrequired

    ID of the training file

    ID with prefix file_

  • validation_file_idstring | null

    ID of the validation file

    ID with prefix file_

  • Default supervised

  • Default LoRA

  • Show 11 fields of hyperparameters
    • epochsinteger

      Default 1

      1–20

    • batch_sizeinteger

      Default 8

      1–256

    • gradient_accumulation_stepsinteger

      Batches accumulated per optimizer step (default 1)

      1–64

    • learning_ratenumber

      Default 0.0001

      1e-7–0.01

    • lr_schedulerstring

      How the learning rate changes over the run (default linear)

      One oflinearcosineconstant

    • warmup_rationumber

      Share of the steps over which the learning rate ramps up from 0 (default 0)

      0–0.5

    • weight_decaynumber

      Weight decay (default 0)

      0–1

    • max_grad_normnumber

      Gradients are clipped to this norm (default 1)

      0–100

    • max_seq_lengthinteger

      Longer examples are truncated (default: the model limit, up to 2048)

      32–131072

    • max_stepsinteger | null

      Stop after this many optimizer steps, whatever `epochs` says; null or omitted: no step limit

      1–1000000

    • seedinteger

      Random seed, for repeatable runs (default 42)

      0–2147483647

  • evaluationobject

    Evaluations per epoch on the validation file (default 1)

    Show 1 field of evaluation
    • evals_per_epochinteger

      Times per epoch the validation file is evaluated, 0–20 (default 1); evaluation tokens are billed

      0–20

  • early_stoppingobject | null

    Stop when evaluation loss has not improved for `patience` evaluations

    Show 2 fields of early_stopping
    • patienceinteger

      Evaluations in a row without improvement before training stops (default 2)

      1–50

    • min_deltanumber

      Smallest drop in evaluation loss that counts as an improvement (default 0)

      0–10

  • checkpointsinteger

    Checkpoints saved over the run, the final one included (default 1)

    1–10

  • merge_weightsboolean

    LoRA: also produce merged full weights (default true)

  • continue_from_checkpoint_idstring | null

    Continue training from a checkpoint of an earlier job

    ID with prefix ftc_

  • suffixstring | null

    Lowercase letters, digits and dashes; part of the result model name

    1–40 characters

  • hardwareobject

    Where 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.

    Show 2 fields of hardware
    • skustring

      Hardware type code

      1–64 characters

    • gpu_countinteger

      Number of GPUs

      0–8

  • Show 2 fields of integrations
    • wandbobject

      Log training to Weights & Biases (the key is a project secret)

      Show 5 fields of wandb
      • api_key_secret_idstringrequired

        ID of the api key secret

        ID with prefix sec_

      • projectstringrequired

        The Weights & Biases project to log to

        1–128 characters

      • entitystring

        Team or user that owns the project; default: the key owner

        1–128 characters

      • run_namestring

        Name 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_faceobject

      Upload the result to the Hugging Face Hub (the token is a project secret)

      Show 4 fields of hugging_face
      • token_secret_idstringrequired

        ID of the token secret

        ID with prefix sec_

      • repositorystringrequired

        The model repository to upload to, as `<namespace>/<name>`

        3–193 characters

      • privateboolean

        Create the repository as private when it does not exist yet (default true); an existing repository keeps its visibility

      • artifactstring

        What to upload: the LoRA `adapter` (default) or the `merged` full weights

        One ofadaptermerged

Response

201 FineTune — The queued job

  • idstringrequired

    Unique ID (`ftj_…`)

    ID with prefix ftj_

  • objectstringrequired

    Always `fine_tune`: the type of this object

    One offine_tune

  • project_idstringrequired

    Project it belongs to

    ID with prefix prj_

  • statestringrequired

    queued (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 ofqueuedlaunchingtrainingsucceededfailedcancelledstopped

  • stagestring | nullrequired

    Finer detail of what the job is doing while launching or training, such as `waiting_for_compute` or `training`; null otherwise

  • modelstringrequired

    Base model slug

  • base_model_idstringrequired

    ID of the base model

    ID with prefix mdl_

  • methodstringrequired

    The training method (see `config.method`)

    One ofsupervisedpreference

  • adapter_typestringrequired

    `lora`: trains a low-rank adapter; `full`: updates every weight

    One oflorafull

  • training_file_idstringrequired

    ID of the training file

    ID with prefix file_

  • validation_file_idstring | nullrequired

    ID of the validation file

    ID with prefix file_

  • continue_from_checkpoint_idstring | nullrequired

    ID of the continue from checkpoint

    ID with prefix ftc_

  • suffixstring | nullrequired

    Part of the result model's name, as given at creation; null when none was given

  • configobjectrequired

    Method, adapter, hyperparameters, evaluation, early stopping and checkpoint settings, defaults filled in

  • integrationsobjectrequired

    Export hooks (secret IDs only, never values)

  • hardwareobjectrequired

    Where the job trains: SKU, GPUs (0 on a CPU SKU) and region

    Show 3 fields of hardware
    • skustringrequired

      Hardware type code

    • gpu_countintegerrequired

      Number of GPUs

    • regionstringrequired

      Region code

  • progressobjectrequired

    How far training has got

    Show 6 fields of progress
    • steps_completedintegerrequired

      Optimizer steps done

    • total_stepsinteger | nullrequired

      Optimizer steps the run will take; null until training starts

    • epochs_completednumberrequired

      Passes over the training file, fractional while one is under way

    • trained_tokensintegerrequired

      Billable training tokens processed so far

    • evaluation_tokensintegerrequired

      Billable evaluation tokens processed so far

    • early_stoppedbooleanrequired

      Training stopped early because evaluation loss stopped improving

  • billingobjectrequired

    What the job costs: billed per training and evaluation token, from credit reserved at creation

    Show 6 fields of billing
    • estimated_tokensintegerrequired

      The estimate at creation (from the files: characters / 4 plus overhead)

    • planned_tokensinteger | nullrequired

      Exact billable tokens counted just before training starts; the reserved credit is resized to their cost. Null until then.

    • reservedstringrequired

      Integer nano-USD as a decimal string

      pattern ^-?[0-9]+$

    • chargedstring | nullrequired

      Set when the job ends: tokens processed × price, never above the reservation

      pattern ^-?[0-9]+$

    • priceTrainingPrice | any JSON | nullrequired

      The training price the job is billed at (the price book in force when it was created)

      Show 5 fields of price
      • unit_pricestringrequired

        Integer nano-USD as a decimal string

        pattern ^-?[0-9]+$

      • unit_quantitystringrequired

        Tokens the unit price is for

      • per_million_tokensstringrequired

        Integer nano-USD as a decimal string

        pattern ^-?[0-9]+$

      • display_unitstring | nullrequired

        Label of the unit for display; null when none is set

      • price_book_versionintegerrequired

        Version of the price book the price comes from

    • accruedstringrequired

      Cost of the tokens processed so far at that price, never above the reservation; equals `charged` once the job has ended

      pattern ^-?[0-9]+$

  • errorobject | nullrequired

    Why the job failed, was cancelled or was stopped (for example `cancelled`, `insufficient_credit`); null otherwise

    Show 2 fields of error
    • codestringrequired

      Machine-readable code

    • messagestringrequired

      One sentence for people

  • resultobject | nullrequired

    The fine-tuned model of a succeeded job

    Show 1 field of result
    • fine_tuned_modelFineTunedModelrequired
      Show 14 fields of fine_tuned_model
      • idstringrequired

        Unique ID (`ftm_…`)

        ID with prefix ftm_

      • objectstringrequired

        Always `fine_tuned_model`: the type of this object

        One offine_tuned_model

      • project_idstringrequired

        Project it belongs to

        ID with prefix prj_

      • namestringrequired

        The model name, unique in the org

      • fine_tune_idstringrequired

        ID of the fine-tuning job

        ID with prefix ftj_

      • checkpoint_idstringrequired

        ID of the checkpoint

        ID with prefix ftc_

      • base_modelobjectrequired

        The model that was fine-tuned

        Show 2 fields of base_model
        • idstringrequired

          Unique ID (`mdl_…`)

          ID with prefix mdl_

        • slugstringrequired

          The base model's name (`publisher/name`)

      • methodstringrequired

        The training method of the job that produced it

        One ofsupervisedpreference

      • adapter_typestringrequired

        `lora`: a low-rank adapter on the base model; `full`: full weights

        One oflorafull

      • adapterobject | nullrequired

        The LoRA adapter; null for a full fine-tune

        Show 6 fields of adapter
        • formatstringrequired

          File format of the adapter

        • bytesintegerrequired

          Size in bytes

        • filesarray of objectrequired

          The files that make up the adapter

        • rankinteger | nullrequired

          LoRA rank; null when not recorded

        • alphainteger | nullrequired

          LoRA alpha; null when not recorded

        • target_modulesstring | array of string | any JSON | nullrequired

          Layers the adapter was trained on (`all-linear` or module names); null: the model's usual LoRA targets

      • merged_weightsobject | nullrequired

        Full 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`

        Show 3 fields of merged_weights
        • formatstringrequired

          File format of the weights

        • bytesintegerrequired

          Size in bytes

        • filesarray of objectrequired

          The files that make up the weights

      • catalog_model_idstring | nullrequired

        ID of the catalog model

        ID with prefix mdl_

      • servingobjectrequired

        How 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`)

        Show 4 fields of serving
        • availablebooleanrequired

          Callable per token right now under `name` (shared serving is ready)

        • sharedobjectrequired

          Shared (per-token) serving

        • dedicatedobjectrequired

          Whether 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 stringrequired

          Serving formats the model has besides its safetensors: adapter_gguf, merged_gguf (llama.cpp engines)

      • created_atstring (date-time)required

        When it was created (ISO 8601, UTC)

  • created_atstring (date-time)required

    When it was created (ISO 8601, UTC)

  • launched_atstring (date-time) | nullrequired

    Time launched (ISO 8601, UTC)

  • started_atstring (date-time) | nullrequired

    When it started (null until then) (ISO 8601, UTC)

  • finished_atstring (date-time) | nullrequired

    When it finished (null until then) (ISO 8601, UTC)

  • updated_atstring (date-time)required

    When it last changed (ISO 8601, UTC)

Example response
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:

Errors
StatusTypeWhen
400invalid_request_errorA parameter or body field is missing or not allowed; param names it.
401authentication_errorThe key or session is missing, revoked or expired.
403permission_errorThe credential lacks the permission this needs, or the organization is suspended.
402insufficient_credit_errorThe organization is out of credit or over a spend limit.
409conflict_error idempotency_in_progressA request with the same Idempotency-Key is still running.
422idempotency_error idempotency_key_reusedThe Idempotency-Key was used with a different request.
429rate_limit_error rate_limitedToo many requests; retry after retry-after seconds.