Python SDK
Full reference for the socaity Python package — installation, services, file handling, and async jobs.
pip install socaity Requires Python ≥ 3.9. Installs media-toolkit automatically for file handling.
The SDK automatically selects the correct API key based on the service's backend. You do not need to pass a key explicitly in most cases.
import os
from socaity import flux_schnell
from socaity import face2face
# Replicate-backed model — routed via Socaity backend, reads SOCAITY_API_KEY
flux = flux_schnell()
# Socaity-hosted model — reads SOCAITY_API_KEY automatically
f2f = face2face()
# Or pass the key explicitly
flux = flux_schnell(api_key=os.getenv("SOCAITY_API_KEY"))
f2f = face2face(api_key=os.getenv("SOCAITY_API_KEY"))SOCAITY_API_KEY. Socaity-hosted services (face2face, speechcraft) call our cloud directly. Replicate-backed services (flux_schnell, deepseek_v3) are routed through the Socaity backend, which makes the upstream Replicate call for you. You never need to set REPLICATE_API_KEY in your environment. Each service is imported as a typed class. All service methods return a job object — call .get_result() to block until the result is ready.
| Import Path | Service | Category |
|---|---|---|
socaity | flux_schnell | Image |
socaity | face2face | Image |
socaity | speechcraft | Audio |
— | videogen | Video — Coming Soon |
Full parameter reference for flux_schnell.predictions() (also callable directly as flux_schnell()).
| Parameter | Type | Default | Description |
|---|---|---|---|
prompt | str | — | Text description of the image to generate. |
num_outputs | int | 1 | Number of images to generate (1–4). |
aspect_ratio | str | "1:1" | Output aspect ratio, e.g. "16:9", "4:3". |
output_quality | int | 80 | JPEG/WebP quality 0–100. |
output_format | str | "webp" | Output image format: "webp", "jpg", or "png". |
megapixels | str | "1" | Approximate output resolution in megapixels. |
num_inference_steps | int | 4 | Number of diffusion steps. Higher = more detail but slower. |
go_fast | bool | True | Enables a faster inference mode. When True, seed-based reproducibility is disabled. |
disable_safety_checker | bool | False | Bypass the safety filter. Use responsibly. |
seed | int | None | None | Random seed for reproducibility. Has no effect when go_fast=True. |
import os
from socaity import flux_schnell
flux = flux_schnell(api_key=os.getenv("SOCAITY_API_KEY"))
images = flux(
prompt="a lone astronaut on a neon planet, cinematic",
num_outputs=1,
).get_result()
for img in images:
img.save("output.png")
print("Done!") Submit multiple jobs concurrently without blocking. Call .get_result() only when you need the output.
import os
from socaity import flux_schnell
flux = flux_schnell(api_key=os.getenv("SOCAITY_API_KEY"))
prompts = ["a forest", "a city", "an ocean"]
jobs = [flux(prompt=p, num_outputs=1) for p in prompts] # all submitted immediately
images = [job.get_result() for job in jobs] # collect results
for i, imgs in enumerate(images):
imgs[0].save(f"output_{i}.png")The SDK accepts local paths, URLs, bytes, PIL Images, and numpy arrays. Files are auto-uploaded if needed.
import os
from socaity import face2face
f2f = face2face(api_key=os.getenv("SOCAITY_API_KEY"))
# Local path — auto-uploaded
result = f2f.swap_img_to_img(
source_img="./my_face.jpg",
target_img="./target.jpg",
).get_result()
result.save("swapped.jpg")
# Also accepts: URL, bytes, PIL.Image, numpy array| Method / Property | Returns | Description |
|---|---|---|
.get_result() | any | Block until the job finishes and return the result. Accepts optional timeout_s parameter. |
.job_id | str | Unique identifier for this job. |
.response.status | APIJobStatus | PENDING | QUEUED | PROCESSING | STREAMING | FINISHED | FAILED | CANCELLED | TIMEOUT | UNKNOWN |
.progress | float | None | Completion 0.0–1.0, if reported by the model. |
.cancel() | BaseJobResponse | None | Request cancellation. Accepts wait (bool), timeout_s, and poll_interval_s parameters. |
Every service today exposes method-level aliases for its primary endpoint — short names that point at the same underlying call. They are defined directly on the Python class, so they exist before any network call is made.
from socaity import speechcraft
tts = speechcraft()
# Canonical endpoint
tts.text2voice(text="hello").get_result()
# Method aliases — same call, shorter names
tts.run(text="hello").get_result()
tts("hello").get_result() # __call__ alias Common patterns: run as a generic entry point, __call__ so you can invoke the service instance directly (speechcraft("hello")), and category aliases like text2img or text2voice on top of the canonical endpoint name.
socaity.