Provider Keys
Fal, Wavespeed and ElevenLabs do not sell their capacity below list. Other people's accounts do — a seller who already pays for a provider lists the key they are not fully using, and you call it through us at a discount.
You keep one base URL and one Surplus API key. There is no second credential, no contract, and nothing to reserve: every call is routed on its own to the cheapest offer that can serve it.
This page is the shape of the market. If you want to make a call now, start with your first call, then the page for your provider — Fal, ElevenLabs or Wavespeed.
Calling one
The path after the provider is the provider's own. Two shapes, and the difference matters:
| Provider | What you call |
|---|---|
| Wavespeed, ElevenLabs | POST {base}/v1/resources/{provider}/{the provider's path} |
| Fal | point the SDK's proxyUrl at {base}/v1/resources/fal and append nothing |
POST {base}/v1/resources/{provider}/{the provider's path}proxyUrl at {base}/v1/resources/fal and append nothingFal's SDK adds the model itself, so a URL with the path already on it is a 404. It is the one provider whose path stays empty, and getting it wrong is the most common first mistake.
Your Surplus API key authenticates the call and your existing balance pays for it.
What a call costs
The response says, on every rail:
| Header | What it is |
|---|---|
x-si-buyer-cost-micro | what you were charged, in microdollars |
x-si-list-cost-micro | what the provider would have billed |
x-si-buyer-cost-microWhat it is · what you were charged, in microdollarsx-si-list-cost-microWhat it is · what the provider would have billedThe difference is what the key market saved you. One offer carries one discount for everything it serves — there is no per-capability price list, and a provider's row shows the best discount with the median behind it so you can see whether that price holds if one seller pauses.
What is never callable
Three things are refused no matter who lists what:
- Account routes. Billing, team members, API keys, usage and plan settings. We only ever call the provider's own API host, and this fence is ours — no seller can widen it.
- Anything we cannot price. A call we cannot put a number on is refused rather than guessed at, so you are never billed an estimate.
- Streaming. Not in this release: a streamed response cannot be metered the way settlement needs, so it is refused rather than mis-billed.
A seller can narrow their own key further. Access rules on a provider key is the full reference for how that decision is made.
Requiring something of the account
Some sellers advertise properties of the account behind their key — zero data retention, an EU region, a business plan. You can require any of them, per call or as a default:
curl {base}/v1/resources/fal/… \
-H "Authorization: Bearer $SURPLUS_API_KEY" \
-H "X-SI-Require: data.zdr,residency.eu"A call that requires something only reaches offers that claim all of it. If none can, the call is refused
with trait_unavailable — it is never quietly served by an offer that does not qualify. That is the whole
point of the header, and it is why requiring something can raise your price: the pool is smaller.
What a badge is worth
Every trait carries its provenance, everywhere it appears, and the three are not interchangeable:
| Badge | What it means |
|---|---|
| Verified | We measured it. |
| Documented | The seller supplied the provider's own confirmation for that account, and an operator accepted it. |
| Claimed | The seller's word, and nothing else. |
Most traits can only ever be Claimed — there is nothing about someone else's account configuration that we can check from outside, and we would rather say so than imply a check we did not make. A false claim removes the listing and holds its earnings, which is the enforcement behind the word.
When a call does not land
Each refusal names one cause, so you can tell whose problem it is:
| Code | What to do |
|---|---|
platform_route_refused | Nothing — never reachable, for any seller. |
policy_refused | No seller's rules allow this call. Wait for one who does. |
seller_cap_reached | Every capable offer spent its daily cap. Resets at 00:00 UTC. Retryable. |
offers_unhealthy | Every capable offer is backed off after failures. Retryable. |
no_resource_offer | Nobody lists this provider yet. |
provider_unpriceable | We cannot price the call. Use a model we can. |
trait_unavailable | Nobody advertises what you required. Drop it, or wait. Retryable. |
insufficient_credit | Top up. |
platform_route_refusedWhat to do · Nothing — never reachable, for any seller.policy_refusedWhat to do · No seller's rules allow this call. Wait for one who does.seller_cap_reachedWhat to do · Every capable offer spent its daily cap. Resets at 00:00 UTC. Retryable.offers_unhealthyWhat to do · Every capable offer is backed off after failures. Retryable.no_resource_offerWhat to do · Nobody lists this provider yet.provider_unpriceableWhat to do · We cannot price the call. Use a model we can.trait_unavailableWhat to do · Nobody advertises what you required. Drop it, or wait. Retryable.insufficient_creditWhat to do · Top up.Related
- Your first call — the end-to-end path, with working examples.
- Fal, ElevenLabs, Wavespeed — each provider's exact routes.
- Jobs and settlement — async jobs, and exactly when you are charged.
- Listing your key — the seller side, end to end.
- Provider key endpoints — the endpoint reference.
- Access rules on a provider key — the three checks, in order.
- Pricing — how a call is priced and what a discount comes off.
- Security and privacy — what reaches a seller's account, and what never does.