​
Introduction

This guide walks you through the process of fine-tuning a model using the Fireworks REST API. For an overview of fine-tuning see https://docs.fireworks.ai/fine-tuning/fine-tuning-models

​
Prepare the dataset

Create your dataset file in JSONL format. Each line should be a valid JSON object containing your training examples.

​
Create a dataset record

  • Endpoint: POST /v1/accounts/{account_id}/datasets
  • Request Body: 
    {
  "datasetId": "your-dataset-id",
  "dataset": {
    "userUploaded": {}
  }
}
  • Curl Example: 
    curl -X POST "https://api.fireworks.ai/v1/accounts/{account_id}/datasets" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "datasetId": "your-dataset-id",
    "dataset": {
      "userUploaded": {}
    }
  }'
This will create a record with a dataset id you can use to upload the file.

​
Upload your dataset file

A streamlined file upload API is available for file sizes less than 150 MB.
  • Endpoint: POST /v1/accounts/{account_id}/datasets/{dataset_id}:upload
  • Curl Example:
curl -X POST "https://api.fireworks.ai/v1/accounts/{account_id}/datasets/{dataset_id}:upload" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/your-dataset-file.jsonl"
Post the file using the multipart/form-data format. After this step you can skip to Check the dataset state Alternatively, for larger files, get the signed URL for uploading your file directly to cloud storage.
  • Endpoint: POST /v1/accounts/{account_id}/datasets/{dataset_id}:getUploadEndpoint
  • Request Body: 
    {
  "filenameToSize": {
    "your-dataset-file.jsonl": file_size_in_bytes
  }
}
  • Curl Example: You can use jq to directly extract the signed URL: 
    SIGNED_UPLOAD_URL=$(
  curl -s -X POST "https://api.fireworks.ai/v1/accounts/{account_id}/datasets/{dataset_id}:getUploadEndpoint" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -d '{
      "filenameToSize": {
        "your-dataset-file.jsonl": file_size_in_bytes
      }
    }' | jq -r '.filenameToSignedUrls | to_entries | .[0].value'
)
The response will contain a signed URL that looks similar to this: 
https://storage.googleapis.com/fireworks-models-...

​
Upload your dataset ( Option 2 continued )

Use the following curl command to upload your file: 
curl -X PUT \
  -H "Content-Type: application/octet-stream" \
  -H "x-goog-content-length-range: FILE_SIZE_IN_BYTES,FILE_SIZE_IN_BYTES" \
  --data-binary "@/path/to/your-dataset-file.jsonl" \
  "$SIGNED_UPLOAD_URL"

​
Validate the dataset upload ( Option 2 continued )

  • Endpoint: POST /v1/accounts/{account_id}/datasets/{dataset_id}:validateUpload
  • Curl Example:
  curl -X POST "https://api.fireworks.ai/v1/accounts/{account_id}/datasets/{dataset_id}:validateUpload" \
    -H "Authorization: Bearer YOUR_API_KEY"
Calling validate will finalize the dataset upload.

​
Check the dataset state

  • Endpoint: GET /v1/accounts/{account_id}/datasets/{dataset_id}
  • Curl Example:
  curl -X GET "https://api.fireworks.ai/v1/accounts/{account_id}/datasets/{dataset_id}" \
    -H "Authorization: Bearer YOUR_API_KEY"
After successful creation and upload, the API will set the dataset state to READY

​
Create a fine-tuning job

After uploading your dataset, create a fine-tuning job using the following command:
  • Endpoint: POST /v1/accounts/{account_id}/fineTuningJobs
  • Request Body: 
    {
  "model_id": "optional-model-id",
  "dataset": "accounts/{account_id}/datasets/{dataset_id}",
  "base_model": "accounts/fireworks/models/{base_model_id}",
  "text_completion": {
    "input_template": "### GIVEN THE CONTEXT: {context}  ### INSTRUCTION: {instruction}  ### RESPONSE IS: ",
    "output_template": "ANSWER: {response}"
  }
}
  • Curl Example: 
    curl -X POST "https://api.fireworks.ai/v1/accounts/{account_id}/fineTuningJobs" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model_id": "optional-model-id",
    "dataset": "accounts/{account_id}/datasets/{dataset_id}",
    "base_model": "accounts/fireworks/models/{base_model_id}",
    "text_completion": {
      "input_template": "### GIVEN THE CONTEXT: {context}  ### INSTRUCTION: {instruction}  ### RESPONSE IS: ",
      "output_template": "ANSWER: {response}"
    }
  }'
Adjust the input_template and output_template fields as needed to match your dataset format. By default, the fine-tuning job will generate a random unique ID for the model. This ID is used to refer to the model at inference time. You can optionally choose a custom model_id.

​
Get the job status

  • Endpoint: GET /v1/accounts/{account_id}/fineTuningJobs/{fine_tuning_job_id}
  • Curl Example: 
    curl -X POST "https://api.fireworks.ai/v1/accounts/{account_id}/fineTuningJobs/{fine_tuning_job_id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
The job should now have state PENDING or RUNNING.

​
Deleting a job

  • Endpoint: DELETE /v1/accounts/{account_id}/fineTuningJobs/
  • Curl Example: 
    curl -X DELETE "https://api.fireworks.ai/v1/accounts/{account_id}/fineTuningJobs/{fine_tuning_job_id}" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Downloading model weights

After your fine-tuning job is complete, a model will be created in your account. You can download the model weights using the following steps. If you specified a model_id when creating the fine-tuning job, you can get the model weights directly. You can see a list of models by running.
  • Endpoint: GET /v1/accounts/{account_id}/models/
Use the model_id to get the signed URLs for downloading the model files.
  • Endpoint: GET /v1/accounts/{account_id}/models/{model_id}:getDownloadEndpoint
  • Curl Example: 
    curl -X GET "https://api.fireworks.ai/v1/accounts/{account_id}/models/{model_id}:getDownloadEndpoint" \
  -H "Authorization: Bearer YOUR_API_KEY"
The response will contain a map of filenames to signed URLs for downloading each file. For each file in the response, use the provided signed URL to download the file.
  • Curl Example: 
    curl -o "/path/to/save/model_file.json" "$SIGNED_DOWNLOAD_URL"