Fireworks AI Python SDK

0.19.20 verified Tue May 12 auth: no python install: verified quickstart: stale

Python SDK and OpenAI-compatible API for running open-source and proprietary LLMs on Fireworks AI infrastructure.

pip install fireworks-ai

Common errors

error AuthenticationError({'fault': {'faultstring': 'Invalid ApiKey', 'detail': {'errorcode': 'oauth.v2.InvalidApiKey'}}}) ↓

cause Your Fireworks AI API key is either incorrect, expired, or has insufficient permissions, preventing authentication with the Fireworks AI service.

fix

Verify your API key from the Fireworks AI dashboard (app.fireworks.ai/api-keys) and ensure it's correctly set in your environment variable (e.g., os.environ["FIREWORKS_API_KEY"] = "<YOUR_API_KEY>") or passed directly to the client/SDK.

error The API endpoint path doesn't exist, the model doesn't exist, the model is not deployed, or you don't have permission to access it. (404 Not Found) ↓

cause The specified model ID in your request is incorrect, deprecated, or you do not have the necessary permissions to access it, resulting in the Fireworks AI service being unable to locate the model.

fix

Double-check the model ID against the official Fireworks AI documentation or model repository (e.g., 'accounts/fireworks/models/llama-v3p1-8b-instruct') and ensure you have access to that specific model.

error AttributeError: module 'openai' has no attribute 'ChatCompletion' ↓

cause This error occurs when you are using an older version of the OpenAI Python SDK (prior to 1.0.0) with Fireworks AI's OpenAI-compatible API, as `ChatCompletion` and other classes were reorganized in OpenAI SDK v1.0.0+.

fix

Upgrade your OpenAI Python SDK to version 1.0.0 or higher (pip install --upgrade openai) and adjust your code to use the new client structure, typically client.chat.completions.create() instead of openai.ChatCompletion.create().

error 400 Bad Request: {'error': {'object': 'error', 'type': 'invalid_request_error', 'code': 'invalid_request_error', 'message': "2 request validation errors: Extra inputs are not permitted, field: 'messages[2].tool_calls[0].call_id'"}} ↓

cause You are sending non-standard or extra fields (like `call_id` or `response_item_id` within `tool_calls`) in your chat completions payload, which is not strictly compatible with Fireworks AI's OpenAI-compatible API.

fix

Remove any non-standard or extra fields from your API request payload, especially within messages[*].tool_calls[*], to align with the strict OpenAI chat completions schema.

error ValueError: Provider 'fireworks-ai' not supported. Available providers: ['fal-ai', 'hf-inference', 'replicate', 'sambanova', 'together'] ↓

cause You are attempting to use 'fireworks-ai' as a provider within the `huggingface_hub` library, but your installed version of `huggingface_hub` does not yet officially support it.

fix

Update your huggingface_hub library to the latest development version (pip install git+https://github.com/huggingface/huggingface_hub) which includes support for the 'fireworks-ai' provider.

Warnings

breaking v1.0.0 alpha SDK (pip install fireworks-ai==1.0.0a*) is NOT stable. It has breaking changes vs v0.x and is still in pre-release as of Jan 2026. pip install fireworks-ai installs v0.19.20 (stable). ↓

fix Use v0.19.20 for production. Pin explicitly: pip install fireworks-ai==0.19.20

breaking Model IDs use full path format: accounts/fireworks/models/<model-name>. Short names like 'llama-3-8b' will fail with 404. ↓

fix Always use full model path. Find IDs at fireworks.ai/models

gotcha When using OpenAI SDK compatibility, set FIREWORKS_API_KEY env var but pass it explicitly as api_key= — the OpenAI SDK reads OPENAI_API_KEY by default and will silently use the wrong key. ↓

fix api_key=os.environ['FIREWORKS_API_KEY'] explicitly in OpenAI() constructor

gotcha usage field is not exposed in OpenAI SDK streaming responses against Fireworks. Cast chunk to Any in TypeScript; in Python, usage will be None on stream chunks. ↓

fix Use non-streaming for usage tracking, or read usage from the final chunk only

gotcha LiteLLM uses FIREWORKS_AI_API_KEY (with _AI_). Native SDK and OpenAI-compat use FIREWORKS_API_KEY. Different env var depending on integration. ↓

fix Check integration docs. Set both if mixing LiteLLM with native/OpenAI SDK.

deprecated Build SDK (native fireworks.client) is marked deprecated in official docs. Fireworks now recommends OpenAI-compatible approach for new projects. ↓

fix Migrate to OpenAI SDK with base_url override, or wait for stable v1.0.0

Install

pip install fireworks-ai==1.0.0a20

pip install openai

Install compatibility verified last tested: 2026-05-12

python os / libc variant status wheel install import disk

3.10 alpine (musl) fireworks-ai - - 6.08s 130.7M

3.10 alpine (musl) fireworks-ai==1.0.0a20 - - - -

3.10 alpine (musl) openai - - - -

3.10 slim (glibc) fireworks-ai - - 4.25s 131M

3.10 slim (glibc) fireworks-ai==1.0.0a20 - - - -

3.10 slim (glibc) openai - - - -

3.11 alpine (musl) fireworks-ai - - 6.93s 140.2M

3.11 alpine (musl) fireworks-ai==1.0.0a20 - - - -

3.11 alpine (musl) openai - - - -

3.11 slim (glibc) fireworks-ai - - 4.50s 140M

3.11 slim (glibc) fireworks-ai==1.0.0a20 - - - -

3.11 slim (glibc) openai - - - -

3.12 alpine (musl) fireworks-ai - - 6.20s 130.6M

3.12 alpine (musl) fireworks-ai==1.0.0a20 - - - -

3.12 alpine (musl) openai - - - -

3.12 slim (glibc) fireworks-ai - - 4.84s 131M

3.12 slim (glibc) fireworks-ai==1.0.0a20 - - - -

3.12 slim (glibc) openai - - - -

3.13 alpine (musl) fireworks-ai - - 5.92s 130.3M

3.13 alpine (musl) fireworks-ai==1.0.0a20 - - - -

3.13 alpine (musl) openai - - - -

3.13 slim (glibc) fireworks-ai - - 4.58s 131M

3.13 slim (glibc) fireworks-ai==1.0.0a20 - - - -

3.13 slim (glibc) openai - - - -

3.9 alpine (musl) fireworks-ai - - 4.52s 110.5M

3.9 alpine (musl) fireworks-ai==1.0.0a20 - - - -

3.9 alpine (musl) openai - - - -

3.9 slim (glibc) fireworks-ai - - 2.89s 108M

3.9 slim (glibc) fireworks-ai==1.0.0a20 - - - -

3.9 slim (glibc) openai - - - -

Imports

Fireworks

wrong

import fireworks

correct

from fireworks.client import Fireworks

v0.x stable import path

OpenAI (Fireworks compat)

wrong

from openai import OpenAI
client = OpenAI()

correct

from openai import OpenAI
client = OpenAI(base_url='https://api.fireworks.ai/inference/v1', api_key=os.environ['FIREWORKS_API_KEY'])

Must override base_url and api_key — defaults point to OpenAI

Quickstart stale last tested: 2026-05-11

Chat completion using OpenAI-compatible interface (recommended for portability)

from openai import OpenAI

client = OpenAI(
    base_url='https://api.fireworks.ai/inference/v1',
    api_key='YOUR_FIREWORKS_API_KEY'
)

response = client.chat.completions.create(
    model='accounts/fireworks/models/llama-v3p1-8b-instruct',
    messages=[{'role': 'user', 'content': 'Hello'}]
)
print(response.choices[0].message.content)