Skip to main content
API7.ai Logo

Fireworks AI

Connect AISIX AI Gateway to Fireworks AI so applications can call Fireworks-hosted models through the gateway's OpenAI-compatible API. AISIX keeps the Fireworks credential on the gateway side. It authorizes model access with caller API keys and allowlists, and applies the same rate-limit and usage-accounting controls as other model aliases.

Fireworks AI exposes an OpenAI-compatible API, so it uses the openai adapter with a Fireworks api_base. The Cloud Admin API derives the adapter from the catalog provider; the adapter field is only accepted on BYO provider keys.

Prerequisites​

The following examples configure the upstream through the AISIX Cloud Admin API. Before configuring the upstream, prepare the following:

  • A running AISIX stack with an environment and an attached gateway. Follow the AISIX On-Premises Quickstart to set up the stack, create an admin token with write scope, and capture the environment ID.
  • A Fireworks API key from the Fireworks console.

Export the connection details used by every request below:

export AISIX_CP="http://localhost:8080/api"
export AISIX_TOKEN="aisix_pat_YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"

Configure the Fireworks AI Upstream​

Create a provider key, model alias, and caller API key for the Fireworks-backed chat-completions route.

Create a Provider Key​

Create the provider key that stores the Fireworks credential and API root, and allow it into the environment:

# Replace with your value
export FIREWORKS_API_KEY="YOUR_PROVIDER_API_KEY"

PROVIDER_KEY_ID=$(curl -sS -X POST "$AISIX_CP/provider_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "fireworks-prod",
    "provider": "fireworks-ai",
    "api_key": "'"${FIREWORKS_API_KEY}"'",
    "api_base": "https://api.fireworks.ai/inference/v1",
    "allowed_environments": ["'"${ENV_ID}"'"]
  }' | jq -r '.provider_key.id')

echo "$PROVIDER_KEY_ID"

❶ provider is fireworks-ai, the catalog provider ID. The hyphen is part of the identifier; fireworks alone is rejected with a 400 INVALID_REQUEST.

❷ api_key stores the Fireworks API key. It follows the credential-handling behavior in Provider Credentials.

❸ api_base points at the Fireworks inference API. The /inference segment is significant: Fireworks serves its OpenAI-compatible inference routes under https://api.fireworks.ai/inference/v1, while its account-management REST API — the one that lists and creates Fireworks API keys — is served under https://api.fireworks.ai/v1. Dropping /inference points the provider key at the wrong API surface.

AISIX appends the endpoint path to api_base, so use the API root without a trailing /chat/completions. A trailing slash is trimmed before the endpoint path is appended, so https://api.fireworks.ai/inference/v1/ and https://api.fireworks.ai/inference/v1 resolve identically.

note

api_base is optional for this provider. When it is omitted, the Cloud Admin API fills in https://api.fireworks.ai/inference/v1. Setting it explicitly keeps the upstream root visible on the resource and survives a later move to a dedicated Fireworks deployment.

The command captures the returned provider key ID in PROVIDER_KEY_ID.

Create a Model​

Fireworks model IDs are fully qualified account paths rather than bare names. A serverless model published by Fireworks uses the form accounts/fireworks/models/<name>, for example accounts/fireworks/models/gpt-oss-120b. Fireworks also writes decimal points in version numbers as p, so Qwen 3.7 Plus is accounts/fireworks/models/qwen3p7-plus. A flat OpenAI-style name such as gpt-oss-120b is not a valid Fireworks model ID.

Copy the full identifier from the Fireworks models overview rather than assembling it by hand. Some catalog entries replace the models segment with routers, and models you deploy yourself use your own account name in the first segment.

Create the model alias callers will send in requests:

MODEL_ID=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/models" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "fireworks-gptoss-prod",
    "model_name": "accounts/fireworks/models/gpt-oss-120b",
    "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
  }' | jq -r '.model.id')

echo "$MODEL_ID"

❶ display_name is the alias callers send in model. Callers never see the account path.

❷ model_name is the Fireworks model ID, for example accounts/fireworks/models/gpt-oss-120b, accounts/fireworks/models/kimi-k3, or accounts/fireworks/models/qwen3p7-plus.

❸ provider_key_id attaches the alias to the Fireworks provider key.

Create a Caller API Key​

Create the caller API key that can access the model alias. The API generates the key value and returns the plaintext once:

AISIX_API_KEY=$(curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/api_keys" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "fireworks-caller",
    "allowed_models": ["'"${MODEL_ID}"'"]
  }' | jq -r '.plaintext')

echo "$AISIX_API_KEY"

The allowed_models value references the model by its ID. The plaintext key is returned only in this response, so store it securely.

The new resources project to the attached gateway automatically.

Verify the Provider Connection​

Send a chat-completions request through the AISIX proxy:

curl -sS -X POST "http://127.0.0.1:3000/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "fireworks-gptoss-prod",
    "messages": [
      {
        "role": "user",
        "content": "Say hello from Fireworks AI."
      }
    ]
  }'

The gateway returns an OpenAI-compatible response that echoes the caller-facing alias fireworks-gptoss-prod. If the request fails, check the provider key api_key, the /inference/v1 path in api_base, and the full accounts/... model ID in model_name.

Understand the Token-Limit Parameter Rewrite​

Fireworks documents max_tokens as the output-limit parameter on its chat-completions route, while current OpenAI SDKs and many agent frameworks send max_completion_tokens. AISIX resolves the difference for you: the fireworks-ai catalog entry carries a built-in request override that renames max_completion_tokens to max_tokens on the outbound request body.

The rewrite has three consequences worth knowing:

  • Callers do not need a Fireworks-specific code path. A client that sends max_completion_tokens reaches Fireworks with max_tokens set to the same value.
  • If a single request carries both fields, the max_completion_tokens value replaces max_tokens. The newer field wins because it is the one the caller most likely set deliberately.
  • The rename applies to the outbound body on every normalized route this provider key serves, not to chat completions alone. Provider passthrough is the exception, because it forwards the body verbatim, so send the field name Fireworks expects on that route.

Fireworks applies its own default output limit to requests that omit the field, so set an explicit limit for long generations. See Querying text models for the current parameter reference.

caution

A request block supplied on the provider key replaces the built-in block rather than merging with it. If you add your own request overrides for this provider key, re-declare param_renames alongside them, or the rewrite stops applying:

{
  "request": {
    "param_renames": {
      "max_completion_tokens": "max_tokens"
    },
    "default_headers": {
      "X-Team": "platform"
    }
  }
}

See Provider-Specific Overrides for the full override schema.

Use Reasoning Models​

Fireworks documents two mutually exclusive reasoning controls, and support for each is model-specific:

  • reasoning_effort, whose accepted effort levels are model-specific and include low, medium, and high.
  • thinking, an object with type set to enabled and budget_tokens of at least 1024.

A request must not set both. AISIX forwards top-level request fields it does not model verbatim to the upstream, so either control reaches Fireworks unchanged:

{
  "model": "fireworks-gptoss-prod",
  "messages": [{ "role": "user", "content": "Plan a cache invalidation strategy." }],
  "reasoning_effort": "medium"
}

Fireworks returns the chain of thought in reasoning_content, which is already the canonical AISIX field. This provider therefore needs no response.reasoning_field override: AISIX preserves the field as choices[0].message.reasoning_content on non-streaming responses and as delta.reasoning_content on streaming responses. Check Reasoning for which models accept which control.

Review Endpoint Support​

A Fireworks-backed alias works on the routes below. See Provider Compatibility for the full endpoint matrix.

RouteBehavior with a fireworks-ai provider key
/v1/chat/completionsSupported, including stream: true.
/v1/embeddingsSupported when the target model is a Fireworks embedding model, because Fireworks implements an OpenAI-shaped embeddings route. See Embeddings and reranking.
/v1/responsesSupported through the Responses bridge. Verbatim forwarding to an upstream Responses API is reserved for models whose configured provider is openai, so Fireworks requests are translated through the chat adapter path.
/v1/rerankNot supported. The rerank route accepts only the openai, cohere, and jina provider values, so a fireworks-ai alias is rejected even though Fireworks publishes a reranking API.
/v1/images/generationsNot supported. The route requires a model whose configured provider is openai.
/v1/videosNot supported. The route has its own provider allowlist, which does not include fireworks-ai.
/passthrough/fireworks-ai/*Supported for provider-native endpoints that AISIX does not model.

For passthrough, AISIX joins the requested path onto api_base. Because the Fireworks api_base ends with an API-version segment, a passthrough path that also begins with v1/ is deduplicated, so /passthrough/fireworks-ai/v1/<path> and /passthrough/fireworks-ai/<path> both resolve to https://api.fireworks.ai/inference/v1/<path>. Passthrough requires a caller API key that is allowed at least one model whose provider value is fireworks-ai. AISIX borrows that model's provider key for the tunnel, so the credential used is the one attached to the first allowed matching model rather than a provider key you name in the path. See Provider Passthrough.

Next Steps​

You have now connected AISIX to Fireworks AI and verified the model alias. Continue with these guides: