Fireworks AI Python SDK

Common errors

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

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

• 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()`.

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

• 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 Stable (recommended)
• pip install fireworks-ai==1.0.0a20 v1 alpha (pre-release, breaking changes)
• pip install openai OpenAI-compatible alternative (no native SDK needed)

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

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)