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

training_file

string

required

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

model

string

required

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

validation_file

string

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

hyperparameters

object

Training hyperparameters

Show hyperparameters object

n_epochs

integer

Number of training epochs (default: auto)

batch_size

integer

Batch size for training (default: auto)

learning_rate_multiplier

number

Learning rate multiplier (default: auto)

suffix

string

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

Response

string

The fine-tuning job identifier

object

string

The object type, always “fine_tuning.job”

model

string

The base model being fine-tuned

created_at

integer

Unix timestamp of when the job was created

finished_at

integer

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

fine_tuned_model

string

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

status

string

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

training_file

string

The ID of the training file

validation_file

string

The ID of the validation file (if provided)

hyperparameters

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"
  }'

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

Build docs developers (and LLMs) love

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

​Related Resources

Upload File

Chat Completions

Provider Guide

Build docs developers (and LLMs) love

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