Base URL Guide

OpenAI-Compatible API Base URL Checks

OpenAI-compatible means a provider exposes an API shape that many tools can call. It does not prove model identity, pricing accuracy or Cursor/Codex compatibility. Use this checklist before adding a key, balance or repository context.

What OpenAI-Compatible Really Means

A compatible provider usually accepts OpenAI-style requests, but each tool can depend on a different subset of endpoints, model IDs, streaming events, error formats and auth behavior. Treat compatibility as a starting point, not a guarantee.

Base URL Checklist

  • Confirm whether the base URL should be the root gateway, `/v1`, or a provider-specific path.
  • Do not paste the full `/chat/completions`, `/responses` or `/models` endpoint into a Base URL field.
  • Check whether the provider supports `/v1/models` so tools can discover available model IDs.
  • Record the exact model ID you tested, not only the marketing model family.
  • Verify streaming, tool-call shape, JSON mode and error response format if your workflow depends on them.

Tool-Specific Checks

  • Cursor custom keys may only cover some chat workflows; specialized Cursor features can still use built-in model routes.
  • Codex CLI custom providers may need Responses-style behavior, not only Chat Completions-style compatibility.
  • Cline and OpenAI SDK workflows usually care most about `/v1`, model IDs, streaming and retryable error formats.
  • Claude Code normally needs Anthropic-compatible behavior; an OpenAI-compatible endpoint alone is not enough.
  • If a provider publishes a dedicated Cursor, Codex CLI, Cline or SDK guide, prefer that over generic setup snippets.

Pricing and Model Evidence

Gateway prices often vary by provider route, cache reads/writes, context length, image/audio usage and failed requests. Before testing, save the pricing page, model list and any provider route details so later billing differences can be explained.

  • Normalize pricing to 1M input tokens and 1M output tokens.
  • Check cache write/read prices separately when a model supports caching.
  • Look for minimum top-up, refund rules, failed-request billing and rate-limit behavior.
  • If a model has multiple provider routes, record which route the gateway selected.
  • Keep a small test prompt and billing screenshot for future comparison.

Small Test Flow

  1. Open the provider docs, pricing, model list, privacy policy, terms, status page and support page.
  2. Use the public source checker to record missing fields before adding any key.
  3. Run a non-sensitive test with the smallest balance or free credit available.
  4. Test model listing, a short chat, streaming, a small code task and one deliberate error.
  5. Only persist the key in your editor or CLI after the endpoint, model ID and billing behavior match the docs.

When to Avoid a Gateway

Avoid third-party gateways for private repositories, production secrets, customer data or regulated workloads unless the provider gives you a credible data-handling and contract path.

For sensitive work, start with official APIs, cloud-provider channels, enterprise gateways or self-hosted BYOK infrastructure. Use relay providers first for public-code tests and low-risk experiments.

FAQ

Is OpenAI-compatible the same as official OpenAI?

No. It usually means the request shape is similar to OpenAI's API. The upstream model, billing, privacy controls, rate limits and error behavior can still differ.

Should a Base URL include /v1?

Sometimes. Some providers ask for the root gateway URL, while others expect `/v1`. The safe rule is to follow the provider's current docs and never paste a full endpoint such as `/v1/chat/completions` into a Base URL field.

Can every OpenAI-compatible provider work in Cursor?

No. Cursor support depends on the current Cursor settings UI, supported model type, Base URL override behavior and whether the workflow uses built-in Cursor model routes.

What should I verify before adding balance?

Verify docs, pricing, model IDs, privacy, terms, status and support first. Then run a small non-sensitive test and compare billing against the published pricing page.