Run Your First Service

Install the Python SDK, set your API key, and generate an image with flux_schnell in under ten lines.

Model:flux_schnell from Black Forest Labs, served via Socaity. Four-step diffusion, around one second per image on a warm worker.

• Python 3.10 or newer.
• A Socaity API key. Sign up to generate one.

Install the SDK, then install the service so its client becomes importable. pip install socaity alone does not ship the per-model stubs; socaity install black-forest-labs/flux-schnell generates the flux_schnell client you import in code.

pip install socaity
socaity install black-forest-labs/flux-schnell

The SDK reads SOCAITY_API_KEY from the environment. Export it in your shell before running Python.

# macOS / Linux
export SOCAITY_API_KEY="sk_..."

# Windows (PowerShell)
$env:SOCAITY_API_KEY = "sk_..."

Import flux_schnell from its vendor path, instantiate the client, and call it with a prompt. The call returns a Job object immediately; .get_result() blocks until the GPU finishes and returns a single ImageFile you can save to disk (or a list of them when you request num_outputs > 1).

import os
from socaity.sdk.replicate.black_forest_labs import flux_schnell

# Pass your key explicitly (or rely on a socaity login session).
flux = flux_schnell(api_key=os.getenv("SOCAITY_API_KEY"))

# Submission returns a Job immediately; .get_result() blocks until the GPU finishes.
job = flux(prompt="a lone astronaut on a neon planet, cinematic")
image = job.get_result()

# With num_outputs=1 (the default), get_result() returns a single ImageFile
# with a .save() helper. Request num_outputs>1 to get a list of ImageFile objects.
image.save("astronaut.webp")

flux_schnell defaults to one 1-megapixel image, 1:1 aspect, WebP output, four diffusion steps. Override any of those by passing aspect_ratio, num_outputs, output_format, or num_inference_steps as keyword arguments. See the flux_schnell reference for the full parameter list.

By default .get_result() waits up to one hour, polling every second. Pass timeout_s to cap the wait. On timeout the method returns None rather than raising, so a missed deadline is a value to check, not an exception to catch.

# Cap the wait at 30 seconds. Returns None if the job has not finished by then.
image = job.get_result(timeout_s=30)

if image is None:
    print("Job still running. Check job.status or call get_result() again.")
else:
    image.save("astronaut.webp")

• Installed the socaity Python SDK.
• Authenticated with the SOCAITY_API_KEY environment variable.
• Submitted a flux_schnell job and saved the result to disk.

• Face Restoration. Restore and upscale a face with the hosted gfpgan model.
• Job system. How Socaity queues, polls, and returns results for every model call.
• Python SDK reference. Full surface area: clients, jobs, media helpers.
• flux_schnell parameters. Every keyword argument the model accepts.
• Chain multiple models. Pipe one model's output into the next.