Loading...
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. Each concept below has a dedicated topic with the full detail.
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 access method. You can browse the catalog at /market.
What you have to set up before a call goes through — and therefore who pays for what you consume. A service sets this per channel, so one service can expose more than one:
The full breakdown, including the enrollment-bound variant, is in Access Methods.
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 (secret names, 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. Aliases resolve on the SMTP and S3 gateways too — use a/<alias> as your SMTP username, or the alias name as your S3 bucket.
A scheduled call to a service. The platform invokes it on a cron-like interval and tracks each run's status; the responses themselves land in your request logs. 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 (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; 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:
/a/llm, /a/embed) that point at any enrolled service or service group, and re-target them later without touching your code.svcpass_… keys. Keys can be scoped to a specific role.OPENAI_API_KEY, webhook tokens, etc.) that the gateway injects into upstream requests at call time.Every request 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. |
/e/ | enrollment | Reach a specific enrollment by its short code — /e/<code> — a stable, unique-per-enrollment alias for its endpoint. |
/p/ | platform service | Call a platform-operated pool of interchangeable providers — you pick the tier, the platform picks the provider. |
/b/ | broadcast | Fan one call out to many targets in parallel and return a single envelope with every target's result. |
/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 | Fall back to 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/ | retry | Auto-retry transient failures (429 / 5xx / timeout) on a backoff schedule; your response is unchanged. | ?_max_retries, ?_interval, ?_backoff_multiplier, ?_retry_on |
/s/ | scheduled | 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. /s/ and /d/ register a future call rather than invoking the service immediately; manage them under Developer → Scheduled Requests. /r/ runs the call immediately and retries failures in the background — each attempt lands 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. For which base URL to point each client at, see Platform URLs.
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 − 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 add a fixed top-up amount whenever the available balance crosses the credit-limit threshold. Card management goes through Stripe — we never see the card number.
Beyond per-usage billing, UnitySVC offers platform plans (individual, team, enterprise) as a recurring subscription. The plan fee is debited from the wallet at the start of each period; you can cancel from the billing page, effective at the end of the current period.
At the end of each billing period (typically calendar month) we freeze a statement under Billing & Wallets → Statements with per-service totals, applied promotions, and a downloadable PDF for accounting.
If a charge looks wrong, open a dispute thread under Messages → Disputes referencing the request log entry. The resolution is recorded on the thread; any resulting credit is posted to your wallet as a separate transaction, visible in your transaction history.
Something unclear or missing? Reach us at [email protected]