AI Model Configuration

If your product uses AI, you decide which models your tenants can reach. Backbuild ships a catalog of ready-to-use AI models, and you can add your own on top of it. For each SaaS package you publish, you curate that catalog down to the exact set of models your product offers, turning some on and leaving others off, so your tenants only ever see and use the models you intend to sell.

Pro AI model configuration is part of the SaaS Builder, included with the Backbuild Pro build-and-ship platform. See pricing.

How model availability works

Two kinds of model can appear in your product:

  • Built-in models: the curated catalog of models Backbuild maintains and keeps up to date. You don’t configure the provider connection for these; you just decide whether each one is offered in your package.
  • Your own models: models you register for your organization (for example, a provider or deployment you bring yourself). These behave the same way: each can be switched on or off per package.

By default, a package inherits the available models. The package-level configuration is an override layer: for each model you can explicitly enable it for the package or explicitly disable it. This lets you offer a deliberately small, supported set (a single fast model on an entry plan, a broader selection on a premium product) rather than exposing every model that happens to exist.

The model-availability view

When you list a package’s models you get one row per available model, each showing whether it is currently enabled for that package:

FieldTypeDescription
model_iduuidThe identifier of the model.
display_namestringThe human-readable model name shown in your product’s UI.
model_stringstringThe model’s technical identifier (the value your application passes when it makes an AI request).
is_system_modelbooleantrue for a built-in catalog model, false for one of your own registered models.
is_enabled_for_packagebooleanWhether this model is currently offered in this package.
GET /v1/saas-packages/{packageId}/ai-models
Authorization: Bearer <token>

The list is paginated. Pass page and page_size (defaults to 50, capped at 200) as query parameters.

{
  "data": [
    {
      "model_id": "019d-aaaa...",
      "display_name": "Fast Chat",
      "model_string": "vendor/fast-chat-1",
      "is_system_model": true,
      "is_enabled_for_package": true
    },
    {
      "model_id": "019d-bbbb...",
      "display_name": "Deep Reasoning",
      "model_string": "vendor/deep-reason-1",
      "is_system_model": true,
      "is_enabled_for_package": false
    }
  ],
  "meta": { "page": 1, "page_size": 50, "total": 2, "total_pages": 1 }
}

Choosing the models your product offers

You set a package’s model availability by sending the toggles you want to change. Each override names exactly one model, either a built-in catalog model (by system_model_id) or one of your own (by org_model_id), and states whether it is enabled.

Toggle several models at once

The batch endpoint applies all of your changes atomically: either every toggle in the request is saved, or none is. Send between 1 and 200 overrides in a single call.

PUT /v1/saas-packages/{packageId}/ai-models
Authorization: Bearer <token>
Content-Type: application/json

{
  "overrides": [
    { "system_model_id": "019d-aaaa...", "is_enabled": true },
    { "system_model_id": "019d-bbbb...", "is_enabled": false },
    { "org_model_id":    "019d-cccc...", "is_enabled": true }
  ]
}
FieldTypeDescription
system_model_iduuidThe built-in catalog model to toggle. Provide this or org_model_id, never both.
org_model_iduuidOne of your own registered models to toggle. Provide this or system_model_id, never both.
is_enabledbooleanWhether the model is offered in this package.

Each override must set exactly one of system_model_id or org_model_id. Setting both, or neither, is rejected with a validation error.

Toggle a single model

To change just one model, use the single-override endpoint. It accepts the same shape as one entry of the batch request.

PUT /v1/saas-packages/{packageId}/ai-models/override
Authorization: Bearer <token>
Content-Type: application/json

{
  "system_model_id": "019d-aaaa...",
  "is_enabled": false
}

Only the three fields above are accepted; any other key is rejected. The owning organization and package are taken from your session and the URL, not from the request body.

Per-plan model availability

The model toggles above scope a model to the whole package. To make a richer model available only on a higher tier, pair model availability with feature flags: gate the premium model behind a feature flag, map that flag to your upper plans, and have your application check the tenant’s effective feature set before offering the model. The package decides which models exist in your product; plan entitlements decide which tenants get to use each one.

A common pattern:

  • Enable a single fast, inexpensive model for the package and leave it ungated, so every tenant can use it.
  • Enable a more capable (and more expensive) model for the package, but gate it behind an advanced-ai feature flag mapped only to your business and enterprise plans.

Paying for AI: universal credits vs. bring-your-own-key

There are two ways the AI your product runs on can be paid for. You choose the model that fits how you want to package and price AI usage.

Universal credits

With universal credits, AI usage runs on Backbuild’s managed providers and is metered as credits. You don’t manage provider API keys at all. Instead, you decide how many credits each plan includes (and how overage is handled), and your tenants consume from that allotment as they use AI features. This is the simplest path: your tenants never see a provider, and AI cost is folded into the price of the plan you sell.

Bring-your-own-key (BYOK)

With bring-your-own-key, you (or, where you allow it, your tenant) supply the credentials for an AI or messaging provider, and usage is billed by that provider directly rather than metered as Backbuild credits. Provider credentials are configured through the integrations surface, stored encrypted, and never returned to the client or written to logs. See Integrations for how to connect and test a provider. BYOK suits products whose customers expect to run on their own AI accounts, or where you want AI cost to sit outside your plan pricing entirely.

The two approaches are not mutually exclusive across your catalog: a built-in model can be offered on credits while a registered model you connect runs on your own key. In all cases, model availability (which models appear at all) is controlled by the package toggles described above.

Provider keys and key pools

Keys and pools is being rolled out. It appears under AI Model Config once it is turned on for your organization; until then your AI usage keeps working exactly as it does today.

When your organization runs AI on its own provider accounts, one key per provider is rarely enough. You may hold a production account, a few test accounts, and promotional credits you want spent first. The Keys and pools tab lets you add as many keys as you need for each provider and group them into pools, so requests keep flowing when one key runs out, and you decide which work each key is allowed to serve.

Keys

  • Add key stores a new key encrypted, or maps a key you already keep in your organization’s vault. A stored key is never shown again.
  • Mark a key Internal only for promotional or test credits: it serves your own organization and never your customers.
  • A Billing reader key is the admin key some providers require for balance and usage reads. It is never used to run requests.
  • Keys that share a provider account share one credit figure, so a balance is never counted twice.

Pools

  • A pool groups keys and sets how a key is chosen, for example the key with the most balance remaining or the credits that expire soonest.
  • Each pool states who may use it: internal use by your organization, named customers and packages, chosen environments, or production only. A new pool serves nothing until you allow it.
  • Pools are tried in the order you set. Turn on When every key is unavailable, try the next pool so a request moves on instead of failing.
  • Designate one pool as your organization’s internal usage pool and every member sees a usage meter (in the header, or beside the sidebar’s quick actions on wider screens) showing how much of the month’s allowance is left.

Quotas and credit sources

Set quotas so no single person or team can drain a pool: per member, or shared by a group, role or department, in usage credits for credit-funded use or in dollars for your own provider accounts, by day, week or month. A request that would pass a quota is refused before it reaches the provider, and members see what remains in plain words. Credit sources record what each provider account holds, so the meter and the selection policy work from real balances.

Changing keys, pools and quotas needs the AI management permission in your organization. Every change is recorded in your audit log.

Permissions and scope

Reading and changing a package’s model configuration requires an authenticated session with rights to manage the package; the owning organization is always resolved from your session, and you can only configure packages your organization owns. The AI-model endpoints are available only when the SaaS Builder capability is enabled for your account.

API reference

All endpoints require an authenticated session. {packageId} is your SaaS package’s id. The owning organization is resolved from your session.

Method & pathDescription
GET /v1/saas-packages/{packageId}/ai-modelsList every available model with its enabled state for the package. Paginated via page / page_size.
PUT /v1/saas-packages/{packageId}/ai-modelsBatch-toggle model availability for the package (1 to 200 overrides, applied atomically).
POST /v1/saas-packages/{packageId}/ai-models/overrideToggle availability for a single model.
PUT /v1/saas-packages/{packageId}/ai-models/overrideSame as the POST form: toggles a single model.

Override fields

Each override (whether in the batch array or the single-override body) sets exactly one of system_model_id (a built-in catalog model) or org_model_id (one of your own registered models), plus is_enabled (boolean). Supplying both ids, or neither, is a validation error.

Related

Frequently asked questions

Can I control which AI models my product offers?
Yes. As the publisher you choose which models your downstream tenants can access, rather than exposing everything by default.
Can model access differ by plan?
Yes. You can set model availability per plan, so a higher tier can unlock more capable models.
Can I use several API keys for the same provider?
Yes, once Keys and pools is turned on for your organization. Add each key, group them into pools, and requests move to the next key or pool when one runs out. See Provider keys and key pools.
Can I stop one person from using up our AI allowance?
Yes. Quotas cap each member, or a whole group, role or department, per day, week or month, and a request over the cap is refused before it is sent.
Who pays for the AI usage?
Either universal usage credits or a bring-your-own-key arrangement, as published on the pricing page.