Fine-tuning Jobs

Fine-tuning API

Fine-tune models on your own data to improve performance for your specific use case. The gateway supports fine-tuning endpoints for compatible providers.

Endpoints

Create Fine-tuning Job

POST /v1/fine_tuning/jobs Create a fine-tuning job to train a model on your data.

List Fine-tuning Jobs

GET /v1/fine_tuning/jobs List all fine-tuning jobs for your organization.

Retrieve Fine-tuning Job

GET /v1/fine_tuning/jobs/:jobId Get details about a specific fine-tuning job.

Cancel Fine-tuning Job

POST /v1/fine_tuning/jobs/:jobId/cancel Cancel a fine-tuning job that is in progress.

Authentication

Requires provider authentication headers:

x-portkey-provider: openai
Authorization: Bearer YOUR_OPENAI_API_KEY

Create Fine-tuning Job

Request Parameters

string

required

The ID of an uploaded file that contains training data. The file must be formatted as JSONL.

string

required

The model to fine-tune (e.g., gpt-4o-mini-2024-07-18, gpt-3.5-turbo-0125)

string

The ID of an uploaded file containing validation data (optional)

object

Training hyperparameters

Show hyperparameters object

integer

Number of training epochs (default: auto)

integer

Batch size for training (default: auto)

number

Learning rate multiplier (default: auto)

string

A string to append to the fine-tuned model name (max 40 characters)

Response

string

The fine-tuning job identifier

string

The object type, always “fine_tuning.job”

string

The base model being fine-tuned

integer

Unix timestamp of when the job was created

integer

Unix timestamp of when the job finished (null if in progress)

string

The name of the fine-tuned model (null until training completes)

string

Current status: created, running, succeeded, failed, or cancelled

string

The ID of the training file

string

The ID of the validation file (if provided)

object

The hyperparameters used for training

Example

Training Data Format

Prepare your training data as JSONL:

{"messages": [{"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "What is the capital of France?"}, {"role": "assistant", "content": "The capital of France is Paris."}]}
{"messages": [{"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "What is 2+2?"}, {"role": "assistant", "content": "2+2 equals 4."}]}

# Upload training file
curl https://localhost:8787/v1/files \
  -H "x-portkey-provider: openai" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F purpose="fine-tune" \
  -F file="@training_data.jsonl"

# Create fine-tuning job
curl https://localhost:8787/v1/fine_tuning/jobs \
  -H "x-portkey-provider: openai" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "training_file": "file-abc123",
    "model": "gpt-4o-mini-2024-07-18",
    "suffix": "custom-model-v1"
  }'

from portkey_ai import Portkey

client = Portkey(
    provider="openai",
    Authorization="sk-***"
)

# Upload training file
with open("training_data.jsonl", "rb") as file:
    training_file = client.files.create(
        file=file,
        purpose="fine-tune"
    )

# Create fine-tuning job
job = client.fine_tuning.jobs.create(
    training_file=training_file.id,
    model="gpt-4o-mini-2024-07-18",
    suffix="custom-model-v1",
    hyperparameters={
        "n_epochs": 3
    }
)

print(f"Job created: {job.id}")
print(f"Status: {job.status}")

# Monitor job status
import time
while True:
    job = client.fine_tuning.jobs.retrieve(job.id)
    print(f"Status: {job.status}")
    
    if job.status in ["succeeded", "failed", "cancelled"]:
        break
    
    time.sleep(60)  # Check every minute

if job.status == "succeeded":
    print(f"Fine-tuned model: {job.fine_tuned_model}")

import Portkey from 'portkey-ai';
import fs from 'fs';

const client = new Portkey({
    provider: "openai",
    Authorization: "sk-***"
});

// Upload training file
const trainingFile = await client.files.create({
    file: fs.createReadStream("training_data.jsonl"),
    purpose: "fine-tune"
});

// Create fine-tuning job
const job = await client.fineTuning.jobs.create({
    training_file: trainingFile.id,
    model: "gpt-4o-mini-2024-07-18",
    suffix: "custom-model-v1",
    hyperparameters: {
        n_epochs: 3
    }
});

console.log(`Job created: ${job.id}`);
console.log(`Status: ${job.status}`);

// Monitor job status
const checkJob = async () => {
    while (true) {
        const updatedJob = await client.fineTuning.jobs.retrieve(job.id);
        console.log(`Status: ${updatedJob.status}`);
        
        if (["succeeded", "failed", "cancelled"].includes(updatedJob.status)) {
            if (updatedJob.status === "succeeded") {
                console.log(`Fine-tuned model: ${updatedJob.fine_tuned_model}`);
            }
            break;
        }
        
        await new Promise(resolve => setTimeout(resolve, 60000));
    }
};

checkJob();

Response Example

{
  "id": "ftjob-abc123",
  "object": "fine_tuning.job",
  "model": "gpt-4o-mini-2024-07-18",
  "created_at": 1713894800,
  "finished_at": null,
  "fine_tuned_model": null,
  "organization_id": "org-123",
  "result_files": [],
  "status": "created",
  "training_file": "file-abc123",
  "validation_file": null,
  "hyperparameters": {
    "n_epochs": "auto"
  },
  "trained_tokens": null
}

List Fine-tuning Jobs

GET /v1/fine_tuning/jobs?limit=10

Returns a paginated list of fine-tuning jobs.

Retrieve Fine-tuning Job

GET /v1/fine_tuning/jobs/ftjob-abc123

Get details about a specific job, including current status and progress.

Cancel Fine-tuning Job

POST /v1/fine_tuning/jobs/ftjob-abc123/cancel

Cancel a job that is in progress. The job status will change to cancelled.

Using the Fine-tuned Model

Once training completes, use your fine-tuned model:

from portkey_ai import Portkey

client = Portkey(
    provider="openai",
    Authorization="sk-***"
)

response = client.chat.completions.create(
    model="ft:gpt-4o-mini-2024-07-18:org-name:custom-model-v1:abc123",
    messages=[
        {"role": "user", "content": "Hello!"}
    ]
)

print(response.choices[0].message.content)

Best Practices

Training Data Quality

Provide at least 50-100 high-quality examples
Ensure examples are diverse and representative
Follow the same format across all examples
Include a system message if needed for your use case

Hyperparameter Tuning

Start with default (auto) hyperparameters
Monitor validation loss to detect overfitting
Adjust n_epochs if the model isn’t learning enough or is overfitting
Use validation data to evaluate performance

Cost Management

Training costs are based on the number of tokens in your training data
Start with a small dataset to validate your approach
Fine-tuning is typically 10-20x the cost of inference
Consider if prompt engineering can achieve similar results first

Model Versioning

Use the suffix parameter to create meaningful model names
Keep track of which training data was used for each model
Test new models thoroughly before replacing production models

Provider Support

Fine-tuning support varies by provider. Currently supported:

OpenAI: GPT-4, GPT-3.5 Turbo
Azure OpenAI: Same models as OpenAI

Check provider documentation for specific model availability.

Upload File

Upload training data

Chat Completions

Use your fine-tuned model

Provider Guide

Provider-specific details

Overview

Models

Messages

Chat

Completions

Embeddings

Images

Audio

Files

Batches

Fine-tuning

Realtime

Fine-tuning API

Endpoints

Create Fine-tuning Job

List Fine-tuning Jobs

Retrieve Fine-tuning Job

Cancel Fine-tuning Job

Authentication

Create Fine-tuning Job

Request Parameters

Response

Example

Training Data Format

Response Example

List Fine-tuning Jobs

Retrieve Fine-tuning Job

Cancel Fine-tuning Job

Using the Fine-tuned Model

Best Practices

Provider Support

Upload File

Chat Completions

Provider Guide

​Fine-tuning API

​Endpoints

​Create Fine-tuning Job

​List Fine-tuning Jobs

​Retrieve Fine-tuning Job

​Cancel Fine-tuning Job

​Authentication

​Create Fine-tuning Job

​Request Parameters

​Response

​Example

​Training Data Format

​Response Example

​List Fine-tuning Jobs

​Retrieve Fine-tuning Job

​Cancel Fine-tuning Job

​Using the Fine-tuned Model

​Best Practices

​Provider Support

​Related Resources

Upload File

Chat Completions

Provider Guide

Fine-tuning API

Endpoints

Create Fine-tuning Job

List Fine-tuning Jobs

Retrieve Fine-tuning Job

Cancel Fine-tuning Job

Authentication

Create Fine-tuning Job

Request Parameters

Response

Example

Training Data Format

Response Example

List Fine-tuning Jobs

Retrieve Fine-tuning Job

Cancel Fine-tuning Job

Using the Fine-tuned Model

Best Practices

Provider Support

Related Resources