# Connect Vercel AI Gateway

With Vercel AI Gateway as the [model provider](https://docs.faustine.ai/workspace/model-providers/), Faustine sends model and embeddings requests to `https://ai-gateway.vercel.sh` with one key from your Vercel team. Vercel bills the usage to the team.

## Before you begin

On Vercel you need:

- A team API key for AI Gateway. See [AI Gateway authentication](https://vercel.com/docs/ai-gateway/authentication) in the Vercel documentation. A key created by a team member stops working when that member leaves the team.
- A payment method on the team and AI Gateway credits. Claude models are not on Vercel's free tier.
- Only if you need a region, zero data retention or a pinned upstream: a virtual model on Vercel. You enter it as an override in the **Models** step.

## Connect Vercel AI Gateway

1. In the portal, go to **Settings** > [**Model Provider**](https://auth.faustine.ai/go?to=%2Fsettings%3Ftab%3Dprovider) and select **Configure a provider**.
2. In **Provider**, select **Vercel AI Gateway**.
3. In **AI Gateway API key**, enter the key and select **Continue**.
4. In **Models on your provider**, leave the fields empty and select **Test connection**, then **Continue**.
5. In **Embeddings**, **Use my Vercel AI Gateway** is selected with the model `openai/text-embedding-3-small`. Select **Continue**.
6. In **Review & save**, select **Test connection**, then **Save & activate**.

The tab shows the **Vercel AI Gateway** card with an **Active** badge. There is no URL to enter, because the gateway has one address for every team.

## Override a model

The gateway accepts Faustine's model IDs as they are, so the **Models** step is optional. The gray ID in each row is what Faustine sends: the first-party ID for Claude models, and the ID with an `openai/` prefix for OpenAI models.

Enter a value in a row only to send that model somewhere else:

| Override | Example |
| --- | --- |
| A virtual model you created on Vercel | `vmc/<SLUG>` |
| A variant of the model | `anthropic/claude-opus-5-fast` |

## Embeddings

**Use my Vercel AI Gateway** reuses the AI Gateway key, so Faustine stores no second key. Model IDs follow the gateway's catalog and start with the creator, as in `openai/text-embedding-3-small`. To use OpenAI directly, select **Use a separate OpenAI key**.

## What the validation checks

| Check | How |
| --- | --- |
| Credentials | A request for the team's credit balance, which costs no tokens. A 401 or 403 means Vercel rejected the key, and the configuration is not saved. |
| Each model | One real request of 16 tokens to every model in Faustine's list for your workspace, with the override where you entered one. |
| Embeddings | One embeddings request to the model you entered. |

If the key is valid and the team's balance is 0, the save goes through with a warning to buy credits before the first run.

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| `Vercel rejected the AI Gateway API key` | The key is wrong, or the member who created it left the team. | Create a team key and enter it. |
| A model shows **Refused** with `The Vercel team has no AI Gateway credits` | The team has no credits, or the key's budget is spent. | Buy credits in the AI Gateway tab of the Vercel team. |
| A model shows **Refused** with `Vercel needs a payment method on the team` | The team has no card. | Add a card on Vercel, then buy credits. |
| A model shows **Not found** with `Vercel AI Gateway does not list this model id` | The override does not name a model in the gateway's catalog. | Clear the field, or enter a `creator/model` ID or one of your virtual models. |

## Next steps

- [Model providers](https://docs.faustine.ai/workspace/model-providers/): status, test and the other providers.
- [Choose an embeddings provider](https://docs.faustine.ai/workspace/embeddings/): the embeddings options on Vercel AI Gateway.
- [Choose the chat model](https://docs.faustine.ai/web-agents/chat-model/): pick a Claude or OpenAI model for an agent.