--- title: Fireworks description: Learn how to use Fireworks with AI Gateway and the direct provider. url: "https://ai-sdk.dev/providers/ai-sdk-providers/fireworks" docs_index: /llms.txt --- > For an index of all documentation, see [/llms.txt](/llms.txt). [Fireworks](https://fireworks.ai/) is a platform for running and testing LLMs through their [API](https://readme.fireworks.ai/). Start with [AI Gateway](/providers/ai-sdk-providers/ai-gateway) for models in its catalog (recommended), or use `@ai-sdk/fireworks` to connect directly to Fireworks. ```ts provider="fireworks" model="openai/gpt-oss-120b" import { generateText } from 'ai'; const { text } = await generateText({ model: "openai/gpt-oss-120b", prompt: 'Write a vegetarian lasagna recipe for 4 people.', providerOptions: { gateway: { order: ['fireworks'], }, }, }); console.log(text); ``` ## Using AI Gateway The AI SDK uses AI Gateway by default for model strings. Gateway provides access to models across providers through a single API key, with usage and cost tracking. Install `ai`: ```bash pnpm add ai ``` Set an [AI Gateway API key](https://vercel.com/docs/ai-gateway/getting-started) in your environment: ```bash export AI_GATEWAY_API_KEY=your_api_key_here ``` Vercel deployments can also use [OIDC authentication](/providers/ai-sdk-providers/ai-gateway#oidc-authentication-vercel-deployments). See the [AI Gateway provider documentation](/providers/ai-sdk-providers/ai-gateway) for configuration and the [model catalog](https://vercel.com/ai-gateway/models) for available models. The example sets `providerOptions.gateway.order` to `['fireworks']`. This sends the request to Fireworks first, then falls back to other available providers of the same model if Fireworks is unavailable or the request fails. `order` sets a preference; it does not restrict fallback to Fireworks. See [provider ordering](https://vercel.com/docs/ai-gateway/models-and-providers/provider-filtering-and-ordering). The dropdown lists models served by Fireworks through Gateway with a corresponding direct-provider example. Provider availability depends on the model and your team's [Provider Allowlist](https://vercel.com/docs/ai-gateway/models-and-providers/provider-filtering-and-ordering). ## Using `@ai-sdk/fireworks` For direct access to Fireworks, install `ai` and `@ai-sdk/fireworks`: ```bash pnpm add ai @ai-sdk/fireworks ``` Set your Fireworks API credential in the `FIREWORKS_API_KEY` environment variable: ```bash export FIREWORKS_API_KEY=your_api_key_here ``` AI Gateway does not expose every API in `@ai-sdk/fireworks`. Use the direct provider for provider-specific APIs or custom connection settings. The following sections document the direct `@ai-sdk/fireworks` provider, including its model factories and settings. Gateway model and feature availability can differ. ## Provider Instance You can import the default provider instance `fireworks` from `@ai-sdk/fireworks`: ```ts 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: ```ts import { createFireworks } from '@ai-sdk/fireworks'; const fireworks = createFireworks({ apiKey: process.env.FIREWORKS_API_KEY ?? '', }); ``` 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\* Custom headers to include in the requests. - **fetch** *(input: RequestInfo, init?: RequestInit) => Promise\* Custom [fetch](https://developer.mozilla.org/en-US/docs/Web/API/fetch) implementation. ## Language Models You can create [Fireworks models](https://fireworks.ai/models) using a provider instance. The first argument is the model id, e.g. `accounts/fireworks/models/firefunction-v1`: ```ts const model = fireworks('accounts/fireworks/models/firefunction-v1'); ``` ### Reasoning Models For models that support reasoning effort, use the top-level `reasoning` parameter. Fireworks maps `'minimal'` to `'low'` and `'xhigh'` or `'max'` to `'high'`, returning a compatibility warning whenever it coerces the effort. Streaming calls include the warning in the `stream-start` event. Explicit `providerOptions.fireworks.reasoningEffort` takes precedence over the top-level setting. Fireworks exposes the thinking of `deepseek-r1` in the generated text using the `` tag. You can use the `extractReasoningMiddleware` to extract this reasoning and expose it as a `reasoning` property on the result: ```ts import { fireworks } from '@ai-sdk/fireworks'; import { wrapLanguageModel, extractReasoningMiddleware } from 'ai'; const enhancedModel = wrapLanguageModel({ model: fireworks('accounts/fireworks/models/deepseek-r1'), middleware: extractReasoningMiddleware({ tagName: 'think' }), }); ``` 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: ```ts import { fireworks } from '@ai-sdk/fireworks'; import { generateText } from 'ai'; const { text } = await generateText({ model: fireworks('accounts/fireworks/models/firefunction-v1'), prompt: 'Write a vegetarian lasagna recipe for 4 people.', }); ``` Fireworks language models can also be used in the `streamText` function (see [AI SDK Core](/docs/ai-sdk-core)). ### Provider Options Fireworks chat models support additional provider options that are not part of the [standard call settings](/docs/ai-sdk-core/settings). You can pass them in the `providerOptions` argument: ```ts import { fireworks, type FireworksLanguageModelOptions, } from '@ai-sdk/fireworks'; import { generateText } from 'ai'; const { text, reasoningText } = await generateText({ model: fireworks('accounts/fireworks/models/kimi-k2p6'), providerOptions: { fireworks: { thinking: { type: 'enabled', budgetTokens: 4096 }, reasoningHistory: 'interleaved', } satisfies FireworksLanguageModelOptions, }, prompt: 'How many "r"s are in the word "strawberry"?', }); ``` 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](https://docs.fireworks.ai/guides/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`](https://docs.fireworks.ai/api-reference/post-chatcompletions) 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: ```ts import { fireworks, type FireworksLanguageModelOptions, } from '@ai-sdk/fireworks'; import { generateText, isStepCount, tool } from 'ai'; import { z } from 'zod'; const sessionId = 'conversation-123'; const result = await generateText({ model: fireworks('accounts/fireworks/models/kimi-k2p6'), providerOptions: { fireworks: { promptCacheKey: sessionId, } satisfies FireworksLanguageModelOptions, }, tools: { weather: tool({ description: 'Get the weather for a city.', inputSchema: z.object({ city: z.string() }), execute: async ({ city }) => `It is sunny in ${city}.`, }), }, stopWhen: isStepCount(5), prompt: 'What is the weather in San Francisco?', }); 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: ```ts import { fireworks, type FireworksLanguageModelOptions, } from '@ai-sdk/fireworks'; import { ToolLoopAgent } from 'ai'; import { z } from 'zod'; import { weatherTool } from './weather-tool'; const agent = new ToolLoopAgent({ model: fireworks('accounts/fireworks/models/kimi-k2p6'), callOptionsSchema: z.object({ sessionId: z.string(), }), prepareCall: ({ options, ...settings }) => ({ ...settings, providerOptions: { fireworks: { promptCacheKey: options.sessionId, } satisfies FireworksLanguageModelOptions, }, }), tools: { weather: weatherTool }, }); const result = await agent.generate({ prompt: 'What is the weather in San Francisco?', options: { sessionId: 'conversation-123', }, }); ``` Use non-identifying values for cache keys rather than email addresses or other personal information. ### Priority Service Tier [Fireworks Priority tier](https://docs.fireworks.ai/serverless/serving-paths) prioritizes supported models above Standard traffic. Set `serviceTier` to `'priority'` to send Fireworks' `service_tier` request field: ```ts import { fireworks, type FireworksLanguageModelOptions, } from '@ai-sdk/fireworks'; import { generateText } from 'ai'; const result = await generateText({ model: fireworks('accounts/fireworks/models/glm-5p2'), providerOptions: { fireworks: { serviceTier: 'priority', } satisfies FireworksLanguageModelOptions, }, prompt: 'Write a haiku about reliable inference.', }); ``` ### Completion Models You can create models that call the Fireworks completions API using the `.completionModel()` factory method: ```ts const model = fireworks.completionModel( 'accounts/fireworks/models/firefunction-v1', ); ``` ### Model Capabilities | Model | Image Input | Object Generation | Tool Usage | Tool Streaming | | ---------------------------------------------------------- | ----------- | ----------------- | ---------- | -------------- | | `accounts/fireworks/models/firefunction-v1` | ✗ | ✓ | ✓ | ✓ | | `accounts/fireworks/models/deepseek-r1` | ✗ | ✓ | ✗ | ✗ | | `accounts/fireworks/models/deepseek-v3` | ✗ | ✓ | ✓ | ✗ | | `accounts/fireworks/models/llama-v3p1-405b-instruct` | ✗ | ✓ | ✓ | ✓ | | `accounts/fireworks/models/llama-v3p1-8b-instruct` | ✗ | ✓ | ✓ | ✗ | | `accounts/fireworks/models/llama-v3p2-3b-instruct` | ✗ | ✓ | ✓ | ✗ | | `accounts/fireworks/models/llama-v3p3-70b-instruct` | ✗ | ✓ | ✓ | ✗ | | `accounts/fireworks/models/mixtral-8x7b-instruct` | ✗ | ✓ | ✓ | ✗ | | `accounts/fireworks/models/mixtral-8x7b-instruct-hf` | ✗ | ✓ | ✓ | ✗ | | `accounts/fireworks/models/mixtral-8x22b-instruct` | ✗ | ✓ | ✓ | ✗ | | `accounts/fireworks/models/qwen2p5-coder-32b-instruct` | ✗ | ✓ | ✓ | ✗ | | `accounts/fireworks/models/qwen2p5-72b-instruct` | ✗ | ✓ | ✓ | ✗ | | `accounts/fireworks/models/qwen-qwq-32b-preview` | ✗ | ✓ | ✗ | ✗ | | `accounts/fireworks/models/qwen2-vl-72b-instruct` | ✓ | ✓ | ✗ | ✗ | | `accounts/fireworks/models/llama-v3p2-11b-vision-instruct` | ✓ | ✓ | ✓ | ✗ | | `accounts/fireworks/models/qwq-32b` | ✗ | ✓ | ✗ | ✗ | | `accounts/fireworks/models/yi-large` | ✗ | ✓ | ✓ | ✗ | | `accounts/fireworks/models/kimi-k2-instruct` | ✗ | ✓ | ✓ | ✗ | | `accounts/fireworks/models/kimi-k2-thinking` | ✗ | ✓ | ✓ | ✗ | | `accounts/fireworks/models/kimi-k2p6` | ✓ | ✓ | ✓ | ✗ | | `accounts/fireworks/models/minimax-m2` | ✗ | ✓ | ✓ | ✗ | The table above lists popular models. Please see the [Fireworks models page](https://fireworks.ai/models) for a full list of available models. ## Embedding Models You can create models that call the Fireworks embeddings API using the `.embeddingModel()` factory method: ```ts const model = fireworks.embeddingModel('nomic-ai/nomic-embed-text-v1.5'); ``` You can use Fireworks embedding models to generate embeddings with the `embed` function: ```ts import { fireworks } from '@ai-sdk/fireworks'; import { embed } from 'ai'; const { embedding } = await embed({ model: fireworks.embeddingModel('nomic-ai/nomic-embed-text-v1.5'), value: 'sunny day at the beach', }); ``` ### Model Capabilities | Model | Dimensions | Max Tokens | | -------------------------------- | ---------- | ---------- | | `nomic-ai/nomic-embed-text-v1.5` | 768 | 8192 | For more embedding models, see the [Fireworks models page](https://fireworks.ai/models) for a full list of available models. ## Image Models You can create Fireworks image models using the `.image()` factory method. For more on image generation with the AI SDK see [generateImage()](/docs/reference/ai-sdk-core/generate-image). ```ts import { fireworks, type FireworksImageModelOptions } from '@ai-sdk/fireworks'; import { generateImage } from 'ai'; const { image } = await generateImage({ model: fireworks.image('accounts/fireworks/models/flux-1-dev-fp8'), prompt: 'A futuristic cityscape at sunset', aspectRatio: '16:9', providerOptions: { fireworks: { guidance_scale: 4.5, num_inference_steps: 8, } satisfies FireworksImageModelOptions, }, }); ``` Model support for `size` and `aspectRatio` parameters varies. See the [Model Capabilities](#model-capabilities-1) section below for supported dimensions, or check the model's documentation on [Fireworks models page](https://fireworks.ai/models) for more details. ### 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. Fireworks Kontext models do not support explicit masks. Editing is prompt-driven — describe what you want to change in the text prompt. #### Basic Image Editing Transform an existing image using text prompts: ```ts const imageBuffer = readFileSync('./input-image.png'); const { images } = await generateImage({ model: fireworks.image('accounts/fireworks/models/flux-kontext-pro'), prompt: { text: 'Turn the cat into a golden retriever dog', images: [imageBuffer], }, providerOptions: { fireworks: { output_format: 'jpeg', safety_tolerance: 2, } satisfies FireworksImageModelOptions, }, }); ``` #### Style Transfer Apply artistic styles to an image: ```ts const imageBuffer = readFileSync('./input-image.png'); const { images } = await generateImage({ model: fireworks.image('accounts/fireworks/models/flux-kontext-pro'), prompt: { text: 'Transform this into a watercolor painting style', images: [imageBuffer], }, aspectRatio: '1:1', }); ``` Input images can be provided as `Buffer`, `ArrayBuffer`, `Uint8Array`, or base64-encoded strings. Fireworks only supports a single input image per request. ### 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` | Model | Dimensions Specification | Image Editing | | ------------------------------------------------------------ | ------------------------ | ------------- | | `accounts/fireworks/models/flux-kontext-pro` | Aspect Ratio | ✓ | | `accounts/fireworks/models/flux-kontext-max` | Aspect Ratio | ✓ | | `accounts/fireworks/models/flux-1-dev-fp8` | Aspect Ratio | ✗ | | `accounts/fireworks/models/flux-1-schnell-fp8` | Aspect Ratio | ✗ | | `accounts/fireworks/models/playground-v2-5-1024px-aesthetic` | Size | ✗ | | `accounts/fireworks/models/japanese-stable-diffusion-xl` | Size | ✗ | | `accounts/fireworks/models/playground-v2-1024px-aesthetic` | Size | ✗ | | `accounts/fireworks/models/SSD-1B` | Size | ✗ | | `accounts/fireworks/models/stable-diffusion-xl-1024-v1-0` | Size | ✗ | For more details, see the [Fireworks models page](https://fireworks.ai/models). #### 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: | Model ID | | -------------------------------------- | | `accounts/stability/models/sd3-turbo` | | `accounts/stability/models/sd3-medium` | | `accounts/stability/models/sd3` | --- For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md) For an index of all available documentation, see [/llms.txt](/llms.txt) For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)