Deploy to Cloud

Intermediate

10 min

Write an APIPod service, build a container image, deploy it to serverless GPU infrastructure, and verify the live endpoint with both curl and the Python SDK.

Alpha SDK — Code examples on this page are illustrative. The Socaity SDK is in alpha and APIs may change. Always check the Python SDK reference for current syntax.

🎬 Video Tutorial — Coming soon.

Prerequisites

You will need the APIPod CLI and the Socaity CLI installed:

pip install apipod socaity

# socaity login is the default — it authenticates both CLIs.
socaity login

# apipod login is a mirror, kept for convenience.
# apipod login

Step 1 — Write the Service

Create service.py. This example wraps FLUX Schnell as a deployable endpoint. Load the model at module level so it is initialised once per container instance, not on every request.

# service.py
import os
from socaity import flux_schnell
from apipod import APIPod

app = APIPod()

# Load once per container — not on every request
flux = flux_schnell(api_key=os.getenv("SOCAITY_API_KEY"))

@app.endpoint("/generate")
def generate(prompt: str, num_outputs: int = 1, seed: int = None) -> list[str]:
    """Generate images from a text prompt."""
    images = flux(
        prompt=prompt,
        num_outputs=num_outputs,
        seed=seed,
    ).get_result()
    # Return base64-encoded images for transport
    return [img.to_base64() for img in images]

Step 2 — Declare Dependencies

List your Python dependencies. APIPod resolves CUDA-compatible wheels automatically.

socaity>=0.3.0
apipod>=0.2.0
Pillow>=10.0.0

Step 3 — Build the Container Image

apipod --build creates a GPU-optimised Docker image. The build runs in the cloud — you do not need Docker installed locally.

apipod --build service.py

Build output:

→ Resolving dependencies...
→ Selecting CUDA 12.1 base image
→ Installing Python packages (remote build)
→ Running health check
✓ Image built: service:latest (3.2 GB)
✓ Pushed to Socaity registry

Step 4 — Deploy Serverless

Push the image and register it as a serverless endpoint. Specify the cloud provider and GPU class. The platform scales to zero between requests — you pay only for active GPU-seconds.

# Live today — uses the apipod CLI.
apipod --build --image service:latest

# Coming soon — unified socaity CLI will mirror this:
# socaity deploy --image service:latest \
#   --serverless --provider runpod --name flux-service

✓ Endpoint registered
✓ Cold-start target: < 8 s
✓ Scaling: 0 → 10 replicas
✓ Live at: https://api.socaity.ai/endpoints/flux-service/generate

Step 5 — Test with curl

Every deployed endpoint accepts standard HTTP POST requests. Test it directly with curl before wiring it into your application.

curl -X POST https://api.socaity.ai/endpoints/flux-service/generate \
  -H "Authorization: Bearer $SOCAITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A lighthouse in a storm, oil painting",
    "num_outputs": 1
  }'

Step 6 — Call via HTTP

Every deployed APIPod endpoint accepts standard HTTP requests. Use requests or any HTTP client to call your service directly.

import os
import requests

endpoint_url = "https://api.socaity.ai/endpoints/flux-service/generate"
headers = {"Authorization": f"Bearer {os.getenv('SOCAITY_API_KEY')}"}

resp = requests.post(
    endpoint_url,
    json={"prompt": "A lighthouse in a storm, oil painting", "num_outputs": 1},
    headers=headers,
)
job = resp.json()   # {"job_id": "...", ...}
print(job)

Supported Cloud Providers

Provider	Flag	GPU Classes	Notes
RunPod	`--provider runpod`	T4, A10G, A100, H100	Default and only wired-in serverless provider today. EU region.
Multi-provider dedicated	`—`	—	Dedicated hosting across providers is coming soon — tracked separately.

Deployment Flags Reference

Flag	Default	Description
`--serverless`	false	Scale to zero between requests (recommended for sporadic traffic).
`--gpu`	A10G	GPU class to request. Overrides apipod.json if set.
`--min-replicas`	0	Minimum always-warm replicas (0 = full serverless).
`--max-replicas`	10	Maximum concurrent replicas for autoscaling.
`--name`	image tag	Human-readable name for the endpoint in the dashboard.

What You Built

Wrote an APIPod service with the @app.endpoint decorator
Built a cloud-side GPU container image with apipod --build
Deployed serverless to RunPod EU with apipod --build (unified socaity deploy CLI coming soon)
Verified the live endpoint with curl and the Python SDK

Multi-Model Pipeline

Monitor and Optimize