Quick Start
Go from zero to live AI inference in under 5 minutes with the Socaity Python SDK.
Python ≥ 3.10On your PATH
Socaity accountFree at socaity.ai
terminal
pip install socaityRequires Python ≥ 3.10. Also installs media-toolkit for automatic file handling.
pip install socaity does not add every catalog client. Run socaity install <handle> for each service you call. Find the handle on the API catalog at socaity.ai (for example black-forest-labs/flux-schnell).
terminal
socaity install black-forest-labs/flux-schnellOfficial Socaity-hosted models import from the top-level package:
python
# Socaity-hosted (official) models
from socaity import face2faceThird-party models use a deeper path. For flux_schnell the segments are replicate (platform), black_forest_labs (developer), and flux_schnell (service):
python
# Third-party models (routed via Socaity; no REPLICATE_API_KEY)
from socaity.sdk.replicate.black_forest_labs import flux_schnell
flux = flux_schnell() Install the service first with socaity install, then import from the path that matches its host. Replicate-backed models never need a REPLICATE_API_KEY; Socaity routes the call with your SOCAITY_API_KEY.
python
# flux(...) submits the job and returns a handle immediately.
# .get_result() blocks until the job finishes (default timeout: 3600s).
result = flux(
prompt="a lone astronaut on a neon planet, cinematic",
num_outputs=1,
).get_result()
result.save("astronaut.png") That's it. The SDK handled authentication, job submission, polling, and result parsing.
Every service reads
SOCAITY_API_KEY from the environment. Socaity-hosted services (face2face, speechcraft) call our backend directly. Replicate-backed services (flux_schnell, deepseek_v3) route through the same backend, so you never set REPLICATE_API_KEY yourself. The SDK login gives you a temporary key, like the
gh or claude CLIs. For production, set the SOCAITY_API_KEY environment variable yourself.- Sign in at socaity.ai
- Navigate to Account → Secrets
- Click Create key and copy the value
Never commit API keys to version control. Use environment variables or a secrets manager.