A two-minute code change, and one guided path to your first request.
You always get the model you asked for. A cheaper model serves a call only where a recorded test already covers that exact job. If it refuses or returns malformed output, we re-run the call on your model at our expense.
- A human issues the key. In the console, at /console/keys#door1. The key is shown once. A coding agent can do every other step but never sees key material, and that boundary is written into the agent instructions themselves.
- The models you arrive with are recorded. At issuance we record the models you came with as your baseline. A pricier recommendation cannot join that baseline unless you independently run it in production for a defined window, so nothing we suggest can raise the number we bill against.
- You add prepaid credit. We pay your provider for you and pass the price through, so a funded balance is a real prerequisite rather than a surprise after setup. Funding goes through card checkout and its signed webhook.
- You change a base URL and a key. On the supported OpenAI Chat Completions or Anthropic Messages client you already use. Model ids stay exactly as they are; we never rewrite them, and we never opt you into finest/auto.
- You run the connection check. A no-charge models request proves the gateway URL, key kind and admitted model catalog before you move one application request.
- Traffic flows, receipted. Every request we serve gets a receipt: the model you asked for, the model that served it, both prices, and the saving. If our accounting is ever unavailable we refuse the request rather than serve it unrecorded. You are never billed for something we cannot show you.
Both lines below are the whole change. Your model names stay exactly as they are.
baseURL: 'https://gateway.finest.so/gateway/openai/v1' apiKey: process.env.FINEST_API_KEY // fk_…
Keep your provider key in the environment. With it present, our one-line client library falls back to calling your provider directly, but only when the response proves we refused the call before it reached them. A network failure is ambiguous, because the provider may already have accepted the request, so that error is returned unchanged rather than risking one call becoming two. Without the shim, every gateway failure remains your application error: that is the trade the two lines above make on their own.
You do not have to tag anything. Two optional tags exist. Send metadata.finest_route (or the x-finest-route header) to name a route once you have your own test results for it. Send metadata.finest_no_demote: true (or x-finest-no-demote: true) whenever one request must stay on the model you named.
Need the request handled in a particular place? Send metadata.finest_residency or the x-finest-residency header, naming a region such as eu. It is a hard requirement, not a preference, and it is applied before any price is compared. finest/auto picks only from endpoints that satisfy it, and a demotion, the swap to a cheaper model, is refused when its target cannot prove it does. An endpoint that declares nothing counts as failing, because unproven residency is not residency. If nothing in our catalogue qualifies, the request is refused with the region named rather than served from somewhere else. What it does not do is block a model you asked for by name: that choice is yours.
- A Finest key, issued by a human in your console.
- Prepaid credit, because we pay the provider for you and pass the price through.
- Your provider key left in your own environment, if you want the direct fallback described above.
- Route tags, test data or graders to start. Every tag is optional.
- A model-id change. We serve what you asked for, and finest/auto is opt-in.
- A hidden retry. An ambiguous network failure stays visible, so one call cannot become two.
- A contract that stops you leaving. Eject is a feature we advertise.
Tokens debit your prepaid balance at the provider’s own price. When a cheaper model saves money against the model you asked for, we take a quarter of that saving and you keep the rest. A top-up lasts longer than it would have, and we earn only when it does. finest/auto is flat-priced and never savings-share priced, because the thing we choose for you must not be able to increase what we charge.
Your worst case is exactly what you asked for, at the provider’s price. When a cheap attempt fails and we re-run it on the model you named, you pay that model’s price and nothing more. The failed attempt is ours, and it never carries a share. The share itself is debited from your prepaid balance on the request that earned it.