Aliases and service resolution

Every Socaity service has a permanent UUID and one or more readable aliases. When you import a service in Python or call socaity install, the SDK uses the alias. The backend resolves it to the underlying service descriptor at runtime, so aliases stay stable even when a service is moved, versioned, or rehosted on a different provider.

See also:Python SDK, SocaitySDK CLI, Server updates.

This page describes the resolution flow from the SDK perspective. The authoritative mapping (alias → service descriptor → deployment) lives in the Socaity backend and is the source of truth for both the SDK and the dashboard.

What an alias is

An alias is the name you use to reference a service in your code. It is short, carries the vendor prefix, and uses snake case so it is a valid Python identifier.

Layer	Example	Used by
Service descriptor UUID	`b0085e5e-2a1a-411c-b0bc-24f1d430f09f`	Backend, dashboard URLs, hosting records.
Alias (canonical)	`flux_schnell`	Python imports, CLI commands, stub filenames.
Vendor path	`black-forest-labs/flux-schnell`	Marketplace listing, install command for Replicate-backed services.

Official services use the bare alias (face2face, speechcraft). Replicate-backed services keep the vendor prefix in the install command and the import path (socaity.sdk.replicate.black_forest_labs.flux_schnell) so two vendors can ship services with the same alias without collision.

How resolution works at runtime

When your code instantiates a service client, the SDK does not call the GPU pod directly. It calls the Socaity backend with the alias, asks for the current hosting record, and uses the returned endpoint URL to submit the job.

Import. from socaity.sdk.replicate.black_forest_labs import flux_schnell loads the local stub (a thin client class that knows its alias and method signatures).
Instantiate. flux = flux_schnell(api_key=...) creates a client bound to your API key. No network call yet.
First call. flux(prompt=...) asks the backend to resolve the alias to a hosting record (service descriptor UUID, endpoint URL, current version). The result is cached for the session.
Submit. The SDK posts the job to the resolved endpoint and returns a Job handle. The endpoint is whatever the backend points at right now, not a value the SDK hard-codes.
Poll. .get_result() walks the job lifecycle against the same resolved endpoint until the job is terminal.

Because resolution happens at runtime, the SDK keeps working when a service is redeployed to a new provider, a new region, or a new GPU class. The alias does not change.

Where the local stub comes from

The Python import (from socaity.sdk.replicate.<vendor> import <alias>) needs a stub file on disk. The stub gets there in one of two ways:

Official services ship with the wheel. pip install socaity already exposes from socaity import face2face.
Replicate-backed and community services are pulled on demand: socaity install <vendor>/<alias> downloads the stub into your environment. socaity update refreshes everything currently installed.

Stubs are generated from the backend's view of the alias (method signatures, defaults, file fields). If the upstream definition changes between releases, socaity update pulls the new shape and your import keeps working, with no change to the import path.

When resolution can fail

Unknown alias. The backend returns 404 for the alias. Usually a typo, or a service removed from the catalog. Check the spelling against socaity.ai/APIs/overview.
Stale local stub. The stub on disk references methods or fields that no longer exist. Run socaity update to refresh.
No active deployment. The alias is known but has no running endpoint right now. The backend returns the descriptor with an empty hosting record; the SDK raises before submitting the job. Common for services in Coming Soon state.

Job system

Server updates