Cursor's setting API and custom API capabilities will vary with versions, packages, and model providers. According to the official description, custom API Key is mainly used for standard chat models; some special functions may still use Cursor's own model. First confirm that the current version indeed provides the corresponding provider or Base URL entry before configuring.
Quick conclusion
Cursor's "API Key Valid" message only indicates that an authentication check may have passed. It does not prove that Agent requests, model mapping or tool calls use that endpoint. Record the test time and model ID, verify requests in available client or provider logs, and test chat and Agent tasks separately. If you cannot access logs, keep the complete error message. Settings verification alone does not establish full compatibility.
Check before you start
Cursor currently documents OpenAI BYOK support for standard, non-reasoning chat models; check the model picker for available options. A gateway's model catalog is not Cursor's compatibility list. A GPT model name alone does not establish support in your client. Keys and protocols from Anthropic, Google, and other providers are not interchangeable.
- Call with curl
/v1/models, confirm that the Key is valid. - Copy the real model ID without using the web display name.
- Confirm whether the target provider or custom Base URL entry exists in the current version of Cursor; if the interface does not have this option, do not copy the old version of the tutorial.
Configuration steps
Look for options related to API Keys, OpenAI API Key, or Base URL in Cursor's model or API settings. Different versions may display differently, and custom Key does not mean that all Agent functions will use this API.
Recommended parameters:
The third-party address below applies only when your version provides a custom Base URL setting. The official provider-key setup instructions do not guarantee compatibility with every OpenAI-compatible gateway.
API Key: you are here AICreated by Quick Station Key
Base URL: https://www.aifast.hk/v1
Model: YOUR_MODEL_IDAfter filling in, send a short message that can be accurately verified:
Reply with only：CURSOR_API_OKAfter receiving the reply, check the service provider call record by test time and model ID. Specifying the reply text helps identify the test, but it does not prove which service the request went to or the identity of the underlying model; response model Fields are only declared on the server side. After the short request is successful, test reading files, modifying code, and long context tasks.
Determine whether to append repeatedly /v1
If the Cursor log shows:
https://www.aifast.hk/v1/v1/chat/completionsChange the Base URL to:
https://www.aifast.hkWhether to retain /v1 It depends on whether the current client automatically appends the path, and the actual request log shall prevail.
FAQ
What if Cursor has no Override OpenAI Base URL setting?
Check your Cursor version, provider, and current settings. The official BYOK documentation does not guarantee a third-party Base URL setting in every version. If it is unavailable, do not enter a gateway key for an endpoint still pointing to the model provider or try to enable it through undocumented settings.
To check whether the API itself works, first use the Base URL checkerto check the path, then follow the OpenAI-compatible integration guideto test locally. This does not replace a compatibility test inside Cursor.
Can Cursor use every GPT model listed by a gateway?
No. Cursor's current documentation limits OpenAI BYOK support to standard, non-reasoning chat models; check the model picker for available options. A model ID in a gateway catalog does not establish support in your Cursor version. Verify client compatibility, API protocol, and account permissions separately.
Why is the local curl successful but the Cursor still cannot connect?
Cursor says requests using custom API keys still pass through its servers for final prompt building. A successful local request only verifies connectivity from your machine, not from Cursor's servers. Check the error timestamp, model ID, status code and server request logs. Your local localhost address is not an endpoint accessible to a remote server.
Does bringing your own API key replace a Cursor subscription?
Bringing your own key changes billing and access for supported model requests; it does not unlock every Cursor feature. Your model provider still charges for API usage, and Teams or Enterprise plans may also incur Cursor usage charges. Tab completion continues to use Cursor's built-in models. Check your current plan for subscription and allowance details.
Where do requests with a custom API key go?
Cursor says the key is sent with each request to its backend over an encrypted connection and is not persisted. Requests still follow the selected provider's data policy. Cursor's zero data retention policy does not automatically apply when you bring your own key, so confirm your team's data requirements before sending private code.
API Key Valid, but conversation failed
"Key verification successful" only indicates that the authentication may be passed, but does not mean that the current model name, request protocol and functional mode are compatible. Continue to view the status code and response body of the specific request.
| Check order | What to record or do | What it establishes |
|---|---|---|
| 1. Model actually selected | Record the ID in the chat model picker, not just the settings page | Avoid verifying one model while selecting another for chat |
| 2. One short message | Start a new chat with a short text message, without files or tools | Separate basic chat failures from Agent capability issues |
| 3. Whether the request arrives | Check provider logs by timestamp, model ID, and request ID | Local connectivity does not establish connectivity from Cursor's servers |
| 4. Final request path | Check the version prefix, endpoint type, and response Content-Type | Distinguish an HTML homepage, duplicated path segments, and a JSON API response |
Share only redacted status codes, paths, and request IDs. Do not disclose API keys, authentication headers, or private code.
model not found
- The model ID is spelled exactly the same.
- Whether the model supports the current API type.
- Whether the client replaces custom model names with built-in aliases.
Agent mode failed, normal chat succeeded
Agent patterns may rely on tool calls, long context, or specific response fields. Verify the normal chat first, and then confirm whether the selected model supports tool calls. Don't judge that all functions are compatible just based on the success of the text conversation.
Troubleshoot by error
| Symptom | Priority check | Corresponding steps |
|---|---|---|
401 or invalid_api_key |
Check that the key is complete and enabled, without an accidental Bearer prefix |
401 authentication troubleshooting |
404、/v1/v1 or model not found |
Final path, exact model ID, and current account permissions | address checkwithModel troubleshooting |
429 |
Distinguish between rate limits, concurrency limits and insufficient credit | 429 rate limiting troubleshooting |
502, timeout or output interruption |
Save request ID, time of occurrence, and streaming error | 502 and SSE disconnection troubleshooting |
Next step
Create a separate API Key for Cursor to facilitate usage statistics and permission revocation. When it comes to private repositories, don't send sensitive source code to unevaluated models or services.
If you are currently using a community protocol conversion project instead of the Cursor official custom Key, please read this first Cursor2API common error reports, risk checks and standard API migration, differentiate between upstream entry changes, conversion layer issues, and client capability boundaries before migrating.
After basic chat succeeds, run theModel Quality Checkto check model claims, token accounting, SSE, and tool calls on the Chat Completions endpoint. This check does not cover Cursor's proprietary Agent features and is not model-vendor identity certification.