API Setup for Tavern Studio

Tavern Studio manages characters, world books, presets, and chat context. A model provider generates the replies. API setup connects those two parts: the app sends a request to a provider, and the provider returns a model response.

This guide is for users configuring a roleplay client. It is not a developer SDK reference. Terms such as client.chat.completions.create and OpenAI-compatible API spec are useful background, but the practical setup is endpoint, key, model, and a test chat.

Before you add an API key

Prepare four things:

1. The provider or gateway you want to use.
2. The API key or token.
3. The base URL or endpoint if the provider needs one.
4. The model name you want Tavern Studio to call.

API keys are private credentials. Do not share them in screenshots, public logs, exported character cards, or support posts.

Choose an API provider

Most users choose one of these provider types:

• Direct cloud provider: you have an account and key from the provider.
• OpenAI-compatible gateway: a routing service exposes a familiar API shape.
• Local server: a model server runs on your machine or network.
• Custom endpoint: an advanced route through a proxy, team gateway, or hosted service.

Use the simplest provider that meets your privacy, cost, speed, and model needs.

Set up OpenRouter

OpenRouter is a common option for users who want access to multiple hosted models through one OpenAI-compatible route.

Typical setup:

1. Create or open your OpenRouter account.
2. Create an API key.
3. In Tavern Studio, choose the matching OpenAI-compatible or provider route.
4. Enter the required endpoint or provider setting.
5. Paste the API key.
6. Choose a model.
7. Run a short test chat.

Free or low-cost models may have rate limits, queueing, availability changes, or provider-specific logging policies. Test before moving a serious roleplay workflow to a new provider.

Set up an OpenAI-compatible endpoint

OpenAI-compatible usually means the service follows a familiar chat-completions style. It does not mean every provider behaves exactly like OpenAI.

Check these fields:

• Base URL: the endpoint root. Some providers require /v1; others already include it.
• API Key: the private credential.
• Model: the exact model identifier expected by the provider.
• Route or provider type: the Tavern Studio setting that controls how requests are sent.

If the model list does not refresh, you may still need to enter the model name manually if your app version supports it.

Add model, endpoint, and key settings

Use this checklist before testing:

• The base URL has the right /v1 path and does not duplicate it.
• The API key has no copied spaces or hidden line breaks.
• The selected model exists for your account.
• Your account has credit or quota.
• The provider route matches the endpoint.
• Proxy or network settings allow the request.

Free API options and limitations

Free API searches are common, but free routes are rarely the most stable default. They may include strict rate limits, shorter context, unavailable models, queue delays, or changing access rules.

Use free options for testing, then verify privacy and reliability before using them for a long-running character or world-book workflow.

Security notes for API keys

Treat API keys like passwords.

• Do not paste keys into character cards.
• Do not include keys in exported logs.
• Do not share screenshots that show keys.
• Rotate the key if it may have leaked.
• Use provider dashboards to revoke unused keys.

Common API setup mistakes

Most setup failures come from one of these:

• wrong base URL;
• missing or duplicated /v1;
• expired or invalid key;
• model name typo;
• no provider quota;
• provider outage;
• network or proxy block;
• using a preset that the selected model does not support well.

If the app returns an error after setup, continue to Troubleshooting Tavern Studio API Errors.