Integrate Fireworks models

Bring models hosted on Fireworks 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, with serverless and dedicated deployment options. This guide focuses on text generation with the Chat Completions API.

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. Contact 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.

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

Sign in to Fireworks and create an API key.
Choose a model from the Fireworks model library. Copy its full model identifier from the model’s API example rather than its display name.
Confirm that the model is available through serverless inference, or create a dedicated deployment and use the model identifier supplied for that deployment.
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.

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:

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:

{
  "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:

{
  "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:

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

Open Models, click Create, and select Custom Model.
Select the data type supported by your adapter. For this text-only workflow, use text data.
Give the model a descriptive name, such as Fireworks — document summarization.
Set HTTP endpoint to your deployed adapter URL.
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.
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

Click + Model run on your custom model and select a small set of representative data rows.
Configure the prompt and, when required, select an ontology that matches your adapter’s output.
Generate a preview and confirm that the predictions contain the expected text or labels.
Submit the model run, then inspect predictions in Catalog.
Send predictions to Annotate for human review, or export predictions 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.

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

Explore model availability, deployment options, and API configuration.

Custom model integration

Review the complete Labelbox endpoint contract and supported prediction formats.

Getting started

Integrations

Label data

Manage data

Explore data

Manage models

Manage team

Access & usage

Updates

Integrate Fireworks models

What you can build

Before you begin

Set up Fireworks

Check access to your model

Connect the APIs with an adapter

Translate the request

Return a Labelbox prediction

Add the model to Labelbox

Generate and review predictions

Troubleshooting

Next steps

Fireworks documentation

Custom model integration

​What you can build

​Before you begin

​Set up Fireworks

​Check access to your model

​Connect the APIs with an adapter

​Translate the request

​Return a Labelbox prediction

​Add the model to Labelbox

​Generate and review predictions

​Troubleshooting

​Next steps

Fireworks documentation

Custom model integration

What you can build

Before you begin

Set up Fireworks

Check access to your model

Connect the APIs with an adapter

Translate the request

Return a Labelbox prediction

Add the model to Labelbox

Generate and review predictions

Troubleshooting

Next steps