Quickstart
Go from a JSONL file on disk to a running private model in seven calls.
This guide follows the managed path end to end: upload a dataset, fine-tune Qwen/Qwen3-8B
on it, check the result against the base model, serve it, and export the weights. It assumes
you already have an API key; if not, start with Authentication.
Upload your dataset
Training data is a JSONL file where each line is a JSON object with a messages array. Upload
it once with purpose=fine-tune and reference the returned file ID everywhere else.
curl https://api.nucleus-ai.io/v1/files \
-H "Authorization: Bearer $NUCLEUS_API_KEY" \
-F purpose=fine-tune \
-F [email protected]Wait for validation
Every file is validated line by line before it can be trained on. Poll
GET /v1/files/{file_id} until status is ready; if it comes back error, the response
lists each rejected line and the reason, so you can fix the export script before spending GPU
time on a bad dataset.
curl https://api.nucleus-ai.io/v1/files/file_9fQ2x \
-H "Authorization: Bearer $NUCLEUS_API_KEY"Submit the fine-tuning job
Point a fine-tuning job at the base model and your file.
Nucleus owns the training loop, the hyperparameters and the retries. Creating a job queues
real GPU time, so send an Idempotency-Key header if your client retries on timeout. See
Errors and retries.
curl https://api.nucleus-ai.io/v1/fine-tuning/jobs \
-H "Authorization: Bearer $NUCLEUS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"base_model": "Qwen/Qwen3-8B",
"training_file": "file_9fQ2x"
}'Watch it train
Poll the job until it finishes, or
stream its event log for live progress.
When status reaches succeeded, the job carries result_model, a reference like
nucleus://run_3Bz:train:0/sampler_weights/000240 to your fine-tuned weights. You pass it to
evaluations and samplers in the next steps.
curl https://api.nucleus-ai.io/v1/fine-tuning/jobs/ftjob_7Kd1p \
-H "Authorization: Bearer $NUCLEUS_API_KEY"
# live progress as a text/event-stream
curl -N "https://api.nucleus-ai.io/v1/fine-tuning/jobs/ftjob_7Kd1p/events?stream=true" \
-H "Authorization: Bearer $NUCLEUS_API_KEY"Evaluate the result
Upload a held-out test set the same way as step 1, with purpose=evaluation, then create an
benchmark, which holds the cases and, if you want one, the
score a model has to reach. Then create an
evaluation against it. Passing compare_to scores the base
model on the same cases, so you can see exactly what fine-tuning bought you. Poll
Retrieve an evaluation for the scores.
# Wrap the test set in a benchmark, which carries the cases and the bar
curl https://api.nucleus-ai.io/v1/benchmarks \
-H "Authorization: Bearer $NUCLEUS_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "name": "Held-out set", "dataset_file": "file_4kEv1" }'
# -> { "id": "bm_7Qa", ... }
curl https://api.nucleus-ai.io/v1/evaluations \
-H "Authorization: Bearer $NUCLEUS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "nucleus://run_3Bz:train:0/sampler_weights/000240",
"benchmark": "bm_7Qa",
"compare_to": "Qwen/Qwen3-8B"
}'Serve it
A sampler is a serving endpoint loaded with your weights. Create
one from the job's result_model, then make your first call through the
OpenAI-compatible chat completions route, the simplest way to
talk to the model.
curl https://api.nucleus-ai.io/v1/samplers \
-H "Authorization: Bearer $NUCLEUS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model_path": "nucleus://run_3Bz:train:0/sampler_weights/000240"}'
curl https://api.nucleus-ai.io/v1/chat/completions \
-H "Authorization: Bearer $NUCLEUS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "nucleus://run_3Bz:train:0/sampler_weights/000240",
"messages": [{"role": "user", "content": "Hello from my own model"}]
}'Export the weights
The weights belong to you. The job's finished weights are stored as a checkpoint; find its ID with List all checkpoints, then request an export. Exports run asynchronously: the response carries an operation ID, so poll the operation until it completes, then download the archive and run the weights wherever you like.
curl https://api.nucleus-ai.io/v1/training-runs/run_3Bz/checkpoints/ckpt_000240/export \
-H "Authorization: Bearer $NUCLEUS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"format": "merged-safetensors", "destination": "signed-url"}'That is the whole journey: seven calls from raw data to a running private model.
Where next
Managed fine-tuning
The same journey in depth: hyperparameters, events and failure handling.
Serving
Samplers, sampling parameters and the compatibility routes.
The training loop
Take over the loop for RL, DPO, distillation or custom losses.
API reference
Every endpoint, with parameters, scopes and example responses.