Fine-tuning models via API

​

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

​

Option 1 - Upload your dataset file directly (recommended for files < 150MB)

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

​

Option 2 - Upload your file using the signed upload URL (recommended for files > 150MB)

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"