Fine-tuning API

Warning

Feature Not Implemented!

This functionality is currently under development and not yet available in AvalAI. This reference is retained as a future compatibility map; examples will not work until AvalAI announces supported fine-tuning routes and base models.

The Fine-tuning API allows you to customize models for your specific use case by training on your data.

Tip

OpenAI's current supervised fine-tuning docs recommend setting up evals before training, starting with high-quality JSONL chat examples, and using default hyperparameters until evals show a reason to change them. The current AvalAI data/models.json source does not advertise fine-tunable base models.

Endpoint

POST https://api.avalai.ir/v1/fine-tuning/jobs

Request Body

Parameter	Type	Required	Description
model	string	Yes	ID of a supported fine-tunable base model. No current AvalAI base model should be assumed fine-tunable until announced.
training_file	string	Yes	The ID of an uploaded file that contains training data.
validation_file	string	No	The ID of an uploaded file that contains validation data.
hyperparameters	object	No	The hyperparameters used for the fine-tuning job.
suffix	string	No	A string of up to 64 characters that will be added to your fine-tuned model name when supported.
method	object	No	Fine-tuning method, such as supervised fine-tuning, when supported by the route.

Method Object

method is route- and model-dependent. Keep examples behind a feature flag until AvalAI publishes supported methods.

Method type	Training signal	Planning notes
supervised	Prompt and ideal assistant response examples.	Best for consistent format, style, and instruction-following.
dpo	Preferred and rejected response pairs.	Best when humans can compare outputs but there is no single ground-truth answer.
reinforcement	A grader produces a numeric reward for sampled responses.	Best for measurable reasoning tasks; requires evals, grader validation, and safety checks.

For RFT-style jobs, design the grader before uploading data, keep validation prompts separate from training prompts, and confirm the base model has partial success before attempting training. A model that never solves the task cannot usually be bootstrapped by RFT.

Hyperparameters Object

Parameter	Type	Required	Description
n_epochs	integer or string	No	The number of epochs to train the model for. An epoch refers to one full cycle through the training dataset. Default is "auto".
batch_size	integer or string	No	Number of examples in each batch. Default is "auto".
learning_rate_multiplier	number or string	No	Scaling factor for the learning rate. Default is "auto".

Examples

Creating a Fine-tuning Job

Bash

curl https://api.avalai.ir/v1/fine-tuning/jobs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AVALAI_API_KEY" \
  -d '{
  "model": "fine-tunable-model-id",
  "training_file": "file-abc123",
  "validation_file": "file-def456",
  "hyperparameters": {
    "n_epochs": 4
  }
}'

Python

from openai import OpenAI

client = OpenAI(
    api_key="your-avalai-api-key",  # Replace with your actual API key
    base_url="https://api.avalai.ir/v1",  # AvalAI API endpoint
)

response = client.fine_tuning.jobs.create(
    model="fine-tunable-model-id",
    training_file="file-abc123",
    validation_file="file-def456",
    hyperparameters={"n_epochs": 4},
)

print(response)

JavaScript

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.AVALAI_API_KEY,
  baseURL: "https://api.avalai.ir/v1",
});

const response = await client.fineTuning.jobs.create({
  model: "fine-tunable-model-id",
  training_file: "file-abc123",
  validation_file: "file-def456",
  hyperparameters: {
    n_epochs: 4,
  },
});

console.log(response);

Go

// Go Example: Creating a Fine-tuning Job via AvalAI
package main

import (
	"context"
	"fmt"
	"os"

	openai "github.com/openai/openai-go"
)

func main() {
	apiKey := os.Getenv("AVALAI_API_KEY") // Or replace with your key
	if apiKey == "" {
		fmt.Println("Error: AVALAI_API_KEY environment variable not set.")
		return
	}
	baseURL := "https://api.avalai.ir/v1" // Use AvalAI base URL

	config := openai.DefaultConfig(apiKey)
	config.BaseURL = baseURL
	client := openai.NewClientWithConfig(config)

	req := openai.FineTuningJobRequest{
		Model:          "fine-tunable-model-id",
		TrainingFile:   "file-abc123",
		ValidationFile: "file-def456", // Optional
		Hyperparameters: &openai.Hyperparameters{
			NEpochs: 4, // Optional, example value
		},
		// Suffix: "my-custom-model", // Optional
	}

	resp, err := client.CreateFineTuningJob(context.Background(), req)
	if err != nil {
		fmt.Printf("FineTuningJob creation error: %v\n", err)
		return
	}

	fmt.Printf("Fine-tuning job created: %+v\n", resp)
}

PHP

<?php
// PHP Example: Creating a Fine-tuning Job via AvalAI

$apiKey = getenv('AVALAI_API_KEY'); // Or replace with your key directly
$apiUrl = 'https://api.avalai.ir/v1/fine-tuning/jobs'; // Use AvalAI base URL

$data = [
'model' => 'fine-tunable-model-id',
'training_file' => 'file-abc123',
'validation_file' => 'file-def456', // Optional
'hyperparameters' => [ // Optional
'n_epochs' => 4
]
// 'suffix' => 'my-custom-model' // Optional
];

$jsonData = json_encode($data);

$ch = curl_init($apiUrl);

curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonData);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'Authorization: Bearer ' . $apiKey,
'Content-Length: ' . strlen($jsonData)
]);

$response = curl_exec($ch);
$httpcode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$err = curl_error($ch);

curl_close($ch);

if ($err) {
  echo "cURL Error #:" . $err;
} elseif ($httpcode >= 400) {
  echo "HTTP Error: " . $httpcode . "\n";
  echo "Response: " . $response;
} else {
  echo "Fine-tuning job creation response:\n";
  echo $response;
  // $responseData = json_decode($response, true);
  // print_r($responseData);
}
?>

Response Format

{
  "id": "ftjob-abc123",
  "object": "fine_tuning.job",
  "model": "fine-tunable-model-id",
  "created_at": 1677858242,
  "finished_at": null,
  "fine_tuned_model": null,
  "organization_id": "org-123",
  "status": "running",
  "hyperparameters": {
    "n_epochs": 4
  },
  "training_file": "file-abc123",
  "validation_file": "file-def456",
  "result_files": [],
  "trained_tokens": null
}

Response Parameters

Parameter	Type	Description
id	string	The identifier for the fine-tuning job.
object	string	The object type, which is always "fine_tuning.job".
model	string	The base model that is being fine-tuned.
created_at	integer	The Unix timestamp (in seconds) of when the fine-tuning job was created.
finished_at	integer or null	The Unix timestamp (in seconds) of when the fine-tuning job was finished.
fine_tuned_model	string or null	The name of the fine-tuned model, if the job has completed successfully.
organization_id	string	The organization that owns the fine-tuning job.
status	string	The status of the fine-tuning job. Can be "validating", "preparing", "queued", "running", "succeeded", "failed", or "cancelled".
hyperparameters	object	The hyperparameters used for the fine-tuning job.
training_file	string	The ID of the file used for training.
validation_file	string or null	The ID of the file used for validation.
result_files	array	Array of file IDs generated during the fine-tuning job.
trained_tokens	integer or null	The number of tokens trained on during the fine-tuning job.

List Fine-tuning Jobs

GET https://api.avalai.ir/v1/fine-tuning/jobs

Query Parameters

Parameter	Type	Required	Description
limit	integer	No	Number of fine-tuning jobs to retrieve. Default is 20.
after	string	No	Identifier for the last job from the previous pagination request.

Retrieve Fine-tuning Job

GET https://api.avalai.ir/v1/fine-tuning/jobs/{fine_tuning_job_id}

Cancel Fine-tuning Job

POST https://api.avalai.ir/v1/fine-tuning/jobs/{fine_tuning_job_id}/cancel

List Fine-tuning Events

GET https://api.avalai.ir/v1/fine-tuning/jobs/{fine_tuning_job_id}/events

Query Parameters

Parameter	Type	Required	Description
limit	integer	No	Number of events to retrieve. Default is 20.
after	string	No	Identifier for the last event from the previous pagination request.

Event and Metrics Notes

Event payloads are provider- and method-dependent. When exposed, use them to debug the job rather than relying on the final status alone:

Metric family	Useful for
train_loss, valid_loss, token accuracy	SFT convergence and overfitting checks.
train_reward_mean, valid_reward_mean	RFT reward progress and validation drift.
grader-specific scores and usage	Finding weak, slow, or expensive graders.
parse and runtime error rates	Detecting invalid response schemas, bad grader variables, or tool-call format errors.

Training metrics are not deployment approval. Run your external eval suite and safety checks before using any fine_tuned_model in production.

Conditional Lifecycle Endpoints

Some upstream fine-tuning systems expose additional lifecycle controls such as pause, resume, and checkpoints. These are not guaranteed AvalAI endpoints; use them only if AvalAI announces support for your route and model.

Operation	Conditional path shape	Purpose
Pause job	POST /v1/fine-tuning/jobs/{fine_tuning_job_id}/pause	Stop training and create a checkpoint for evaluation when supported.
Resume job	POST /v1/fine-tuning/jobs/{fine_tuning_job_id}/resume	Continue training from the last checkpoint when supported.
List checkpoints	GET /v1/fine-tuning/jobs/{fine_tuning_job_id}/checkpoints	Compare intermediate candidate models against the final model and base model.

Checkpoint objects commonly include a checkpoint model ID, step number, creation time, and metrics. Treat each checkpoint model ID as a candidate: evaluate it on a held-out set, run safety checks, and keep rollback to the previous production model.

Error Handling

The API may return various error codes:

Status Code	Description
400	Bad Request - Your request is invalid.
401	Unauthorized - Your API key is wrong.
403	Forbidden - You don't have permission to access this resource.
404	Not Found - The specified resource could not be found.
429	Too Many Requests - You have exceeded your rate limit.
500	Internal Server Error - We had a problem with our server.

For more information on handling errors, see the Error Handling guide.

Related Resources

• Models - Learn about available models
• Authentication - Learn about authentication methods
• Rate Limits - Learn about API rate limits