Loading...
A short tour of how UnitySVC works from the customer side: the concepts you'll see in the UI, what each page is for, how to talk to the platform from code, and how billing works.
UnitySVC is a marketplace that puts a single API key, gateway, and bill in front of digital services from many sellers. The same vocabulary shows up across the GUI, the SDK, and the API — it's worth getting familiar with these terms first.
A specific offering listed by a seller — for example, an OpenAI-compatible chat endpoint, an S3 bucket, or an SMTP relay. Each service has its own pricing, routing target, and listing type (managed, BYOK, or self-hosted). You can browse the catalog at /market.
A curated bundle of services that you enroll in as a single unit. Useful when you want all of a seller's chat models, or a themed collection (e.g. "embedding models"). When the seller adds a new service to the group, your enrollment picks it up automatically.
The act of opting in to a service (or a group). Until you enroll, calls to a service are rejected. Enrollment captures the price you accepted, any per-customer routing variables (BYOK keys, region hints), and the effective access scope.
A stable, personal endpoint of the form /a/<your-alias>/... that resolves to a real service path before routing. Aliases let you switch the underlying provider or model without touching your code — point llm at OpenAI today, Anthropic tomorrow, and your application keeps calling /a/llm/chat/completions.
A scheduled call to an enrolled service. The platform invokes the service on a cron-like interval and stores the response. Useful for uptime checks, periodic ETL, or scheduled report generation. The same service is still callable manually — recurrence is just an extra trigger.
API keys (svcpass_…) authenticate every call to the gateway and the customer API. Secrets are encrypted values (BYOK provider keys, webhook tokens) that the gateway injects into requests on your behalf — the value is write-only, only metadata ever comes back.
A prepaid USD balance attached to your account. Usage charges are deducted from the wallet by a streaming consumer; when the available balance dips below your credit limit, the platform attempts an auto top-up. You'll find the full picture under Billing → Wallets.
The customer sidebar groups everything you'll touch day-to-day:
Services → Enrollments. Browse the marketplace, enroll in a service or group, and configure per-enrollment routing variables (e.g. a BYOK API key to forward upstream).
Services → Aliases. Create stable shortcuts (/a/llm, /a/embed) that point at any enrolled service or service group, and re-target them later without touching your code.
Billing → Wallets & Statements. Top up your prepaid balance, set a credit limit, and download monthly statements with per-service usage totals.
Developer → API Keys. Issue and revoke svcpass_… keys. Keys can be scoped to a specific role and listed with their last-used timestamp.
Developer → Secrets. Store provider credentials (OPENAI_API_KEY, webhook tokens, etc.) that the gateway injects into upstream requests at call time.
Developer → Scheduled Requests. Configure recurrent requests against any enrolled service — cron expression, headers, body, expected response.
Developer → Request Logs. Inspect the last N gateway calls: status, latency, upstream chosen, and the resolved alias / routing key.
Support → Messages. Inquiries about a service, support tickets, and disputes all flow through the same threaded inbox.
Settings → Account. Manage team membership, switch between customer accounts, and link your OIDC identity (Google / GitHub) via Keycloak.
Every primitive is a single-letter URL prefix. There are two classes: routes choose or shape where a call goes, and wrappers modify how it runs. Prefixes stack and compose, so a single URL can express a whole behavior — no code, no SDK, and it works with any client. The primitive itself is free; you pay only for the underlying service call.
# Cache for 10 minutes (/m/) and force-log (/l/) a call # routed through your "llm" alias (/a/) — just prefix the path. POST /m/l/a/llm/chat/completions?_ttl=10m
| Prefix | Primitive | What it does |
|---|---|---|
/a/ | alias | Re-point a stable path to any service or group — your own, or seller-published — without touching code. |
/g/ | service group | Dispatch across a weighted pool of equivalent services; the group's /models endpoint lists what's available. |
/b/ | broadcast | Fan one call out to many targets in parallel — a sync envelope of results, or async tasks. |
/c/ | chain | Run a sequence of calls where success and failure each branch to a different next step. |
| Prefix | Primitive | What it does | Key query params |
|---|---|---|---|
/l/ | log | Force per-call request logging, inline — no headers required. | ?_complete |
/m/ | memoize | Cache the response for a TTL; identical calls return instantly and aren't billed. | ?_ttl, ?_renew |
/f/ | failover | Retry on a backup target on 5xx / 429 / timeout. | ?_else |
/t/ | tee | Mirror the call to a second target, fire-and-forget; your response is unchanged. | ?_to |
/r/ | recurrent | Register a repeating call on a cadence; returns a recurrent-request id. | ?_every, ?_fire_now, ?_name |
/d/ | delayed | Schedule a one-shot future call; returns a task id and is logged when it fires. | ?_at, ?_in |
Order is cosmetic — the gateway applies each behavior at a fixed stage. /r/ and /d/ register a future call rather than invoking the service immediately; manage them under Developer → Scheduled Requests and watch each firing land in Developer → Request Logs.
Most customers integrate by pointing an existing client (OpenAI SDK, boto3, an SMTP library) at the gateway URL with a UnitySVC API key — no UnitySVC SDK required. The unitysvc-py package is for the control plane: managing aliases, secrets, and scheduled requests programmatically.
pip install unitysvc-py
With UNITYSVC_API_KEY set in the environment:
from unitysvc import Client
client = Client.from_env()
# Manage encrypted secrets that the gateway injects upstream.
client.secrets.create({"name": "OPENAI_API_KEY", "value": "sk-..."})
# List your URL aliases.
for alias in client.aliases.list().data:
print(alias.name, "→", alias.target)
# Trigger a scheduled request on demand.
client.recurrent_requests.trigger(request_id)An AsyncClient with the same surface is available for asyncio code (FastAPI, scripts using asyncio.run). All errors subclass UnitysvcSDKError with HTTP-status-specific types like AuthenticationError and RateLimitError.
The same package ships usvc, a Typer-based CLI for the same surface, ideal for shell scripts and quick checks:
usvc env # show which env vars the SDK will pick up usvc secrets list usvc secrets set OPENAI_API_KEY --value sk-... usvc aliases list usvc aliases show <alias_id> usvc recurrent-requests list usvc recurrent-requests trigger <request_id>
Full reference (every method, every option, type-checked docstrings) lives on GitHub: unitysvc/unitysvc-py — if a feature isn't covered above, that's where to look.
UnitySVC bills against a prepaid wallet in USD. The model has three numbers:
Wallet balance — the settled balance from top-ups, refunds, and previously closed statements.
Usage charges — calls made since the current billing period started, calculated from per-service pricing bundles.
Credit limit — how far the available balance (wallet − usage) is allowed to go negative before an auto top-up triggers.
Top up manually from Billing → Wallets (one-time charge on a saved card), or enable auto top-up to refill to a target amount whenever the available balance crosses the credit-limit threshold. Card management goes through Stripe — we never see the card number.
Some services are sold as subscriptions (flat monthly, included quota, overage rate). The recurring fee is debited from the wallet at the start of each period; usage above the quota is metered against the same wallet. You can cancel from the enrollment detail page; cancellation takes effect at the end of the current period.
At the end of each billing period (typically calendar month) we freeze a statement under Billing → Statements with per-service totals, applied promotions, and a downloadable PDF for accounting.
If a charge looks wrong, open a thread under Messages → Disputes referencing the request log entry. Resolved disputes post a credit transaction to the wallet, visible in your transaction history.