Getting Started with APIPod

Turn any Python AI model into a cloud API in minutes — install APIPod, write one decorator, serve locally, then deploy.

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.

Step 1 — Install APIPod

pip install apipod

Requires Python ≥ 3.9. APIPod pulls in fastapi, uvicorn, and media-toolkit automatically.

Step 2 — Write service.py

Create a file called service.py. Decorate your function with @app.endpoint and APIPod handles routing, serialisation, and queueing.

from apipod import APIPod

app = APIPod()

@app.endpoint("/generate")
def generate(prompt: str, steps: int = 20) -> dict:
    """Generate an image from a text prompt."""
    # Replace with your actual model logic
    image = my_model.run(prompt=prompt, num_inference_steps=steps)
    return {"image": image}  # media-toolkit handles serialisation

if __name__ == "__main__":
    app.start()

Step 3 — Serve Locally

Start a local dev server with hot-reload. APIPod exposes your endpoints at http://localhost:8000 and prints a Swagger UI link.

apipod --start

Starting APIPod service...
Loaded endpoints:
  POST /generate

Listening on http://0.0.0.0:8000
Swagger UI     at http://localhost:8000/docs

Step 4 — Test Your Endpoint

Call your endpoint using the Python SDK, curl, or the Swagger UI.

import requests

resp = requests.post(
    "http://localhost:8000/generate",
    json={"prompt": "a lone astronaut on a neon planet", "steps": 20}
)
print(resp.json())  # {"job_id": "...", ...}

curl -X POST http://localhost:8000/generate \
  -H "Content-Type: application/json" \
  -d '{"prompt": "a lone astronaut on a neon planet", "steps": 20}'

You should see a job_id in the response. Call .get_result() to block until the result is ready.

Step 5 — Deploy to the Cloud

Build a Docker image and deploy to serverless GPU with two commands. APIPod detects CUDA automatically.

# 1. Build the Docker image — live today (auto-detects CUDA)
apipod --build

# 2. Deploy to serverless GPU on RunPod EU — coming soon
# The unified socaity CLI will mirror apipod for the deploy step:
# socaity deploy --serverless --provider runpod

# Until then, run the deploy from the Studio dashboard at socaity.ai
# after the build completes.

CLI status today. apipod --build is live and handles the build step. The unified socaity deploy CLI shown below is Coming Soon — it will mirror apipod commands for convenience. Track release status on the changelog.

The first deploy pulls a CUDA base image (~8 GB). Subsequent deploys are incremental and much faster.

Project Layout

The minimal APIPod project only needs service.py. Add optional files for custom dependencies or Dockerfile overrides.

File	Required	Purpose
`service.py`	Yes	Your APIPod app — endpoints defined here.
`requirements.txt`	Optional	Extra pip dependencies added to the image.
`Dockerfile`	Optional	Override the generated Dockerfile for custom builds.
`apipod.json`	Optional	Project config: base image, GPU type, env vars. Located at apipod-deploy/apipod.json.

What's Next

Endpoints

Decorator params, media types, and queue behaviour.

Build

CUDA detection, Dockerfile structure, custom builds.

Deploy Serverless

Cold-start tuning, provider config, pricing.

Deploy Dedicated

GPU selection guide and provider comparison.

CLI Reference

Endpoints