vlunaai

Official async Python SDK for VlunaAI Billing and Usage Gate APIs.

The SDK bundles:

• A shared async HTTP client (httpx) with retries + idempotency keys
• Authentication helpers (Service Key signing, Bearer token via context)
• Generated Pydantic v2 models

Documentation:

• https://docs.vluna.ai/docs/adapters/sdk

Installation

pip install vlunaai

Requires Python >= 3.8.

Package contents

• Async service client for server-to-server (/mgt/v1) APIs
• Async bearer client for end-user (/api/v1) APIs
• Service Key authentication helpers
• Generated Pydantic v2 models and typed request/response surfaces

Quickstart (Service Key, server-to-server)

Configure Service Key auth (S2S):

• If you use Vluna Cloud (hosted), get these values from the dashboard.
• If you self-host, provision them using your Vluna deployment and service-key setup flow.

Set them in the environment where you run your sdk integration:

export VLUNA_REALM_ID='...'
export VLUNA_SERVICE_KEY_ID='pk-...'
export VLUNA_SERVICE_KEY_SECRET='...'

Use ServiceClient for service-to-service calls to the management surface (/mgt/v1).

import asyncio
import os

from vlunaai import (
  VlunaAIConfig,
  RequestContext,
  ServiceClientOptions,
  ServiceKeyCredentials,
  create_service_client,
)


def env(name: str) -> str:
  value = os.environ.get(name)
  if not value:
    raise RuntimeError(f'Missing environment variable: {name}')
  return value


async def main() -> None:
  service_base_url = os.environ.get('VLUNA_SERVICE_BASE_URL', 'https://us-central1.api.vluna.ai/mgt/v1')
  realm_id = env('VLUNA_REALM_ID')
  principal_id = YOUR_PRINCIPAL_ID  # your customer's organization/team/workspace id
  user_id = YOUR_USER_ID

  client = create_service_client(
    ServiceClientOptions(
      config=VlunaAIConfig(
        base_url=service_base_url,
        realm_id=realm_id,
      ),
      service_key=ServiceKeyCredentials(
        key_id=env('VLUNA_SERVICE_KEY_ID'),
        secret=env('VLUNA_SERVICE_KEY_SECRET'),  # base64-encoded secret
      ),
    )
  )
  try:
    ctx = RequestContext(principal_id=principal_id, user_id=user_id)
    feature_code = 'openai.gpt-4o'

    # 1) authorize: ask Vluna for a lease before performing work
    authz = await client.gate_authorize(body={'feature_code': feature_code, 'feature_family_code': 'llm.standard'}, context=ctx)
    if not authz.data:
      raise RuntimeError('gate_authorize returned no data')
    lease = authz.data.lease

    # ...perform the protected work...

    # 2) commit: report usage once the work completes
    commit = await client.gate_commit(
      body={'lease': lease, 'feature_code': feature_code, 'quantity_minor': '12345'},
      context=ctx,
    )
    print(commit.model_dump())

    # 3) billing helpers
    balance = await client.get_credit_balance(context=ctx)
    print(balance.model_dump())

    # 4) token issuance: your backend can return this access_token to your frontend/mobile app for bearer-auth calls.
    token_envelope = await client.issue_platform_token(
      body={
        'principal_id': principal_id,
        'user_id': user_id,
        'scopes': ['checkout', 'portal'],
        'session_ttl_sec': 900,
      },
      context=ctx,
    )
    if not token_envelope.data:
      raise RuntimeError('issue_platform_token returned no data')
    access_token = token_envelope.data.access_token
    print(access_token)

  finally:
    await client.close()


asyncio.run(main())

Preflight result mode

ServiceClientOptions.error_mode defaults to result. In this mode, gate_preflight() returns either GatePreflightSuccess or GatePreflightError; declared admission denials are typed results rather than integration exceptions.

from vlunaai import GatePreflightError

result = await client.gate_preflight(
  body={'feature_code': 'openai.gpt-4o'},
  context=RequestContext(principal_id=principal_id, user_id=user_id),
)

if isinstance(result, GatePreflightError):
  print(result.status, result.code, result.hints, result.meta, result.trace_id)
else:
  print(result.status, result.data.as_of)

Set error_mode='raise' to receive VlunaAIError for non-2xx responses. A 200 preflight response is always validated strictly and must contain valid data.

Quickstart (Bearer token, end-user calls)

Use BearerClient for user/bearer-auth calls to the public surface (/api/v1).

In a typical setup, your frontend/mobile app fetches an platform access token from your backend (issued via the S2S flow above), then uses it as a bearer token for end-user calls.

import asyncio
import os

from vlunaai import (
  VlunaAIConfig,
  BearerClientOptions,
  RequestContext,
  create_bearer_client,
)


def env(name: str) -> str:
  value = os.environ.get(name)
  if not value:
    raise RuntimeError(f'Missing environment variable: {name}')
  return value


async def main() -> None:
  bearer_base_url = os.environ.get('VLUNA_BEARER_BASE_URL', 'https://us-central1.api.vluna.ai/api/v1')
  realm_id = env('VLUNA_REALM_ID')
  access_token = env('VLUNA_ACCESS_TOKEN')  # obtain from your backend (see ServiceClient.issue_platform_token)

  client = create_bearer_client(
    BearerClientOptions(
      config=VlunaAIConfig(
        base_url=bearer_base_url,
        realm_id=realm_id,
      )
    )
  )
  try:
    ctx = RequestContext(access_token=access_token)
    products = await client.list_catalog_products(context=ctx)
    print(products)
  finally:
    await client.close()


asyncio.run(main())

Key concepts

realm_id

• Required in VlunaAIConfig.
• Identifies the Realm (business project) and is sent as X-Realm-Id on every request.

billing_account_id

• Payor/account-scoped endpoints may use billing_account_id (sent as X-Billing-Account-Id) or principal_id.
• Runtime metering and gate endpoints should not use billing_account_id as the user subject.

principal_id

• Your business identifier for the payor account (for example org_id, team_id, or workspace_id).
• For service-key runtime calls, pass it with user_id via RequestContext(principal_id=..., user_id=...).

user_id

• Your business identifier for the runtime user inside the billing account.
• Required with principal_id for service-key gate, wallet, budget, and event calls.

More details:

• https://docs.vluna.ai/docs/adapters/sdk