DEVELOPER DOCUMENTATION

Cursor setup

Use GPU Router for supported Local chats and agent requests in Cursor Desktop.

← All coding-agent guides and compatibility

Checked September 13, 2026. Cursor Desktop 3.20.17 Local chat and a follow-up using existing tool history were verified with router-luna. Gateway streaming and function-tool round trips also passed. Broader in-app editing workflows still need testing.

1. Prepare your account

Create a GPU Router key in API Keys. New accounts automatically get $1 in free credits; add more in Billing when needed. You also need a Cursor account and a plan that permits your selected BYOK model. GPU Router credits do not change Cursor plan limits.

2. Set the key and base URL

1. Open Cursor Settings → Models → API Keys.
2. Paste your gpu_sk_live_… key into OpenAI API Key, save it, and enable Use OpenAI API Key.
3. Enable Override OpenAI Base URL and paste:

https://gpurouter.io/v1/cursor

Include /v1/cursor. Cursor adds /chat/completions itself. This dedicated endpoint accepts Cursor’s text and function-call formats. The shared coding-agent endpoint is https://gpurouter.io/v1/agents. Other API clients can continue using https://gpurouter.io/v1.

3. Add a model and select it in chat

Choose the actual model below, then copy its Cursor ID into Add Custom Model. Enable that model, open a new chat, and explicitly select it instead of Auto. Confirm the environment below the message box says Local.

Copy the readable client ID, such as router-gpt-luna, router-opus-5, or router-sonnet-4. Previously copied IDs still work. The full mapping is available at the Cursor model list. Use a router-* alias from that list. Names containing provider keywords can make Cursor select a different protocol or reject a custom model before contacting the gateway.

In the verified Cursor Desktop setup, custom models are added manually. The model-list endpoint powers this searchable picker; setting the base URL does not install the whole catalog into Cursor. You do not need to match Cursor’s built-in model names. Cursor’s Auto selection is separate from GPU Router’s automatic provider routing: keep your chosen router-* model selected.

4. Check chat, then tools

Start in Ask mode with “Reply OK.” Then try Agent mode in a scratch project with a small task, such as listing files and explaining one function. Text, streaming, function tools, and tool results are supported when the selected route advertises those capabilities. Cursor’s own model restrictions still apply.

To check the gateway independently, set GPU_ROUTER_API_KEY in your terminal and run the example below. It sends one small, billable request. Keep the key out of screenshots and messages.

curl "https://gpurouter.io/v1/cursor/chat/completions" \
  -H "Authorization: Bearer $GPU_ROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"COPY_A_CURSOR_MODEL_ID","messages":[{"role":"user","content":"Reply OK"}],"max_tokens":32}'

5. Image-generation availability

OpenRouter-only models have been removed from GPU Router, including the image-generation model used by the image MCP tool. Image generation and reference-image editing are unavailable until a supported model has another provider route. Check /catalog/models for current availability. Image understanding remains available on supported chat models.

Routing and retries

Keep your selected model. GPU Router tries eligible discounted providers first and uses a reference-price route as the final fallback for that same model. Provider quota, rate-limit, availability, and transport failures can retry before the response starts. Each retry must fit your balance, API-key allowance, required features, and any explicit price limits. A response already in progress is not restarted on another provider.

For normal routing, omit min_discount. A zero marketplace_min_discountalso permits fallback. Explicit min_discount values remain strict price guards; even zero prohibits above-reference pricing. A fallback can cost more than the first quote.

Caching and reasoning controls

Chat Completions accepts text-part arrays with ephemeral cache_control, a reasoning object (or reasoning_effort), and provider.order with allow_fallbacks. GPU Router preserves those controls and selects a compatible route. Verified model and supplier combinations can use discounted routes while keeping reasoning and prompt caching enabled. Reference-price routing remains the final fallback. Explicit price limits still apply.

The verified discounted configuration uses google/gemini-3.1-pro-preview, reasoning effort low, medium, or high, and at most one ephemeral cache breakpoint on a system or user text part, without an explicit TTL. Streaming and strict JSON output are supported. Function tools with tool_choice: "auto"and streamed tool-result follow-ups use supplier combinations verified for the requested reasoning effort. Strict tool definitions, forced tool choice, and explicit parallel-tool settings retain their existing compatible routes. reasoning.exclude: truehides reasoning text while preserving its usage and opaque continuation metadata. Explicit TTLs, provider preferences, images, and unverified combinations keep their existing compatible routes; adding a cache marker does not guarantee a hit or discount.

Astra, Sol, Luna, Luna Pro, GLM 5.3 Flash, and Gemini 3 Flash Preview also have verified discounted text routes for low and medium reasoning. Send the normal reasoning object: GPU Router translates it for verified GPT routes. With these reasoning/cache settings, function tools use combinations that passed a round trip using facts from the original prompt. Luna Pro tool combinations retain their existing fallback. Known supplier paths that lose system instructions are excluded from tool requests.

Gemini 3.1 Flash Lite has a verified supplier route for streaming, JSON output, function tools, and a single ephemeral cache breakpoint without an explicit TTL. This does not enable reasoning on a route that does not advertise it. Cache counts can still be zero or omitted, and a provider’s warm-session indicator is not a cached-token hit.

Keep cached text prefixes and part order stable. Cache markers request reuse; the provider determines whether a cache hit occurs. Provider ordering can affect cache reuse. For usage, use stream_options.include_usage: true; the legacy usage: { include: true } switch is also accepted. Read the final usage event even if its choices array is empty. These controls apply to Chat Completions; The agent adapter also accepts reasoning.effort in Responses-shaped input. Summary options, encrypted reasoning replay, and audio inputs remain unsupported.

Cursor’s flat input_schema tools and text-only tool_use/tool_result history are accepted by the agent endpoints. Error results retain is_error: true in a JSON text wrapper. SDK content options openai.imageDetail and anthropic.cacheControl are translated into image detail and cache markers. Conflicts and unknown meaningful options produce a validation error. Image dimension hints are ignored for admission and billing.

Visible reasoning

Readable reasoning depends on the selected provider. Send reasoning.exclude: falseto allow it in the response. GPU Router passes through returned message.reasoningand reasoning_details; streamed replies use delta instead ofmessage. For a reasoning.summary entry, display its summarytext. Astra returned these readable summaries through a reference route in live checks.

A reasoning.encrypted entry is opaque continuation data, not display text. It cannot be decrypted by the gateway. A response can contain both formats, or no readable summary. Reasoning token counts alone do not mean displayable text was supplied. Native Responses reasoning.summary settings and replay of OpenAI encrypted reasoning history remain unsupported by these Chat Completions endpoints. See OpenAI’s reasoning summary guide.

Image-generation availability

OpenRouter-only models have been removed, including the dedicated image-generation model. Image generation and reference-image editing are currently unavailable. Use /catalog/models to check current model availability; supported chat models still accept images for understanding.

Image inputs

Chat Completions currently supports image inputs for google/gemini-3.1-pro-preview, google/gemini-3.1-flash-lite, google/gemini-3.5-flash, openai/gpt-5.6-luna, and openai/gpt-6-astra. Use their exact model IDs or current agent aliases. Additional routes require an exact supported contract, compatible image accounting and reviewed evidence before operators adopt them. Catalog discovery alone does not enable a model or start paid verification. Check routes[].imageInputs in /catalog/models for a fresh supported offer and check its supportedParameters for your controls. The route’s eligible flag describes default text routing; a reference route may appear as a fallback there while imageInputs.supported is true. Astra image requests can use verified discounted routes, including reasoning and tools where that combination is supported. Other profiled models retain their verified reference routes. Capability flags alone do not guarantee every combination of images, tools, cache, and reasoning; incompatible routes are excluded without stripping those inputs. Discounted pricing is not guaranteed, and explicit discount limits stay in force.

In a user message, mix { type: "text", text: "Describe this" } and { type: "image_url", image_url: { url: "https://example.com/image.png", detail: "high" } }. Use a public HTTPS image URL or a data:image/png;base64,... URL (PNG, JPEG, or WebP). Up to 8 images are accepted, with at most 5 MiB decoded per inline image and 8 MiB for the entire JSON request including base64. Resize or use public HTTPS images when the request is too large. Private addresses, credentials in URLs, and non-image data are rejected. The provider retrieves remote images; GPU Router does not download them.

Text/image order, URLs, cache markers, reasoning, and streaming settings are preserved. An optional image_url.source label is accepted for application bookkeeping and omitted upstream. Gemini accepts auto, low, and high; Luna and Astra also accept original. Omitted detail stays omitted. These inputs are supported on /v1, /v1/agents, and /v1/cursor Chat Completions, including prior user messages. System/assistant/tool images, audio, and hosted computer-use tools are not supported. The agent endpoints also translate URL-based input_image parts in Responses-shaped user input. This does not enable a native /responses endpoint. Text-only privacy redaction cannot process image pixels, so requests combining images with the privacy option are rejected.

Image reservations use conservative model/detail token allowances and published pricing premiums. Some discounted suppliers reserve the full image allowance even for low detail until their detail-specific tokenization is verified; unused reservation is released after settlement. Final billing uses the provider receipt, not URL or base64 text length. Reported prompt_tokens includes image tokens. Read final streamed usage; missing usage is not a zero-token image request and must not be estimated from its URL. Start with a small image before enabling screenshots in an editor. The editor must send the supported Chat Completions shape and respect these limits.

Sources: Reference provider image inputs, Gemini image token limits, OpenAI image detail and tokenization.

Costs, cache, and pending credits

Prepaid requests are billed from the provider’s final charge, after cache discounts. Savings are capped at 95%. Activity shows tokens, reported cache reuse, your total cost, savings, and gateway/provider time. “—” in the Cache column means no usable count was recorded; it does not prove a cache miss. A reported zero shows “No hit”; a reported hit shows the reused token count and percentage. Short Gemini replies can omit the field even when longer repeated prompts report cache reuse.

Savings compare the same model and reported cache use at list rates. When cache reads are missing, the comparison assumes zero reads and is labeled “estimated”; the Cache column still shows “—”. Missing or unsupported cache-write charges are excluded from the comparison. Expand Savings to see the amounts and assumptions. This display comparison does not change historical charges or stored savings.

Check both your available balance and the key’s remaining allowance in API Keys. Choose Edit next to a key’s allowance to change its lifetime limit or select Unlimited. Existing usage still counts toward a new limit. Pending reservations are already excluded from available funds. Failed prepaid attempts release their customer hold before a retry. A failed or stopped request that nothing retries is billed what the provider billed for it, plus the routing fee; completed requests settle against their final bill. Interrupted requests have automatic recovery, so refreshing the page is not what releases a hold.

Gemini tool-call history

Keep each returned assistant message with its tool calls, IDs, and metadata when adding tool results. GPU Router supports Gemini signatures in tool_calls[].extra_contentand the google-gemini-v1 entries in reasoning_details used by OpenAI-compatible SDKs, including streamed replies. The conversion preserves the original signature; it cannot recover metadata that a client has already discarded.

A 400 missing_tool_signature means the tool history needs repair, rather than another provider retry. Preserve the returned metadata in your SDK or start a new conversation if it was lost. Other encrypted reasoning formats and hosted tools remain unsupported. See Google’s signature requirements and Reference provider’s reasoning metadata format.

Troubleshooting

• The model you chose is not available: check the environment dropdown under the message box. Switch Cloud to Local and start a new chat. Cloud Agents do not use desktop BYOK keys; changing the alias or gateway URL cannot enable them.
• Custom model not supported: use the exact router-* ID, enable it, select it in a new chat, and check your Cursor plan. Adding a duplicate of a built-in model can fail inside Cursor.
• Rate limited: run the curl check. A GPU Router 429 includes rate_limit_exceeded and Retry-After; wait before retrying. If curl works but Cursor fails, collect the Cursor version, Request ID, and complete error text. Cursor can show a generic rate-limit error for provider-routing problems.
• 401 / 402: check the key for 401. For 402, check both the available prepaid balance and the key’s remaining allowance, including pending reservations. The error identifies an API key spending limit, pending funds, or an insufficient account balance. Adding credits does not raise a key’s spending limit; edit the existing key’s allowance in API Keys. Long conversations can require a larger reservation than their final bill because cache hits are confirmed after the request. An upstream provider running out of credits is handled as a routing failure.
• 400 unsupported features: choose a model with function-tool support, remove image/file/audio attachments, or shorten the conversation. This adapter supports stateless text and function calls, including Gemini tool signatures; stored Responses conversations and other encrypted reasoning formats, hosted tools, and automatic context truncation are not supported.
• Wrong provider or model: check the alias mapping and the actual provider shown in Activity. Turning off the base URL override restores Cursor’s normal provider configuration.

Tab completion continues using Cursor’s own models. A custom endpoint does not enable every Cursor feature. Cursor sends BYOK requests through its servers to assemble prompts, so this setup does not create a direct local-only connection.

References: Cursor BYOK documentation, Cursor’s payload-format issue, model-name routing behavior, Cloud Agent model restrictions, Cursor’s explanation of Cloud BYOK limits.