Cursor Custom API Configuration

How to Configure a Custom API Key and Base URL in Cursor

Cursor AI IDE supports custom API keys and base URLs, allowing you to use your own API accounts, third-party providers, or relay services instead of the built-in Cursor subscription. This is essential for developers who need to control their API usage, use specific model versions, access models from restricted regions, or route requests through a centralized gateway.

Why Use a Custom API Key?

There are several reasons to configure your own API credentials in Cursor:

• Cost control: Use your own API account with direct billing instead of the Cursor Pro subscription.
• Model access: Access models that are not available through Cursor's built-in provider, or use the latest model versions as soon as they are released.
• Organizational requirements: Route requests through your company's API gateway for compliance, logging, or security purposes.
• Regional access: Use a relay service to access models from regions where direct API access is restricted.
• Usage tracking: Monitor and control API usage through your own dashboard or relay service.

Step-by-Step Configuration

Configuring an OpenAI-Compatible API

Most relay services and alternative providers use the OpenAI-compatible API format. Here is how to configure it:

1. Open Cursor and go to Settings (Cmd+, on macOS, Ctrl+, on Windows/Linux).
2. Click on Cursor Settings in the left sidebar (not the VS Code settings).
3. Navigate to the Models section.
4. Find the OpenAI API Key field and enter your API key.
5. Click on Override OpenAI Base URL and enter your custom endpoint.
6. Click Verify to test the connection.

// Example configuration for claude4u.com relay service:
API Key: cr_your-relay-api-key-here
Base URL: https://claude4u.com/v1

Configuring Anthropic (Claude) API

To use Claude models directly or through a compatible endpoint:

1. In Cursor Settings, go to the Models section.
2. Find Anthropic API Key and enter your key.
3. If using a relay service, you may need to configure the base URL to your relay endpoint.

Configuring Google (Gemini) API

1. In Cursor Settings, go to the Models section.
2. Find Google API Key and enter your Gemini API key.
3. Select Gemini models from the model picker when starting a conversation.

Using a Relay Service as Your Provider

A relay service like claude4u.com acts as a unified gateway to multiple AI models. When configured as your API endpoint in Cursor, it provides several advantages:

• Single API key for all models: Access Claude, GPT, Gemini, and other models with one key.
• Automatic load balancing: Requests are distributed across multiple backend accounts for better reliability.
• Cost dashboard: Track spending across all models in one place.
• Rate limit management: The relay handles rate limiting and queuing so you do not get interrupted while coding.
• Reliable access: Built-in retry logic and failover for consistent availability.

// Configuration for relay service in Cursor:
//
// Step 1: Override OpenAI Base URL with the relay endpoint
// Step 2: Enter the relay API key as the OpenAI API Key
// Step 3: Select models that the relay service supports
//
// The relay service translates requests to the appropriate
// provider format automatically.

Verifying Your Configuration

After setting up your custom API key and base URL:

1. Click the Verify button next to the API key field to test connectivity.
2. Open a new chat (Cmd+L) and send a simple test message like "Hello, which model are you?"
3. Check the response to confirm the correct model is responding.
4. Try an inline edit (Cmd+K) on a small code block to verify all features work.

Troubleshooting Common Issues

• "Invalid API key" error: Double-check that the API key is entered correctly with no leading or trailing spaces. Ensure the key format matches what your provider expects.
• "Connection refused" or timeout: Verify the base URL is correct and includes the protocol (https://). Test the URL in a browser or with curl to confirm it is accessible.
• Wrong model responding: Make sure you have selected the correct model in Cursor's model picker after configuring the custom endpoint.
• "Model not found" error: The model identifier you selected in Cursor may not match what the relay service expects. Check the relay service documentation for exact model names.
• Slow responses: If using a relay service, check if the relay service status page shows any issues. Also verify that your network connection to the relay endpoint is stable.

Advanced Configuration

For team environments, you can configure Cursor settings at the project level by creating a .cursor/settings.json file in your repository. However, API keys should never be stored in project-level settings — always use personal settings or environment variables for credentials.