Skip to main content

Bring your own AI key plugin

EnterpriseThis plugin is available with an Enterprise plan. 5.57.0This feature requires Strapi version 5.57.0 or later.
Page summary:

The Bring your own AI key (BYOK) plugin powers Strapi AI with your own AI provider, for AI Translations and AI-powered metadata generation.

With the Bring your own AI key plugin, Strapi AI sends the requests of AI Translations and AI-powered metadata generation in the Media Library to the provider of your choice. You set the API key and pick the model for each feature. The Content-Type Builder AI assistant is not included: it is only available with Strapi-managed AI.

IDENTITY CARD
Location
Configured in /config/plugins. Used through the Strapi AI features of the admin panel.
Package name
@strapi-enterprise/plugin-byok
Additional resources
Installing Enterprise plugins
Prerequisites
  • A license for the CMS Enterprise plan.
  • Strapi 5.57.0 or later.
  • An API key for a provider with an OpenAI-compatible API.
  • For AI Translations, the Internationalization feature.

Installation​

The plugin installs from the Strapi package registry. The strapi enterprise install command does the setup for you, or you can do it manually.

With the command​

From the root folder of your Strapi application, run:

terminal
yarn strapi enterprise install plugin-byok

The command finds your license, sets up access to the registry, and installs a version that supports the Strapi version of your application. See Installing Enterprise plugins for details.

Manually​

  1. Set up access to the registry, as described in Setting up access manually.
  2. From the root folder of your Strapi application, install the package, saving the exact version:
terminal
yarn add --exact @strapi-enterprise/plugin-byok
Caution

Once installed, the plugin is enabled, and Strapi does not start until the plugin is configured. See Configuration.

Configuration​

The plugin is configured in the plugins configuration file, with environment variables for the provider connection and the models.

  1. Add the plugin to the plugins configuration file:
/config/plugins.js
module.exports = ({ env }) => ({
  // …
  byok: {
    enabled: env.bool('STRAPI_BYOK_ENABLED', false),
    config: {
      connection: {
        baseURL: env('STRAPI_BYOK_PROVIDER_BASE_URL'),
        apiKey: env('STRAPI_BYOK_PROVIDER_API_KEY'),
      },
      models: {
        translations: env('STRAPI_BYOK_TRANSLATIONS_MODEL'),
        mediaMetadata: env('STRAPI_BYOK_MEDIA_METADATA_MODEL'),
      },
    },
  },
});
  1. Set the environment variables in the .env file. See Configuration options for the expected value of each one:
terminal
/.env
STRAPI_BYOK_ENABLED=true
STRAPI_BYOK_PROVIDER_BASE_URL=
STRAPI_BYOK_PROVIDER_API_KEY=
STRAPI_BYOK_TRANSLATIONS_MODEL=
STRAPI_BYOK_MEDIA_METADATA_MODEL=
  1. Restart Strapi.

Configuration options​

If a required option is missing while the plugin is enabled, Strapi does not start and logs the first missing option.

OptionTypeRequiredDescription
enabledBooleanNoTurns the plugin on or off without uninstalling it. With the configuration above, the plugin stays off unless STRAPI_BYOK_ENABLED is true.
connection.baseURLStringYesRoot URL of your provider's OpenAI-compatible API, with its version prefix. For instance, https://api.openai.com/v1 for OpenAI, or https://api.anthropic.com/v1 for Anthropic.
connection.apiKeyStringYesAPI key for your provider. Keep it in the server environment only.
models.translationsStringYesModel used for AI Translations, for instance gpt-4o (OpenAI) or claude-haiku-4-5 (Anthropic).
models.mediaMetadataStringYesModel used to generate alternative text and captions in the Media Library. The model must accept image input, for instance gpt-4o (OpenAI) or claude-sonnet-5-5 (Anthropic).
Tip

Use STRAPI_BYOK_ENABLED to keep the plugin off in an environment without an API key, such as a staging environment.

Tested providers and models​

The plugin works with providers that offer an OpenAI-compatible API. Strapi tested the following models. For the connection.baseURL value, see the documentation of your provider: Anthropic, OpenAI, Google Gemini, OpenRouter, or LiteLLM.

Provider and model familyAI Translations (models.translations)AI-powered metadata generation (models.mediaMetadata)
Anthropic Claude Haiku>=claude-haiku-4-5>=claude-haiku-4-5
Anthropic Claude Sonnet>=claude-sonnet-4-5>=claude-sonnet-4-5
Anthropic Claude Opus>=claude-opus-4-5>=claude-opus-4-8
Anthropic Claude Fable>=claude-fable-5>=claude-fable-5
OpenAI GPT>=gpt-4>=gpt-4o
OpenAI GPT mini>=gpt-5.4-mini>=gpt-4o-mini
OpenAI o-series>=o3>=o3
Google Gemini>=gemini-3>=gemini-3
OpenRouterSame as above, with OpenRouter IDs (e.g., anthropic/claude-haiku-4.5)Same as above, with OpenRouter IDs
LiteLLMSame as above, with your LiteLLM model namesSame as above, with your LiteLLM model names
Note

Strapi only tested the models above, but in theory any other OpenAI-compatible API should work. For AI-powered metadata generation, ensure that you use a model that accepts image input.

AI models don't always reply the same way to the same request, so even a tested model can fail now and then. If that happens, retry the request.

Usage​

Once the plugin is configured, each AI feature works as described in its own documentation, including how to turn it on. Its requests go to your provider:

To turn off all Strapi AI features, including the ones the plugin powers, set ai.enabled to false.

Checking that the plugin is active​

When Strapi starts, the server logs list the features that use your provider, for instance:

BYOK is ready for AI Translation, AI Media Library. Requests go to your configured provider.

Troubleshooting​

SymptomWhat to do
Strapi does not start and logs an option that is requiredSet that option. See Configuration options.
A warning says your Strapi license does not include the featureCheck your license. Until it includes the feature, Strapi AI features stay off.
A warning says the i18n plugin is not installedAI Translations stays off until the Internationalization feature is enabled. The Media Library feature still uses your provider.
No BYOK is ready line in the logs at startupCheck that STRAPI_BYOK_ENABLED is true and that ai.enabled is not false.
The AI provider rejected the request (HTTP 401) or (HTTP 403)Check connection.apiKey.
The AI provider rejected the request (HTTP 404)Check that connection.baseURL includes the API version path, such as /v1, and that your provider still offers the model you set. Some providers also return a 404 error when your account cannot use the model.
The AI provider did not return valid JSONRetry. If the error happens often, try a more recent model from Tested providers and models. With a server that runs models on your own infrastructure, such as Ollama, try a larger model.

Uninstallation​

  1. Stop Strapi.
  2. Remove the byok entry from the plugins configuration file.
  3. Remove the package:
terminal
yarn remove @strapi-enterprise/plugin-byok
  1. Remove the STRAPI_BYOK_ENABLED, STRAPI_BYOK_PROVIDER_BASE_URL, STRAPI_BYOK_PROVIDER_API_KEY, STRAPI_BYOK_TRANSLATIONS_MODEL and STRAPI_BYOK_MEDIA_METADATA_MODEL variables from the .env file.
  2. Start Strapi again.
Was this page helpful?
On this page
Contribute to this page