Install & Compatibility
Where this runs
tested against v1.2.9 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.10
14/18 runs
14/18 runs
py 3.11
14/18 runs
14/18 runs
py 3.12
14/18 runs
14/18 runs
py 3.13
14/18 runs
14/18 runs
py 3.9
14/18 runs
14/18 runs
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Fireworks
✓ from fireworks.client import Fireworks
✗ import fireworks
v0.x stable import path
OpenAI (Fireworks compat)
✓ from openai import OpenAI
client = OpenAI(base_url='https://api.fireworks.ai/inference/v1', api_key=os.environ['FIREWORKS_API_KEY'])
✗ from openai import OpenAI
client = OpenAI()
Must override base_url and api_key — defaults point to OpenAI
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)
fireworks --version
Debug
Known issues
breakingv1.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).fixUse v0.19.20 for production. Pin explicitly: pip install fireworks-ai==0.19.20
affects: 1.0.0a1–1.0.0a20
breakingModel IDs use full path format: accounts/fireworks/models/<model-name>. Short names like 'llama-3-8b' will fail with 404.fixAlways use full model path. Find IDs at fireworks.ai/models
affects: all
gotchaWhen 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.fixapi_key=os.environ['FIREWORKS_API_KEY'] explicitly in OpenAI() constructor
affects: all
gotchausage 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.fixUse non-streaming for usage tracking, or read usage from the final chunk only
affects: all
gotchaLiteLLM uses FIREWORKS_AI_API_KEY (with _AI_). Native SDK and OpenAI-compat use FIREWORKS_API_KEY. Different env var depending on integration.fixCheck integration docs. Set both if mixing LiteLLM with native/OpenAI SDK.
affects: all
deprecatedBuild SDK (native fireworks.client) is marked deprecated in official docs. Fireworks now recommends OpenAI-compatible approach for new projects.fixMigrate to OpenAI SDK with base_url override, or wait for stable v1.0.0
affects: 0.x
Errors
Common errors & fixes
AuthenticationError({'fault': {'faultstring': 'Invalid ApiKey', 'detail': {'errorcode': 'oauth.v2.InvalidApiKey'}}})
Your Fireworks AI API key is either incorrect, expired, or has insufficient permissions, preventing authentication with the Fireworks AI service.
fixVerify 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.
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)
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.
fixDouble-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.
AttributeError: module 'openai' has no attribute 'ChatCompletion'
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+.
fixUpgrade 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()`.
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'"}}
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.
fixRemove 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.
ValueError: Provider 'fireworks-ai' not supported. Available providers: ['fal-ai', 'hf-inference', 'replicate', 'sambanova', 'together']
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.
fixUpdate 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.
Upgrade
Version history
1.2.9latest on PyPI · released Aug 12, 2026
Audit
Dependencies
openaioptionalRequired if using OpenAI-compatible approach instead of native SDK