How to use Cursor with a custom API (your own key)

Cursor can use an OpenAI-compatible endpoint instead of its own model billing, but only in builds that expose an Override OpenAI Base URL (or Custom Base URL) field. When that field exists, setup is four values: API key, base URL, model ID, and a new chat to test. This guide covers those values, what Cursor does and does not route through your key, and the token math for a coding workload.

Written 2026-10-27. Cursor's settings UI changes between releases; use the labels your build shows and treat the field names below as the common case.

What Cursor's custom API mode actually does

Cursor is an editor plus a model client. A custom key replaces the model account Cursor would otherwise bill for the requests it sends through that key. It does not turn Cursor into a generic API client, and it does not guarantee that every feature uses your endpoint.

The practical consequence: expect the chat and agent panel to use your key, and expect some editor-native features to keep using Cursor's own models. If you need every request to go through one gateway, a client built around a provider setting — Cline, for example — is easier to audit.

Before you start

Step 1: open Cursor's model settings

Open Cursor Settings and find the Models section. In builds that support bring-your-own-key, there is an API Keys area with an OpenAI key field and a base-URL override. If you only see Cursor's own model list and no key or URL field, stop here: that build cannot point at a custom gateway directly. Use the Cline guide linked at the end of this page.

Step 2: add the key and base URL

Enable the OpenAI API Key option, paste your JZS key, and put the API base URL in the override field:

API Key:   sk-your-key-here
Base URL:  https://jzstoken.com/api/v1
Model:     claude-sonnet-5

The base URL is the part people get wrong. Use https://jzstoken.com/api/v1, not https://jzstoken.com/api/v1/chat/completions. Cursor appends the endpoint path itself. A trailing slash is usually harmless, but the exact base URL is easier to support when something fails.

Click Verify if the button is present. A successful verify means the key and URL were accepted; it does not prove that every Cursor feature will use the model. Send a real chat message as the final check.

Step 3: add the model ID

If Cursor lets you add a custom model name, enter the exact ID from the catalog. The ID is case-sensitive and has no vendor prefix. These are the sensible starting points for coding:

The catalog also lists versioned variants such as claude-sonnet-5.5, priced the same as its unversioned ID. Use the ID that appears in your Cursor model field and in the catalog; do not assume a dot or hyphen variant will resolve.

Step 4: test with a read-only request

Start a new chat, select the model you added, and ask for something that cannot modify the repository:

> list the top-level files in this repository and explain what the project does
  in one paragraph. Do not edit anything.

A normal answer confirms the key, base URL, and model. Then ask for a small edit and review the diff. If the answer works but the agent cannot edit files, the model may not support the tool-call format Cursor expects; try Claude Sonnet before changing the gateway settings.

Open the usage page after the first session. The per-request token counts are the real number; the token estimate in a chat UI is not a bill.

What the same tokens cost on both gateways

This is the standard-price comparison for the models that overlap with OpenRouter. It uses a 3:1 input/output blend and excludes batch, cache, and retries.

USD per 1M tokens, standard (non-batch) routes, captured 2026-10-26. Blended assumes 3 input tokens per output token. OpenRouter batch routes are often half price and are not compared here.

Sources: JZS public pricing API and OpenRouter public model list, both read on 2026-10-26. Prices move; check both pages before you commit to a provider.

A coding session is usually more input-heavy than 3:1 because the editor resends context on every turn. That makes the input column more important than the blended rank. The table below uses a concrete 10M input + 2M output month instead:

10M input + 2M output, USD, standard non-batch rates. GPT-5.6 Terra's prices were read on 2026-10-27; OpenRouter lists it at $2.00 / $12.00 per 1M. The other rows use the shared comparison data captured 2026-10-26. These are list-price estimates, not a quote.

Cursor-specific limits worth knowing

• The override field is version-dependent. A build without it cannot use a custom OpenAI-compatible gateway, regardless of the key.
• Some Cursor features run on Cursor's servers and may keep using Cursor's models. A custom key is not a global proxy for the whole editor.
• The model list may not refresh from the gateway. Add IDs manually and expect to re-check them after a Cursor update.
• Verify only tests credentials. It does not test streaming, tool calls, or long context, so send a real coding request before trusting it.
• A custom key changes inference billing; it does not necessarily remove Cursor's own plan limits or feature gates.

Troubleshooting

Security and team use

The key lives in Cursor's local settings, which means it is only as private as the machine. Use one key per developer or per device, named so you can recognise it in the usage log. Do not put the key in a repository, a shared Cursor settings sync, or a screenshot. If a laptop is lost, delete that key rather than rotating the whole team.

For a team, decide up front which Cursor features are allowed to call the paid gateway. A developer experimenting with agent mode can generate far more requests than a chat user, and the usage page will only show totals per key. If you need per-project attribution, separate keys per project are simpler than trying to infer it after the fact.

Cursor or Cline for a custom API?

Cursor is the better editor experience when the override field exists and the features you use stay inside the custom-key path. Cline is the more predictable choice when you want every model request to go through one provider configuration, because its OpenAI Compatible provider is a first-class setting rather than a version-dependent override.

The Cline setup is documented step by step in How to use Cline with a custom API. If you are still choosing a gateway, the 2026 LLM API pricing comparison has the wider table.

FAQ

Does Cursor support a custom OpenAI base URL?

Some builds do, under Models → API Keys, with a field labelled Override OpenAI Base URL or Custom Base URL. Others do not expose the field at all. Check your build before buying credit for this setup; the feature is version-dependent, not account-dependent.

Can I use Claude models through Cursor's OpenAI-compatible setting?

Yes, if the model ID is in the catalog and your key covers it. The gateway accepts OpenAI-format chat requests and routes the model you name. Use the exact ID, for example claude-sonnet-5, not a display name.

Why does Tab completion still cost Cursor credits?

Because Tab is a Cursor-served feature, not a request your override key necessarily handles. A custom key changes the billing path for the requests Cursor sends to it; it does not make every editor feature use that endpoint.

Is Cursor with a custom key cheaper?

The per-token rate is usually lower than OpenRouter on the overlapping Claude and GPT models, but Cursor's own plan and the features that bypass your key still cost money. Compare the full bill, not just the model line: subscription, requests that use your key, and requests that do not.

What if my Cursor version has no base-URL override?

Use a client that treats the provider as a first-class setting. Cline in VS Code is the closest workflow and is covered in the next guide. Do not try to redirect Cursor by editing hosts or a system proxy; that is fragile and can break Cursor's own services.

Try Cursor with JZS

Create a key, check the live prices for the model you plan to use, and send one read-only request. If your Cursor build has no base-URL override, the Cline guide is the fallback.