Catalog

Access tiers

Every model sits in one of three tiers. The tier decides who may call it, independently of price.

Tiers

Field	Type	Description
`free`	any account	Callable on every plan, including the free one, within a daily token allowance.
`paid`	plan or balance	Needs an active paid plan or a positive wallet balance. Trial credit counts.
`premium`	plan or deposit	Flagship models. Covered by any active plan, or callable from a wallet with real deposited balance. Promotional and bonus credits alone do not unlock this tier.

Why premium is separate#

Flagship models cost several times more per token than the rest of the catalog. Keeping them off promotional credit — rather than treating every credit as equal — is what stops an account created for a promotion from being worth more than it cost.

Pay-as-you-go models#

A few models are pay-as-you-go: they are billed from your wallet on every request and are never covered by a plan's allowance, whatever plan you hold. The rule is strict for premium ones:

Pay-as-you-go by tier

Field	Type	Description
`paid + pay-as-you-go`	wallet balance	Needs a positive wallet balance. Promotional credit counts. A plan does not cover it.
`premium + pay-as-you-go`	real deposit only	Needs real deposited balance in the wallet. Plans, promotional credit and manual unlocks do not apply — this is the only tier where nothing but a top-up works.

How a plan and a wallet interact

A plan covers free, paid and premium models that are not pay-as-you-go, up to its allowance window. Once the window is used up, requests fall back to the wallet (if you have enabled that) and follow the wallet rules above. Pay-as-you-go models skip the plan entirely and go straight to the wallet.

What a blocked call looks like#

Free plan calling a paid model

{
  "error": {
    "message": "This is a premium model. The Free plan only allows free models — upgrade your plan or top up your wallet to use it.",
    "type": "permission_error",
    "code": "permission_denied"
  }
}

Paying account calling a premium model

{
  "error": {
    "message": "This model requires a paid account. Top up your wallet or subscribe to a plan to unlock it.",
    "type": "permission_error",
    "code": "permission_denied"
  }
}

Both are 403. Retrying will not help — the request is valid, the account is not entitled. Surface it to whoever can change the plan rather than looping. See Error codes.

Tiers are checked against the model you name#

Entitlement is checked against the model in your request.

Checking a model's tier from code#

GET /v1/models is public and identical for everyone — it lists the whole active catalog, not what your account may call. But each entry now carries an access_tier field (free / paid / premium), so a client can filter the catalog to the tiers its account can reach instead of discovering a 403 at request time. The gate itself still runs on every request; the field is the map, not the door. Plan details and current balance are in the dashboard.

Models a free account can call

curl -s https://api.xkiro.com/v1/models \
  | jq '[.data[] | select(.access_tier == "free") | .id]'

For what each tier costs and how usage is metered, see Pricing & billing.