Bring your own key (BYOK)
Use your own provider account through AI Hub. The provider bills the model usage to you; AI Hub adds a routing fee and keeps your keys, caps, activity and analytics in one place.
Who it is for
Teams that already hold a contract or committed spend with a model provider and do not want to move that billing, but want workspace controls, per-key caps, activity logs and analytics in the same console as the other AI Hub models.
How to get it
BeLive switches BYOK on for an organization. Ask your BeLive contact. Until it is on, Settings shows no provider keys section and every request is priced at the AI Hub price. The providers you can add a key for are listed in Settings for your organization, each with what its key covers.
What a key covers
A key covers chat, images, video, or a mix, depending on the provider. Settings shows the coverage of each provider next to its name, read from the API, so that list is the one that applies to your organization.
| Provider | Chat | Images | Video |
|---|---|---|---|
| OpenAI | Yes | OpenAI image models | None |
| BytePlus ModelArk | Yes | Seedream models | Seedance 2.0, 2.0 Fast, 2.0 Mini and 2.5 |
| Google AI Studio | Yes | Google image models (generation, not editing) | Not yet |
| Anthropic | Yes | None | None |
- An OpenAI key stored for chat also serves OpenAI image requests. There is no separate image key.
- A model that your key's provider does not serve on your key runs on AI Hub capacity at the full AI Hub price. Today that includes Google video models and Google image editing: a stored Google AI Studio key does not change them.
- Video is asynchronous: you submit a job and poll it. See Video jobs on your key below.
Add a key
- Add the key in Console → Settings → Provider keys.
- A key belongs to one workspace. A workspace can hold up to 20 keys per provider. Add the key in each workspace that should use it.
- Only the organization owner can add, change or remove a key. Admins can verify a provider's first Prioritized key.
- To replace a key's secret, add the new key and then remove the old one. A key's secret cannot be edited.
- A key is write-only. AI Hub encrypts it with a key held in AWS KMS and never shows it again, so you can replace or remove a key but not read it back.
- A provider key is used only for requests from your own workspaces.
How a request is routed and priced
Once a key is stored, a request to that provider that the key covers is sent with your key, and the provider meters it on your account. AI Hub records the request as usual and charges the routing fee.
| Item | What happens |
|---|---|
| Routing fee | A routing fee (currently 5%) of what the same request would cost at the AI Hub price. For an image or video request that is the AI Hub price of the endpoint that ran it. It is taken from your organization's AI Hub account per request. Settings shows the current rate. |
| Monthly minimum | None. |
| Provider usage | The provider bills the request to your own account at its own price. |
| A call that fails without usage | Nothing is charged. |
For an image or video request on your key, usage.cost and usage.tokenhub_cost in the response are the routing fee alone, not the price of the generation. POST /api/v1/media/offers marks an offer that would run on your key with credential_source: "byok", and its quote.amount_usd is then the routing fee only.
Video jobs on your key
- A video job keeps the key it was submitted with. Changing a key's order, scope, on/off switch or shared-capacity choice affects new requests only.
- If you remove or replace that key while a job is running, the job ends and AI Hub charges nothing. The job fails with error code
byok_key_unavailable. If the provider refuses the key, the job fails withbyok_key_refused, also at no charge. - Reading the output of a finished job after its key was removed or replaced returns
409 conflictwithmetadata.reasonset tobyok_key_unavailable. AI Hub does not keep a copy of video made on your key. - BytePlus output links expire after 24 hours. Fetch the video from the job within that time, before you remove the key.
Several keys, tiers and scope
A workspace can hold several keys for one provider, for example one per team account. Each key has these settings, all editable in Settings → Provider keys:
| Setting | What it does |
|---|---|
| Tier | Prioritized keys are tried before AI Hub capacity. Fallback keys are tried after it. |
| Order | The key's place within its tier. Move a key up or down to change it. |
| On | An off key is kept but serves no new request. |
| Models | The models the key serves: all, or a list you choose. |
| API keys | The AI Hub API keys of the workspace whose requests may use the key: all, or a list you choose. |
| AI Hub shared capacity | What happens when the key cannot serve. See below. |
A request uses a key only when the key is on, active, covers the requested model and covers the AI Hub API key that made the request. A list that is empty means all.
For one request, AI Hub tries:
- The Prioritized keys that apply, in the order shown.
- AI Hub capacity, where the shared-capacity choice of your keys allows it.
- The Fallback keys that apply, in the order shown.
AI Hub moves to the next candidate when the provider refuses a key, rate-limits it or answers with a server error. A key the provider refuses is marked invalid in Settings. A video request takes the first key that applies and does not retry on another key.
Shared capacity
Each key has one of three choices for AI Hub capacity. It is Never for this key's models until you change it.
| Choice | What happens when the key cannot serve |
|---|---|
| Never for this key's models | AI Hub capacity of this provider is not used for the models the key covers. If no other key serves the request, it fails and nothing is charged. |
| Never for this provider | AI Hub capacity of this provider is not used for any model of the provider while the key is on. |
| Use shared capacity | The request can run on AI Hub capacity at the full AI Hub price. The routing fee does not apply to that request. |
- The choice removes only the key's own provider's capacity. Another provider's AI Hub capacity for the same model can still serve the request at the full AI Hub price.
- A choice applies to the requests the key applies to: those of the API keys in its API-key scope, and, for Never for this key's models, the models in its model scope.
- If several keys for one provider disagree, one key set to a "never" choice is enough to remove that provider's AI Hub capacity.
- An off key does not remove AI Hub capacity. A key the provider refused (invalid) still does, so the request fails instead of spending AI Hub capacity you did not allow.
When your key is refused
When no key can serve a request and no AI Hub capacity is allowed, the request fails and nothing is charged. A refused key returns 502 with error type byok_key_refused. A rate-limited key returns 429 rate_limit_exceeded with metadata.reason set to byok_key_rate_limited.
When a key's shared-capacity choice is Use shared capacity, the request is retried on AI Hub capacity at the full AI Hub price, and the routing fee does not apply.
A refused key is marked invalid in Settings. Add a working key and remove the invalid one, or switch shared capacity on, to restore service. The AI Hub key you call the API with is not affected: the error does not mean your AI Hub key is wrong.
See which key served a request
- Every chat, image and video response carries
X-TokenHub-Credential-Source, with the valuebyokwhen your key paid the provider andsharedwhen AI Hub capacity did.usage.is_byokistrueon a request that used your key. - Each item from
GET /mgmt/v1/activityhascredential_source(byokorshared) andplatform_fee_usd, which is the routing fee for a BYOK request andnullwhen no fee applies. See Management API. - The console Activity view shows Your key on a request that used your key, with the routing fee as its cost, and key refused on one your provider refused. A video job ended by key removal or refusal shows like any other refused request that was not charged; its exact ending is the job's error code.
Prompt caching, batch and structured outputs behave as the provider defines them when you bring your own key, because the provider meters the request.
See Workspaces & governance for how workspaces and roles fit together, and Cost for how AI Hub prices a request.