> ## Documentation Index
> Fetch the complete documentation index at: https://docs.labelbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrate Fireworks models

> Connect models hosted on Fireworks to Labelbox Foundry for response generation, data enrichment, and model-assisted labeling.

Bring models hosted on [Fireworks](https://fireworks.ai/) into your Labelbox workflows through a custom model integration. Use Fireworks for inference and Labelbox Foundry to select data, configure prompts, inspect predictions, and send results for human review.

Fireworks provides access to open models through an [OpenAI-compatible API](https://docs.fireworks.ai/tools-sdks/openai-compatibility), with serverless and dedicated deployment options. This guide focuses on text generation with the [Chat Completions API](https://docs.fireworks.ai/api-reference/post-chatcompletions).

## What you can build

* **Response generation:** Generate responses on your own datasets and review how a model handles domain-specific questions.
* **Data enrichment:** Summarize documents, extract information, or categorize text before further curation.
* **Model-assisted labeling:** Generate candidate labels, then send predictions to Annotate for human review and correction.
* **Model comparison:** Run different Fireworks-hosted models on the same data to compare output quality for your use case.

## Before you begin

You need:

* A Labelbox enterprise plan with access to [custom model integrations](https://docs.labelbox.com/horizon/guides/custom-model-integration.md). [Contact sales](https://labelbox.com/sales/) for plan options.
* A Fireworks account, an API key, and access to a text-generation model.
* Data in Labelbox Catalog and, for labeling tasks, an ontology that defines the expected predictions.
* An HTTPS adapter endpoint that you host and make accessible to Labelbox.

> [!NOTE]
>
> Fireworks' OpenAI-compatible API and Labelbox's custom model endpoint use different request and response formats. Register your adapter URL in Labelbox, not the Fireworks Chat Completions URL. The adapter translates requests, calls Fireworks, and returns predictions in Labelbox's expected format.

## Set up Fireworks

1. Sign in to Fireworks and [create an API key](https://app.fireworks.ai/settings/users/api-keys).
2. Choose a model from the [Fireworks model library](https://fireworks.ai/models). Copy its full model identifier from the model's API example rather than its display name.
3. Confirm that the model is available through [serverless inference](https://docs.fireworks.ai/serverless/overview), or [create a dedicated deployment](https://docs.fireworks.ai/getting-started/ondemand-quickstart) and use the model identifier supplied for that deployment.
4. Store the API key as a secret in your adapter's hosting environment. Do not put it in prompts, data rows, or client-side code.

### Check access to your model

Use a small request to verify your Fireworks credentials and model selection before connecting Labelbox. Set `FIREWORKS_API_KEY` and `FIREWORKS_MODEL` in your local environment; use the exact model identifier from Fireworks.

```bash theme={"theme":"css-variables"}
curl --fail-with-body https://api.fireworks.ai/inference/v1/chat/completions \
  --header "Authorization: Bearer ${FIREWORKS_API_KEY}" \
  --header "Content-Type: application/json" \
  --data "$(jq -n --arg model "$FIREWORKS_MODEL" '{
    model: $model,
    messages: [
      {role: "user", content: "Summarize the purpose of data labeling in one sentence."}
    ],
    max_tokens: 128,
    stream: false
  }')"
```

This example requires `curl` and `jq`. A successful response includes generated text in `choices[0].message.content`. This check calls Fireworks directly; it does not test your Labelbox adapter. Fireworks usage is subject to your account's billing and rate limits.

## Connect the APIs with an adapter

The integration follows this request path:

```text theme={"theme":"css-variables"}
Labelbox Foundry → Your HTTPS adapter → Fireworks Chat Completions API
                ← Labelbox prediction ← Generated model response
```

Configure your adapter with these Fireworks settings:

| Setting | Value |
| - | - |
| OpenAI-compatible base URL | `https://api.fireworks.ai/inference/v1` |
| Chat Completions endpoint | `https://api.fireworks.ai/inference/v1/chat/completions` |
| Authentication | `Authorization: Bearer <FIREWORKS_API_KEY>` |
| Model | The full identifier from your selected model or deployment |
| Streaming | `false`; return a completed prediction to Labelbox |

### Translate the request

Labelbox sends messages in `prompt`, with each message containing a `role` and ordered `parts`. For a text-only integration, map each message to a Fireworks `messages` entry, preserve its role, and combine its text parts in order.

For example, this Labelbox request:

```json theme={"theme":"css-variables"}
{
  "prompt": [
    {
      "role": "system",
      "parts": [{ "text": "Summarize each document in one sentence." }]
    },
    {
      "role": "user",
      "parts": [{ "text": "The customer received a damaged item and requested a replacement." }]
    }
  ]
}
```

becomes a Fireworks request with this message list, plus your configured `model` and generation parameters:

```json theme={"theme":"css-variables"}
{
  "messages": [
    {
      "role": "system",
      "content": "Summarize each document in one sentence."
    },
    {
      "role": "user",
      "content": "The customer received a damaged item and requested a replacement."
    }
  ]
}
```

Validate incoming payloads and reject unsupported input types rather than silently dropping them. This text-only mapping does not handle image parts. To use a vision-capable Fireworks model, extend the adapter to translate images into the model's supported input format.

### Return a Labelbox prediction

Extract the generated text from `choices[0].message.content`. Return the prediction format required by your Labelbox task, not the full Fireworks response object.

For an ontology with a free-text feature named `summary`, an adapter can return a prediction shaped like this:

```json theme={"theme":"css-variables"}
{
  "summary": "The customer requested a replacement for a damaged item."
}
```

The key must match the feature name in your ontology. For radio or checklist classifications, validate that generated labels match the ontology's allowed values. See the [custom model response formats](https://docs.labelbox.com/horizon/guides/custom-model-integration.md#response) for other task types.

Before deploying the adapter, configure authentication, request timeouts, and error handling. Keep the Fireworks API key on the server. Surface upstream failures as errors rather than saving an error message as a successful prediction, and use bounded retries with backoff for transient failures or rate limits.

## Add the model to Labelbox

1. Open [Models](https://app.labelbox.com/mea), click **Create**, and select **Custom Model**.
2. Select the data type supported by your adapter. For this text-only workflow, use text data.
3. Give the model a descriptive name, such as `Fireworks — document summarization`.
4. Set **HTTP endpoint** to your deployed adapter URL.
5. If your adapter requires a secret, configure **Secret** for the adapter's authentication. This is separate from the Fireworks API key stored by your adapter.
6. Add a description that records the Fireworks model identifier and intended task, then click **Create model**.

On the model's **Settings** tab, document the supported inputs and outputs in its Readme. Set a rate limit appropriate for your adapter capacity and Fireworks account limits. When changing models, verify the new model's context length, input support, and generation parameters before running it on a full dataset.

## Generate and review predictions

1. Click **+ Model run** on your custom model and select a small set of representative data rows.
2. Configure the prompt and, when required, select an ontology that matches your adapter's output.
3. [Generate a preview](https://docs.labelbox.com/horizon/guides/foundry-define-model-run#generate-previews) and confirm that the predictions contain the expected text or labels.
4. Submit the model run, then [inspect predictions in Catalog](https://docs.labelbox.com/horizon/guides/foundry-view-predictions).
5. [Send predictions to Annotate](https://docs.labelbox.com/horizon/guides/foundry-annotate-predictions) for human review, or [export predictions](https://docs.labelbox.com/horizon/guides/export-predictions.md) for downstream workflows.

For model comparisons, keep the dataset, prompt, and output schema consistent across runs. Record the Fireworks model identifier and adapter configuration so you can interpret the results later.

> [!WARNING]
>
> Bounding box and mask tasks are not supported by the self-serve custom model integration flow. See [custom integrations for bounding box and mask tasks](https://docs.labelbox.com/horizon/guides/custom-model-integration.md#create-model-integrations-for-bounding-box-and-mask-tasks) for the separate onboarding process.

## Troubleshooting

| Symptom | What to check |
| - | - |
| Authentication fails | Check adapter authentication separately from the Fireworks API key. Confirm that the adapter sends the Fireworks key as a bearer token. |
| Fireworks cannot find the model | Copy the exact model identifier from Fireworks and confirm serverless availability or deployment access. |
| Requests are rate-limited | Reduce the custom model's rate limit on its **Settings** tab and check Fireworks account limits. Apply bounded retries with backoff in the adapter. |
| Requests time out | Test the adapter independently, reduce input or output length, and review inference latency and endpoint timeout settings. |
| Predictions are missing or malformed | Check the `prompt`-to-`messages` mapping and ensure the adapter returns Labelbox predictions, not the Fireworks response envelope. |
| Labels do not match the ontology | Validate feature names and allowed classification values before returning a prediction. |

## Next steps

> **[Fireworks documentation](https://docs.fireworks.ai/)**
>
> Explore model availability, deployment options, and API configuration.

> **[Custom model integration](https://docs.labelbox.com/horizon/guides/custom-model-integration.md)**
>
> Review the complete Labelbox endpoint contract and supported prediction formats.