​
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"