Connect Cursor to a Custom OpenAI-Compatible API: Full Guide (As of Sep 2026)

By pointing Cursor to a custom OpenAI-compatible endpoint such as HeFu's unified API (https://api.hefu.hk/v1), you keep your coding assistant fully operational after OpenAI formally ends model supply to Cursor on Nov 12, 2026 — while gaining access to GPT-5.6, Claude Opus 5, DeepSeek-V4-Pro, Gemini 3.6 Flash and many more models under one key, one bill, and one configuration change: Cursor's built-in “Override OpenAI Base URL” switch. This BYOK flow is documented by Cursor (docs.cursor.com, retrieved Sep 2026) and by OpenAI's Help Center (help.openai.com, retrieved Sep 2026). Cursor's Pro plan was listed at US$20/user/month on cursor.com/pricing as of Sep 2026; requests sent through a custom endpoint are billed by that endpoint's provider, not by Cursor.

Why Connect Cursor to a Custom OpenAI-Compatible API?

The trigger is structural: OpenAI sells model access through Cursor-managed plans, but its Help Center also documents bringing your own OpenAI API key to Cursor. If the announced cutoff for Cursor-managed OpenAI models takes effect on Nov 12, 2026, the exact status should be confirmed on OpenAI's official announcement page because contractual cutoff dates can change. After that date, anyone who wants to keep using GPT-class or alternative models inside Cursor must bring their own OpenAI API key or switch to a custom OpenAI-compatible base URL.

The custom-endpoint route is usually the better choice for teams. It centralizes billing, lets you select per-task models (Claude Opus 5 for complex refactors, DeepSeek-V4-Pro for high-volume generation, Kimi K3 for long-context review), and keeps your prompts and code excerpts inside a provider you explicitly trust. The setup pattern matches what we documented for Cline in VS Code, Open WebUI, and LobeChat: paste an API key, override a base URL, and verify the handshake.

What You Need: Prerequisites for a Seamless Setup

Only four components are required:

1. A Cursor account (any plan).
2. An API key from HeFu (sign up at https://www.hefu.hk).
3. An OpenAI-compatible base URL: https://api.hefu.hk/v1.
4. A model ID from the HeFu model catalog.

One protocol caveat matters before you start: Cursor Agent mode sends the OpenAI Responses API format (input plus flat tools), not legacy Chat Completions (messages plus nested tools). OpenAI made the Responses API generally available on 2025-03-11 (OpenAI announcement); the API reference uses input/tools for Responses (platform.openai.com). Endpoints that only implement /v1/chat/completions fail with "Errored, no charge" (Cursor forum, 2026). HeFu says its endpoint accepts both shapes as of Sep 2026, which is why it works as a drop-in replacement in Chat, plan mode, and agent mode.

Also keep expectations calibrated: a custom base URL covers Chat and Agent only. Tab autocompletion and Cmd/Ctrl+K inline edits stay locked to Cursor's own backend and never touch your gateway, per Cursor's BYOK documentation (retrieved Sep 2026).

Step-by-Step: Configuring Cursor's Custom API Settings

The UI path takes roughly 2–5 minutes, mirroring the Cline guide:

1. Open Cursor → Settings → Models.
2. Paste your HeFu API key into the OpenAI API Key field.
3. Enable Override OpenAI Base URL and enter https://api.hefu.hk/v1.
4. Save, then send a test message in Chat.

Verification tips: a successful Chat response confirms the handshake; next, switch to agent mode and run a task that calls a tool to confirm Responses-API compatibility (our Open WebUI guide uses the same two-field logic).

Important behavior: once Override OpenAI Base URL is enabled, all OpenAI-family requests—including Cursor's managed OpenAI models—route to your custom endpoint. As of Sep 2026, Cursor provides no per-model or per-provider override, so reverting requires manually disabling the override (Cursor official forum, posts of 2026-02-26 and 2026-03-07).

Model Mapping: Choosing the Right HeFu Models in Cursor

Instead of guessing model IDs, open the official catalog at https://www.hefu.hk/models. The table below is a task-to-model mapping as of Sep 2026; exact model IDs and availability are subject to the HeFu catalog and Cursor's model picker.

Task	Recommended HeFu Model	Why It Fits
Complex agentic coding, multi-file refactors	Claude Opus 5 / GPT-5.6 Terra	Strong tool-calling discipline, long-context reasoning
Frontend & backend generation	GPT-5.3 Codex / Qwen 3.8 Max	Code-specialized tuning, fast iteration
High-volume, low-cost work	DeepSeek-V4-Pro / DeepSeek-R1	Cost at a fraction of GPT flagship models
Long-document review	Kimi K3 / Gemini 3.6 Flash	Very long context, strong summarization
Multimodal inputs	Gemini 3.6 Flash / Qwen3-VL-Flash	Image understanding and multimodal reasoning

The broader catalog also includes GPT-5.6 Terra/Sol/Luna, GPT-5.5/5.4/5.2, GPT-5 Pro/Mini/Nano, Claude Sonnet 5 / Opus 4.8, DeepSeek-V3 / V3.1 / V3.2, GLM 5, Grok 4.3, and MiniMax M3—so you can map models per workflow rather than paying flagship prices for every request. Verify each exact model ID against the official catalog before entering it.

HeFu vs. Other Endpoints: What Makes It a Strong Choice

OpenAI's help center notes that aggregators such as OpenRouter or Vercel AI Gateway "may work" as compatible APIs, but available models and behavior depend entirely on the provider (help.openai.com, "Using OpenAI models in Cursor," retrieved Sep 2026). The practical selection criteria are protocol compatibility, model coverage, and billing clarity:

Dimension	HeFu Unified API	Self-Hosted Gateway	OpenRouter / Other Aggregators
Responses API for Cursor Agent	Yes—both formats, as of Sep 2026	Requires extra proxy/adapter	"May work," provider-dependent
Model coverage	GPT-5.6/5.x, Claude Opus/Sonnet 5, DeepSeek, Kimi, Gemini, Qwen, GLM, Grok, MiniMax	Whatever you self-host	Aggregator totals vary; check each provider's official model list
Billing model	Unified pay-as-you-go	Infra cost + upstream keys	Prepaid credits vs. itemized invoices; failure-billing rules differ
Regional access	Hong Kong node direct, no overseas card	Depends on your server	Depends on routing
Docs & support	API docs + Dev Toolkit	Self-maintained	Provider docs scattered

For Cursor specifically, protocol compatibility is the dealbreaker: an endpoint that only exposes Chat Completions will show "Errored, no charge" in agent mode even though Chat works. HeFu's dual-format support removes that failure class before you start debugging.

Troubleshooting: Common Errors and How to Fix Them

401 Unauthorized. The API key is missing, expired, or mistyped. Regenerate one from the HeFu dashboard and confirm there is no trailing space.

404 model not found. The model ID you entered is not in HeFu's catalog, or the ID is case-sensitive. Cross-check the exact string at https://www.hefu.hk/models.

"Errored, no charge" in Agent mode. This is the Responses API mismatch. Chat succeeds over /v1/chat/completions, but agent mode sends the Responses format; endpoints that implement only Chat Completions fail. HeFu supports both—if you still see this error, confirm the override is active and your key has agent-model access.

Timeout or streaming glitches. Most cases are network-level. HeFu's Hong Kong node offers a direct path; for quick diagnostics, use the Dev Toolkit to inspect raw request/response headers and SSE events.

Can I connect a local Ollama endpoint? Not directly. Cursor proxies agent requests through its own servers, so local/LAN endpoints must be publicly reachable (e.g., via cloudflared or ngrok) and must implement SSE streaming tool_calls; otherwise the connection appears healthy but behavior is abnormal (Reddit r/ollama, 2026).

Security & Cost: Using Custom APIs Responsibly

Treat the API key as a credential for all Cursor traffic: rotate it regularly, avoid committing it to dotfiles, and scope it to least privilege where HeFu's dashboard allows. For cost control, remember that Cursor's "no charge" message on proxy errors reflects Cursor's billing logic, not necessarily your provider's—always verify failed requests against HeFu's usage dashboard. As of Sep 2026, exact per-token rates for HeFu models are published only on the official pricing page, so treat that page as the single source of truth before scaling up spend.

FAQ

Is it allowed to use a custom API in Cursor?

Yes. Cursor explicitly supports custom OpenAI-compatible endpoints via Settings → Models → Override OpenAI Base URL, and OpenAI's help center documents bring-your-own-key setups for Cursor. The main constraint is behavioral: once the override is on, all OpenAI-family requests use your endpoint; there is no per-model override as of Sep 2026 (Cursor official forum, 2026).

How do I get an API key from HeFu?

Create an account at https://www.hefu.hk, generate an API key from the dashboard, and note the base URL https://api.hefu.hk/v1 plus the model IDs you need from https://www.hefu.hk/models. Step-by-step examples are in the development docs.

Can I use both Cursor's default models and HeFu models in parallel?

Not while the override is active. As of Sep 2026, Cursor does not offer per-model or per-provider routing; enabling Override OpenAI Base URL redirects all OpenAI-family traffic, including Cursor-managed models. To return to the default stack, disable the override manually (Cursor official forum, 2026-02-26 / 2026-03-07).

What if my custom endpoint returns a 404 model error?

The model ID you typed is not in HeFu's catalog. Open https://www.hefu.hk/models, copy the exact ID, and paste it into Cursor's model field. Note that IDs are case-sensitive and some models (e.g., DeepSeek-V4-Pro) may use distinct IDs in Chat versus agent mode.

Why does Chat work but Agent mode throw errors?

Because Cursor Agent uses the OpenAI Responses API format (input + flat tools), while legacy Chat Completions endpoints (messages + nested tools) cannot parse it. If a provider only implements /v1/chat/completions, Chat succeeds and agent mode fails with "Errored, no charge" (Cursor forum, Mar–Apr 2026). HeFu accepts both formats, which makes it a direct fix for this exact symptom.