DEVELOPER DOCUMENTATION

Cline setup

Use your GPU Router key and a custom Chat Completions provider.

Official setup documentation checked September 13, 2026.

Automated gateway tests cover request formats reconstructed from Zed, Continue, Cline, OpenCode, and Aider source code, including conversation replay and streamed replies. These checks do not replace testing inside each app.

← All coding-agent guides and compatibility

Connection details

Create a key in API Keys. New accounts automatically get $1 in free credits; add more in Billing when needed. Use the following base URL for these guides. Existing Cursor configurations can keep /v1/cursor.

https://gpurouter.io/v1/agents

Choose a text model. Native agent tools require a tool-capable route. These aliases identify the actual upstream models; they do not change pricing, model identity, or your client plan.

Current model mapping. Availability and feature support depend on fresh routes. The examples use a 16,384-token context budget and 4,096 output tokens where configurable; these are starter budgets, not the model’s maximum. Lower them for smaller models.

Configure Cline

1. Open Cline settings and choose OpenAI Compatible as the API provider.
2. Set Base URL to https://gpurouter.io/v1/agents, paste your GPU Router key, and set Model ID to COPY_AN_AGENT_MODEL_ID.
3. Start with a 16,384-token context window and 4,096 maximum output tokens. Leave image support and computer-use features off.
4. If Plan and Act use separate model settings, configure the intended modes, then open a new task and verify the selected provider.

Use the OpenAI Compatible entry, which sends Chat Completions. The separate OpenAI/Codex provider may use a different protocol. Begin with a text-only task. Enable images only for a model and request shape covered by the image-input guide.

Source: Cline OpenAI Compatible configuration.

Check the connection

1. In a new chat, ask “Reply OK.” Confirm the actual model and provider in Activity.
2. For tool-based agents, ask it to list files in a scratch project and explain one function. Confirm that a tool result returns and the next assistant turn completes.
3. Try a one-line edit and inspect the diff. In Aider, start with one small file and review its text edit before attempting a broader change.

To isolate gateway configuration from the app, set GPU_ROUTER_API_KEY and run this small, billable request:

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

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

• 404: use the base URL exactly once. The client adds /chat/completions. A request to /responses or /messages means the wrong provider protocol is selected.
• 401 or 402: check the key for 401. For 402, check your available balance and the key’s remaining allowance, including pending reservations. GPU Router’s error identifies which allowance is blocking the request. A key spending limit is separate from account credits; use or create a key with more allowance in API Keys. Reservation estimates do not assume cache hits, so a long conversation may need more available funds than its final bill.
• 400: read the unsupported field or capability in the error. Remove attachments and reasoning options; select a tool-capable route for native tools.
• Tool history rejected: use /v1/agents (or /v1/cursor for Cursor). Both handle empty tool-call lists, retained stream indices, and null optional fields in function definitions. A remaining error identifies the exact message, call, and field, such as messages[5].tool_calls[0].function.arguments. Keep call IDs and tool results together, including Gemini signature metadata; changing model names will not repair malformed history. Other provider reasoning formats and image tool results remain unsupported.
• 429: respect Retry-After when supplied. Account request limits are shared across keys and endpoints. A client’s own plan or provider-routing rejection may happen before a request reaches GPU Router.
• Works in curl, fails in the app: record the app version, model ID, request path, status, and Request ID. Remove keys and private prompts before sharing diagnostics.
• Long sessions: shorten or compact locally. The gateway admits up to 4,096 messages, 128 function tools, and 65,536 output tokens per request; body and credit limits also apply.