AI Allowance #

View this page as Markdown

On this page

AI Allowance lets your backend generate text and images with the platform’s provider key. Calls draw your account’s balance at the provider’s published price plus the markup on the pricing page. Your application receives no provider key and has no monthly AI allowance.

To start, take the package from the library (Use the library), write the transport in The client, and call generateText(transport, { prompt }) from a route. Call an AI model gives the steps.

Read one application’s AI spend this month with tzcloud_read_usage, under ai_allowance_usd_micros. Read the account’s balance, pause state and monthly usage lines with read_balance. Size and usage explains these reads. Read rates on the pricing page, or call read_rate_card.

At a glance:

  • Package: the ai_allowance library entry (Use the library).
  • Settings your server reads: TURNZERO_CLOUD_GATEWAY_URL, or else TURNZERO_CLOUD_API, and TURNZERO_CLOUD_APP_TOKEN.
  • Import: import { generateText } from '@turnzero/ai_allowance';
  • The transport: a function that sends each path to that origin with authorization: Bearer <TURNZERO_CLOUD_APP_TOKEN>. The client has the smallest working call.
  • The call: generateText(transport, { prompt }) returns the answer’s text, usage and an allowance object whose members are null for a customer application.
  • Account pause: a call can throw AllowanceRefusal with refusal: 'account_paused'. Follow The boundary and the fallback.

Use it when #

Use AI Allowance when your backend needs an AI answer or picture without storing a provider key. You can also use the platform’s key for some calls and your own key for others.

Choose the route for each call. This package’s route draws the account’s balance. A call through your own declared upstream, using the Egress client, uses your stored key with no markup or balance charge. Call an external API with an API key sets up that route.

The platform route supports text and image generation on any Gemini model its key can reach. generateText makes text calls; generateImage makes image calls. Generate an image with AI shows one.

A request for audio or video output, paid grounding, a named cachedContent cache, or a separately priced provider tool is refused with allowance_feature_refused. Use your own key through Egress for those features or another provider.

What it provides #

  • The function generateText(transport, request, options), which The client describes.
  • The function generateImage(transport, request, options) returns an image's bytes and type. If you omit the model, it uses DEFAULT_IMAGE_MODEL. Its usage includes imageTokens, the image's token count. It sends one request and does not retry.
  • An allowance object on each result. For a customer application, its used, quota and resetsAt members are null. readStanding(headers) reads those members from a response’s headers.
  • A typed refusal, AllowanceRefusal, thrown for every response the gateway itself wrote, rather than passed on from the provider.
  • A typed upstream error, AllowanceUpstreamError, thrown for a provider response with a non-success status. Its quota member is true where the provider rejected the call because it lacked capacity, the case your application may fall back on.
  • A streamed form: pass onText in the options, and each text fragment arrives in order as the provider produces it. The returned text contains the whole answer.
  • A test double, createAiAllowanceDouble at @turnzero/ai_allowance/testing, which responds in place of the allowance route. Test with the double shows it in use.

If you leave out model, generateText uses DEFAULT_MODEL (gemini-3.6-flash), and generateImage uses DEFAULT_IMAGE_MODEL (gemini-3.1-flash-lite-image). A call may name any Gemini model, one whose name starts with gemini-. A request naming another model is refused 403 allowance_path_refused, and the refusal's detail states that rule.

Calls are charged at the model’s rates in effect if the platform prices it, or at the highest-priced model’s rates in effect otherwise, plus the pricing page’s markup. Input tokens use the input rate. Text output and thinking tokens use the output rate; image output uses the image-output rate. Image tokens are counted once. Cached input uses the cached-input rate, or the input rate where the model has none.

The answer’s usage gives the provider’s inputTokens and outputTokens. These token counts do not report the account’s balance. Use tzcloud_read_usage for an application’s AI spend this month and read_balance for the account’s balance and monthly lines.

For customer applications, no allowance headers are returned. The package preserves the object shape with null members:

Allowance member Customer application
allowance.used null
allowance.quota null
allowance.resetsAt null

Unlimited applications use the plans form. Their answers carry the amount used before the call and the quantity, in micro-dollars, plus the next UTC month’s start. The same form is available in tests with pricing: 'plans'. These fields do not describe a customer application’s balance.

Availability #

Version 0.12.0 is the package's current version, and this page describes it. Until the library's next publish, read_library can return an earlier version, the one you can take. This page can describe a change that version lacks. The entry includes the compiled module, the testing subpath, its product statement and detailed contract, and its integration guide.

The platform’s egress gateway applies its provider key and meters calls. A customer application’s calls draw the account’s balance and carry no allowance headers. A paused account’s call is refused with account_paused.

Egress sends calls on your own stored keys through the same gateway. Secrets stores those keys. Logging records what your backend does with an answer.

The client #

The package is published in the library as the npm package @turnzero/ai_allowance, not on the npm registry; Use the library installs it with one line. The package builds no client object and keeps no state. Each call is one generateText(transport, request, options) or generateImage(transport, request, options), over the transport function your application supplies. Call an AI model shows a complete call from a backend route.

Your transport function takes a gateway path and a request. It adds the platform's origin and your application's credential as the bearer, and returns the response. The platform credential that a deploy gives your copy is bound to its environment and takes no environment header. A call under a minted token bound to the application gives the environment in the header x-turnzero-cloud-environment. The client adds content-type and no other header.

A deployed copy receives the origin as TURNZERO_CLOUD_GATEWAY_URL where the platform gives a separate one, and otherwise as TURNZERO_CLOUD_API. It receives the credential as TURNZERO_CLOUD_APP_TOKEN (A deployed app's settings). So a transport reads the first of the two origins that is set, as Call an AI model shows.

This call, from a deployed copy's backend, sends one prompt and prints the answer, its transport reading the settings above. The guide shows the same call inside a server route. A test runs this sample over the package's test double and checks the answer and the request it sends.

import { generateText } from '@turnzero/ai_allowance';

// The platform's origin and this copy's credential, from the settings it receives.
const origin = process.env.TURNZERO_CLOUD_GATEWAY_URL ?? process.env.TURNZERO_CLOUD_API;
const transport = (path, init = {}) =>
  fetch(origin + path, { ...init, headers: { ...init.headers, authorization: `Bearer ${process.env.TURNZERO_CLOUD_APP_TOKEN}` } });

const answer = await generateText(transport, { prompt: 'Summarize the notes in one line.' });
console.log(answer.text);

Direct HTTP requests #

To call the route without generateText, send a POST to /egress/v0/ai-allowance/v1beta/models/gemini-3.6-flash:generateContent. Use TURNZERO_CLOUD_GATEWAY_URL as the base address, or TURNZERO_CLOUD_API when the gateway setting is absent. Set Content-Type: application/json and Authorization: Bearer <TURNZERO_CLOUD_APP_TOKEN>, using the environment's credential only on that platform address.

The short request below sets no thinking budget. Unlike generateText, which sends zero when you leave it out, it leaves that choice to the provider. To set it explicitly, use generationConfig.thinkingConfig as in the next example. Thinking tokens are charged at the output rate. This request asks for a short text answer:

{
  "contents": [
    { "role": "user", "parts": [{ "text": "Say hello in one short sentence." }] }
  ]
}

A successful answer can contain this candidate. This is an illustrative response, not a promised output:

{
  "candidates": [
    {
      "content": { "role": "model", "parts": [{ "text": "Hello!" }] },
      "finishReason": "STOP",
      "index": 0
    }
  ]
}

Read generated text from candidates[0].content.parts entries with a text member; a response can include other fields, and may contain no text candidate. Direct calls use the provider's contents and generationConfig fields, rather than the package's prompt field. The platform adds the provider's key; do not supply one yourself.

For a direct call, read the HTTP error body as Failures describes. For one of Turn Zero's own unlimited applications, an allowance_exhausted body names its reset time resets_at; the package calls it resetsAt. The boundary and the fallback explains the fallback policy, using the package's names. Its AllowanceUpstreamError is a package wrapper, not a field in a direct HTTP response.

A customer application’s answer carries none of x-ai-allowance-used, x-ai-allowance-quota or x-ai-allowance-resets-at. For an unlimited application, provider answers and allowance_exhausted carry these headers. They supply the three members in What it provides. Other gateway refusals carry none.

Substitute another Gemini model for gemini-3.6-flash as needed, following the model pricing rule. For a streamed answer, use :streamGenerateContent?alt=sse instead of :generateContent. ALLOWANCE_PATH_PREFIX contains the start of the path. Generate an image with AI shows an image call.

This text request gives a system instruction and one user prompt, limits the answer to 128 tokens, and sets the thinking budget to zero:

{
  "systemInstruction": {
    "parts": [
      {
        "text": "Answer in one sentence."
      }
    ]
  },
  "contents": [
    {
      "parts": [
        {
          "text": "Summarize the notes in one line."
        }
      ]
    }
  ],
  "generationConfig": {
    "maxOutputTokens": 128,
    "thinkingConfig": {
      "thinkingBudget": 0
    }
  }
}

Text request and result #

The request takes prompt or messages, never both, and the other fields are optional.

Request field What it does
prompt One user turn's text, in place of messages.
messages The conversation's turns in order, each { role, content }. role is user or assistant, and the last turn is the user's.
system The system instruction, which the model reads separately from the turns.
responseSchema A JSON Schema the answer must satisfy. The answer's text is then JSON: parse it, and check what matters to your application.
maxOutputTokens The most output tokens the answer may hold.
thinkingBudget The model's reasoning budget in tokens, zero when left out. Thinking tokens count as output, so set it only when the answer needs reasoning.
model The model to call, DEFAULT_MODEL when left out.

Every turn you send counts as input on that call, so a long conversation draws more tokens on each call. Sending only the recent turns limits that draw. Do not add an answer with empty text to the conversation, because a turn's content must not be empty.

The options are onText, a function that receives each piece of text as it arrives, and signal, an AbortSignal that ends a call you no longer want. generateText passes options.signal to your transport as init.signal. Pass it to fetch, as the sample above does, or handle it in your transport to abort the HTTP request itself.

Cancellation rejects the call. When the package detects cancellation between streamed reads, it rejects with the signal's reason. Cancellation handled by your transport follows that transport's behavior. If your transport ignores the signal, the package can detect cancellation only between streamed reads.

The call returns text, model, usage with inputTokens and outputTokens, finish (the provider's reason the answer ended, or null), and allowance.

Image request and result #

generateImage(transport, request, options) takes a non-empty request.prompt and an optional request.model, which defaults to DEFAULT_IMAGE_MODEL. Its only option is signal, an AbortSignal. Image calls have no streamed form.

It returns { image, model, usage, finish, blockReason, allowance }. The first non-thinking image part of the first candidate becomes image, as { bytes, mimeType }; where that candidate has none, image is null. bytes is a Uint8Array, and a missing type becomes application/octet-stream.

usage holds inputTokens, outputTokens, and imageTokens. The image tokens are part of the output count, not extra output tokens. finish and blockReason hold the provider's reasons, or null where it gave none.

A malformed prompt throws TypeError before anything is sent. Platform refusals throw AllowanceRefusal, and provider failures throw AllowanceUpstreamError. The function sends one request and retries nothing. Generate an image with AI shows a complete route.

The function readStanding(headers) reads the allowance from the headers of any response of the route, whatever its status. It returns { used, quota, resetsAt }: used and quota as numbers, and resetsAt as the header's time. Each is null where its header is absent, and used or quota also where its header is not a number.

Failures #

On a non-streamed direct HTTP call, a gateway refusal is a JSON body with contract_version, error, and detail. Read the refusal name from error; AllowanceRefusal.refusal is the package's name for that field. The provider's own error body is passed through unchanged. The provider's response has the x-egress-upstream header; a gateway refusal does not. For a provider error, treat HTTP 429 or RESOURCE_EXHAUSTED in the body as a capacity failure. The package reports this as AllowanceUpstreamError with quota: true.

A paused account’s call is refused with HTTP 429 and error: "account_paused". Its Retry-After header gives the wait until the next UTC month. It carries no allowance headers. Do not repeatedly retry during that wait.

For an unlimited application, allowance_exhausted carries used, quota and resets_at. The amounts are micro-dollars and the time is the next UTC month’s start. Other gateway refusals need not carry those members.

The package reports these failures:

  • An AllowanceRefusal, for a response the gateway wrote itself, with refusal, status, detail, resetsAt, and allowance.
  • An AllowanceUpstreamError, for the provider's non-success response, with status, body, quota, and allowance.
  • A TypeError, before anything is sent, for a malformed request: both prompt and messages, neither, or a malformed turn.

The AI route’s refusals, in refusal:

Refusal Status Meaning
account_paused 429 The customer account is paused at a zero balance until the next UTC month. Retry-After gives the wait.
allowance_exhausted 429 An unlimited application has reached its allowance quantity.
allowance_unavailable 503 The platform has no allowance key available, or no model price in effect.
allowance_application_required 403 The call used an account-wide credential, which cannot call the platform’s AI route.
allowance_busy 429 The application already has the most allowance calls in progress that the platform allows.
allowance_path_refused 403 The request named a model whose name does not start with gemini-, or a path other than the model's generate methods.
allowance_feature_refused 400 The request asked for a feature the allowance does not cover, such as audio or video output, or its body was not JSON.
plan_quantity_unset 409 An unlimited application has no gemini-allowance quantity set.

Any other refusal name is one of the gateway's own, passed through with its status, and the refusals page lists it.

Where your backend closes its connection before a call returns, the platform ends the call at the provider, streamed or not. A call already sent to the provider can end early in any of these ways, and each says what your backend receives:

  • Your backend gives the call up: it receives no answer. On a streamed call, the text that already arrived stays delivered.
  • The call runs past the platform's time limit: a call that does not stream fails with 504 upstream_timeout. A streamed call keeps the text already sent, then ends with a final egress_error event naming upstream_timeout. Either way, generateText throws AllowanceRefusal with that name.
  • The provider's answer passes the platform's size limit: a call that does not stream fails with 502 response_too_large. A streamed call keeps the text sent within the limit, then ends with a final egress_error event naming response_too_large. Either way, generateText throws AllowanceRefusal with that name.

Such a call uses the provider’s token counts to calculate its AI charge if those counts reached the platform, in streamed text or a whole answer over the size limit.

Otherwise it draws an estimate of the request's input tokens: one for every four bytes of the request. A call the provider had already answered with an error status draws nothing, as it would if it had finished. A call stopped before the platform sent it, such as a request over the size limit, draws nothing. These tokens are charged like those of any other call. tzcloud_read_usage records the application’s AI spend this month.

The boundary and the fallback #

An account pause stops the whole application. The router refuses every request on its hostnames with 429 account_paused, including shell files and sign-in routes. Scheduled runs and storage calls are refused too, and a background pass puts the compute to sleep. When the account pauses explains the account-wide stop.

Application code can receive account_paused from the gateway only in work already running when the pause begins.

Handle each failure by the refusal field. Read detail to understand the cause; do not parse it to identify the refusal:

  • On account_paused, end the work without another outbound call or retry. Calls on your own declared upstream and key are refused too. The pause ends at the next UTC month; Retry-After gives the wait.
  • On allowance_unavailable, read its detail. Use the fallback you chose while the platform restores the allowance route: answer without AI, or call your own declared upstream and key. A monthly reset does not fix this refusal.
  • On an AllowanceUpstreamError whose quota is true, the provider is short of capacity for the platform's key. The platform has already sent the call again up to four times, over up to 15 seconds, before it responded to you, so a quick retry rarely helps. Retry it later at a slower cadence, waiting tens of seconds between attempts, or apply the same fallback.
  • Treat every other upstream error as the provider's own. It reaches you with its body unchanged.

An unlimited application can receive allowance_exhausted. The last admitted call can take that allowance over its quantity by its own cost. Wait for its resetsAt, or use your own declared upstream and key. Platform staff can also restore allowance by adjusting its quantity.

Test with the double #

The factory createAiAllowanceDouble(options) from @turnzero/ai_allowance/testing responds in place of the platform route behind unchanged generateText and generateImage calls. Pass double.transport to either. For a transport that wraps global fetch, replace it with double.fetch in the test.

The default is pricing: 'usage': answers carry no allowance headers and have no allowance boundary. The double’s meter still counts calls. Queue answers with double.prime(...) and read the meter with standing() or the call log with calls.

To test a paused account, set paused: true, or use refuseNext('account_paused') for one call. To test an unlimited application’s allowance boundary, set pricing: 'plans' and a quota. In that form, answers carry allowance headers and calls at the boundary are refused.

Without prices or weights, the meter counts tokens. prices supplies the test’s own input and output dollar rates per million tokens, so it counts micro-dollars. These are test settings, not published rates. A test runs the sample below over the double.

For an image call, prime { text: '', image: { mimeType, data } }, with data in base64.

import assert from 'node:assert/strict';
import { AllowanceRefusal, generateText } from '@turnzero/ai_allowance';
import { createAiAllowanceDouble } from '@turnzero/ai_allowance/testing';

// Usage answers have no allowance headers; the test meter still counts tokens.
const allowance = createAiAllowanceDouble();
allowance.prime({ text: 'Three short points.', usage: { input: 10, output: 4 } });

const answer = await generateText(allowance.transport, { prompt: 'Summarize the notes.' });
assert.equal(answer.text, 'Three short points.');
assert.equal(allowance.standing().used, 14);
assert.deepEqual(answer.allowance, { used: null, quota: null, resetsAt: null });
// Script one paused-account response without calling the provider.
allowance.refuseNext('account_paused');
await assert.rejects(generateText(allowance.transport, { prompt: 'Again.' }), (error) => error instanceof AllowanceRefusal && error.refusal === 'account_paused');

The double returns the refusals in Failures. pricing: 'plans' enables allowance_exhausted; paused: true enables account_paused. These failures come from its own setup:

Refusal Cause Remedy
account_paused The double was created with paused: true, or refuseNext scripted the refusal. Use this response to check pause handling. Use an unpaused double for a success test.
allowance_exhausted The double uses pricing: 'plans' and its meter reached quota. Check the unlimited-application fallback, or reset the meter for another success test.
allowance_unavailable, allowance_busy, plan_quantity_unset, allowance_application_required keyHeld: false, credential: 'session', or a scripted refusal caused it. Keep the default key and credential for success tests. Script the other refusals to check their handling.
allowance_path_refused, allowance_feature_refused, gateway_refused The request named a model the double does not accept, asked for another feature, or left the route. Pass model to the factory, and call generateText or generateImage.
environment_required, environment_mismatch The environment header is missing or differs from the factory's environment. Send the factory's environment on the transport.
unknown_upstream The upstream's name held a NUL character (U+0000) or an unpaired UTF-16 surrogate, which the double reads as no name, as the gateway does. Send the name without the character.
no primed answer, TypeError from prime No answer was queued, or a queued answer has the wrong form. Queue an answer with prime after reset().