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.
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 BYOE — see below). You can browse the catalog at /market.
How a service is fulfilled — which mostly comes down to who supplies the upstream credentials and endpoint:
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.
A commodity capability offered by many sellers at a single, uniform price, reached at /p/<capability> — for example /p/llama3-2-1b/v1/chat/completions. The gateway load-balances your request across every verified provider of that capability by performance (latency, quality, health), so you get the best available member without having to pick one yourself.
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:
/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 and listed with their last-used timestamp.OPENAI_API_KEY, webhook tokens, etc.) that the gateway injects into upstream requests at call time.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. |
/p/ | capability pool | Route across every verified provider of a capability — /p/<capability>. Membership is earned (providers instantiate the capability's template and pass its conformance test) rather than curated, and the pool price is uniform, so requests are routed by performance. |
/e/ | enrollment | Reach a specific enrollment by its short code — /e/<code> — a stable, unique-per-enrollment alias for its endpoint. |
/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/ | 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.
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 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.