Fireworks Provider

Fireworks is a platform for running and testing LLMs through their API.

Setup

The Fireworks provider is available via the @ai-sdk/fireworks module. You can install it with

pnpm add @ai-sdk/fireworks

Provider Instance

You can import the default provider instance fireworks from @ai-sdk/fireworks:

1
import { fireworks } from '@ai-sdk/fireworks';

If you need a customized setup, you can import createFireworks from @ai-sdk/fireworks and create a provider instance with your settings:

1
import { createFireworks } from '@ai-sdk/fireworks';
2

3
const fireworks = createFireworks({
4
  apiKey: process.env.FIREWORKS_API_KEY ?? '',
5
});

You can use the following optional settings to customize the Fireworks provider instance:

• baseURL string

  Use a different URL prefix for API calls, e.g. to use proxy servers. The default prefix is https://api.fireworks.ai/inference/v1.

• apiKey string

  API key that is being sent using the Authorization header. It defaults to the FIREWORKS_API_KEY environment variable.

• headers Record<string,string>

  Custom headers to include in the requests.

• fetch (input: RequestInfo, init?: RequestInit) => Promise<Response>

  Custom fetch implementation.

Language Models

You can create Fireworks models using a provider instance. The first argument is the model id, e.g. accounts/fireworks/models/firefunction-v1:

1
const model = fireworks('accounts/fireworks/models/firefunction-v1');

Reasoning Models

Fireworks exposes the thinking of deepseek-r1 in the generated text using the <think> tag. You can use the extractReasoningMiddleware to extract this reasoning and expose it as a reasoning property on the result:

1
import { fireworks } from '@ai-sdk/fireworks';
2
import { wrapLanguageModel, extractReasoningMiddleware } from 'ai';
3

4
const enhancedModel = wrapLanguageModel({
5
  model: fireworks('accounts/fireworks/models/deepseek-r1'),
6
  middleware: extractReasoningMiddleware({ tagName: 'think' }),
7
});

You can then use that enhanced model in functions like generateText and streamText.

Example

You can use Fireworks language models to generate text with the generateText function:

1
import { fireworks } from '@ai-sdk/fireworks';
2
import { generateText } from 'ai';
3

4
const { text } = await generateText({
5
  model: fireworks('accounts/fireworks/models/firefunction-v1'),
6
  prompt: 'Write a vegetarian lasagna recipe for 4 people.',
7
});

Fireworks language models can also be used in the streamText function (see AI SDK Core).

Provider Options

Fireworks chat models support additional provider options that are not part of the standard call settings. You can pass them in the providerOptions argument:

1
import {
2
  fireworks,
3
  type FireworksLanguageModelOptions,
4
} from '@ai-sdk/fireworks';
5
import { generateText } from 'ai';
6

7
const { text, reasoningText } = await generateText({
8
  model: fireworks('accounts/fireworks/models/kimi-k2p6'),
9
  providerOptions: {
10
    fireworks: {
11
      thinking: { type: 'enabled', budgetTokens: 4096 },
12
      reasoningHistory: 'interleaved',
13
    } satisfies FireworksLanguageModelOptions,
14
  },
15
  prompt: 'How many "r"s are in the word "strawberry"?',
16
});

The following optional provider options are available for Fireworks chat models:

• promptCacheKey string

  A stable, opaque key that improves prompt cache hit rates by routing requests with shared prompt prefixes to the same Fireworks replica. Reuse the same key for all steps and calls in one conversation, and use different keys for unrelated conversations.

• serviceTier 'priority'

  Uses the Fireworks Priority serving path for higher reliability during peak traffic. The provider sends it as Fireworks' service_tier request field.

• thinking object

  Configuration for thinking/reasoning models like Kimi K2.6.

  • type 'enabled' | 'disabled'

    Whether to enable thinking mode.

  • budgetTokens number

    Maximum number of tokens for thinking (minimum 1024).

• reasoningHistory 'disabled' | 'interleaved' | 'preserved'

  Controls how reasoning history is handled in multi-turn conversations:

  • 'disabled': Remove reasoning from history
  • 'interleaved': Include reasoning between tool calls within a single turn
  • 'preserved': Keep all reasoning in history

Prompt Cache Affinity

Fireworks prompt caching is automatic, but cached prefixes are local to a replica. Set promptCacheKey to an opaque session or conversation identifier to improve cache affinity. The provider sends it as Fireworks' prompt_cache_key request field.

The AI SDK reuses the same provider options for every model step in a multi-step generateText or streamText call, so one key covers the complete tool loop:

1
import {
2
  fireworks,
3
  type FireworksLanguageModelOptions,
4
} from '@ai-sdk/fireworks';
5
import { generateText, isStepCount, tool } from 'ai';
6
import { z } from 'zod';
7

8
const sessionId = 'conversation-123';
9

10
const result = await generateText({
11
  model: fireworks('accounts/fireworks/models/kimi-k2p6'),
12
  providerOptions: {
13
    fireworks: {
14
      promptCacheKey: sessionId,
15
    } satisfies FireworksLanguageModelOptions,
16
  },
17
  tools: {
18
    weather: tool({
19
      description: 'Get the weather for a city.',
20
      inputSchema: z.object({ city: z.string() }),
21
      execute: async ({ city }) => `It is sunny in ${city}.`,
22
    }),
23
  },
24
  stopWhen: isStepCount(5),
25
  prompt: 'What is the weather in San Francisco?',
26
});
27

28
console.log(result.usage.inputTokenDetails.cacheReadTokens);

For a reusable ToolLoopAgent, use call options to supply a key for each conversation. Pass the same key again for later agent calls that continue that conversation:

1
import {
2
  fireworks,
3
  type FireworksLanguageModelOptions,
4
} from '@ai-sdk/fireworks';
5
import { ToolLoopAgent } from 'ai';
6
import { z } from 'zod';
7
import { weatherTool } from './weather-tool';
8

9
const agent = new ToolLoopAgent({
10
  model: fireworks('accounts/fireworks/models/kimi-k2p6'),
11
  callOptionsSchema: z.object({
12
    sessionId: z.string(),
13
  }),
14
  prepareCall: ({ options, ...settings }) => ({
15
    ...settings,
16
    providerOptions: {
17
      fireworks: {
18
        promptCacheKey: options.sessionId,
19
      } satisfies FireworksLanguageModelOptions,
20
    },
21
  }),
22
  tools: { weather: weatherTool },
23
});
24

25
const result = await agent.generate({
26
  prompt: 'What is the weather in San Francisco?',
27
  options: {
28
    sessionId: 'conversation-123',
29
  },
30
});

Use non-identifying values for cache keys rather than email addresses or other personal information.

Priority Service Tier

Fireworks Priority tier prioritizes supported models above Standard traffic. Set serviceTier to 'priority' to send Fireworks' service_tier request field:

1
import {
2
  fireworks,
3
  type FireworksLanguageModelOptions,
4
} from '@ai-sdk/fireworks';
5
import { generateText } from 'ai';
6

7
const result = await generateText({
8
  model: fireworks('accounts/fireworks/models/glm-5p2'),
9
  providerOptions: {
10
    fireworks: {
11
      serviceTier: 'priority',
12
    } satisfies FireworksLanguageModelOptions,
13
  },
14
  prompt: 'Write a haiku about reliable inference.',
15
});

Completion Models

You can create models that call the Fireworks completions API using the .completionModel() factory method:

1
const model = fireworks.completionModel(
2
  'accounts/fireworks/models/firefunction-v1',
3
);

Model Capabilities

Embedding Models

You can create models that call the Fireworks embeddings API using the .embeddingModel() factory method:

1
const model = fireworks.embeddingModel('nomic-ai/nomic-embed-text-v1.5');

You can use Fireworks embedding models to generate embeddings with the embed function:

1
import { fireworks } from '@ai-sdk/fireworks';
2
import { embed } from 'ai';
3

4
const { embedding } = await embed({
5
  model: fireworks.embeddingModel('nomic-ai/nomic-embed-text-v1.5'),
6
  value: 'sunny day at the beach',
7
});

Model Capabilities

Image Models

You can create Fireworks image models using the .image() factory method. For more on image generation with the AI SDK see generateImage().

1
import { fireworks, type FireworksImageModelOptions } from '@ai-sdk/fireworks';
2
import { generateImage } from 'ai';
3

4
const { image } = await generateImage({
5
  model: fireworks.image('accounts/fireworks/models/flux-1-dev-fp8'),
6
  prompt: 'A futuristic cityscape at sunset',
7
  aspectRatio: '16:9',
8
  providerOptions: {
9
    fireworks: {
10
      guidance_scale: 4.5,
11
      num_inference_steps: 8,
12
    } satisfies FireworksImageModelOptions,
13
  },
14
});

Provider Options

Fireworks image models support flexible provider options through the providerOptions.fireworks object. Use the FireworksImageModelOptions type to validate known Fireworks image options while still allowing model-specific options to pass through.

The following typed provider options are available:

• guidance_scale number

  Classifier-free guidance scale for the image diffusion process.

• num_inference_steps number

  Number of denoising steps for FLUX workflow image generation.

• output_format 'jpeg' | 'png'

  Desired output format for FLUX Kontext image generation and editing.

• prompt_upsampling boolean

  Whether Fireworks should automatically modify the prompt for more creative generation.

• safety_tolerance number

  Moderation tolerance level for inputs and outputs, from 0 to 6. Fireworks limits image-to-image requests to 2.

• webhook_url string

  URL to receive webhook notifications for async Kontext requests.

• webhook_secret string

  Secret for webhook signature verification.

• cfg_scale number

  Guidance scale for legacy image_generation models.

• steps number

  Number of generation steps for legacy image_generation models.

Image Editing

Fireworks supports image editing through FLUX Kontext models (flux-kontext-pro and flux-kontext-max). Pass input images via prompt.images to transform or edit existing images.

Basic Image Editing

Transform an existing image using text prompts:

1
const imageBuffer = readFileSync('./input-image.png');
2

3
const { images } = await generateImage({
4
  model: fireworks.image('accounts/fireworks/models/flux-kontext-pro'),
5
  prompt: {
6
    text: 'Turn the cat into a golden retriever dog',
7
    images: [imageBuffer],
8
  },
9
  providerOptions: {
10
    fireworks: {
11
      output_format: 'jpeg',
12
      safety_tolerance: 2,
13
    } satisfies FireworksImageModelOptions,
14
  },
15
});

Style Transfer

Apply artistic styles to an image:

1
const imageBuffer = readFileSync('./input-image.png');
2

3
const { images } = await generateImage({
4
  model: fireworks.image('accounts/fireworks/models/flux-kontext-pro'),
5
  prompt: {
6
    text: 'Transform this into a watercolor painting style',
7
    images: [imageBuffer],
8
  },
9
  aspectRatio: '1:1',
10
});

Model Capabilities

For all models supporting aspect ratios, the following aspect ratios are supported:

1:1 (default), 2:3, 3:2, 4:5, 5:4, 16:9, 9:16, 9:21, 21:9

For all models supporting size, the following sizes are supported:

640 x 1536, 768 x 1344, 832 x 1216, 896 x 1152, 1024x1024 (default), 1152 x 896, 1216 x 832, 1344 x 768, 1536 x 640

For more details, see the Fireworks models page.

Stability AI Models

Fireworks also presents several Stability AI models backed by Stability AI API keys and endpoint. The AI SDK Fireworks provider does not currently include support for these models: