API reference

API reference · API

Distill this key's captured traffic into a small fine tuned model

POST/v1/distillAPI key

Chat scope. The training is held on a funded balance at the provider's published price per training token times tokens times epochs, marked up; then the training file is uploaded. Settled at the provider's estimate, never above the hold; released on failure. 402 insufficient_credits for an unfunded account or a balance short of the hold; 409 with code dataset_too_small for a thin window. A 404 at every path while the operator has not turned distillation on.

Request body

application/json, required

Request body fields
FieldTypeWhat it is
key_idrequiredintegerThe key whose captures are read. Over /v1/distill it is always the calling key. At most 9007199254740991.
teacherrequiredstringThe model whose answers are learnt: captured requests it answered with a 2xx. At most 200 characters.
base_modelrequiredstringThe base model trained: meta-llama/Meta-Llama-3.1-8B-Instruct-Reference, Qwen/Qwen3.5-9B, openai/gpt-oss-20b, Qwen/Qwen3.5-27B, meta-llama/Llama-3.3-70B-Instruct-Reference. At most 200 characters.
fromrequiredintegerThe window's start, unix seconds; the window is at most 30 days wide. From 0 to 9007199254740991.
torequiredintegerThe window's end, unix seconds. From 0 to 9007199254740991.
holdoutnumberThe newest share held out for the proof, 0.1 unless set. From 0.05 to 0.3.
epochsintegerPasses over the training set, 3 unless set. From 1 to 10.
namestringAt most 80 characters.
compareobjectHow the proof compares answers: auto unless set, or embedding or judge with a model you name, billed.
compare.methodrequiredstringOne of "auto", "embedding", "judge".
compare.modelstringAt most 200 characters.

Example

{
  "key_id": 0,
  "teacher": "string",
  "base_model": "string",
  "from": 0,
  "to": 0
}

Answer 201

The distillation.

Fields of the 201 answer
FieldTypeWhat it is
idstring
object"distill.job"
worldstringantimatter/distilled/<id>, nameable by the owner's keys only.
teacherstring
base_modelstring
statusanyOne of "uploading", "validating", "training", "completed", "failed", "cancelled".
trainingobject
lossarray of object
loss[].kindanyOne of "train", "eval".
loss[].stepinteger
loss[].lossnumber
world_stateobject
world_state.stateanyOne of "dark", "lighting", "lit", "darkening".
world_state.hourly_microsinteger or null
world_state.untilinteger or null
world_state.spent_microsinteger
proofobject or nullAgreement on the held out slice with its 95% Wilson interval, latency beside the teacher's, and a request's cost before and after at the key's own rate.

Errors

  • 400OpenAI shaped error.
  • 401OpenAI shaped error.
  • 402OpenAI shaped error.
  • 403OpenAI shaped error.
  • 404OpenAI shaped error.
  • 409OpenAI shaped error.
  • 429Rate limited, or a spent budget or spend cap. The type distinguishes rate_limit_error, policy_exceeded, and spend_cap_exceeded.
  • 502OpenAI shaped error.

Every error answers in one shape, with its type, code and the field it names. The whole list is in the docs' Errors section.

Antimatter