How to beginner · 3 min read

How to build RunPod serverless handler

Q: How to build RunPod serverless handler

Use the runpod Python package to create a serverless handler by defining a function that processes the job input and returns the output. Set runpod.serverless.start with your handler function to run the serverless endpoint.

Quick answer

Use the runpod Python package to create a serverless handler by defining a function that processes the job input and returns the output. Set runpod.serverless.start with your handler function to run the serverless endpoint.

PREREQUISITES

Python 3.8+
RunPod API key (set as environment variable RUNPOD_API_KEY)
pip install runpod

Setup

Install the runpod package and set your API key as an environment variable before running your serverless handler.

bash

pip install runpod

output

Collecting runpod
  Downloading runpod-1.0.0-py3-none-any.whl (10 kB)
Installing collected packages: runpod
Successfully installed runpod-1.0.0

Step by step

Create a Python script that defines a handler function accepting a job dictionary, processes the input, and returns a result dictionary. Use runpod.serverless.start to start the serverless handler.

python

import os
import runpod

runpod.api_key = os.environ["RUNPOD_API_KEY"]

def handler(job):
    # Extract input prompt from job
    prompt = job.get("input", {}).get("prompt", "")
    # Simple echo response
    response = f"You said: {prompt}"
    return {"output": response}

if __name__ == "__main__":
    runpod.serverless.start({"handler": handler})

output

Waiting for jobs...
Received job: {'input': {'prompt': 'Hello RunPod'}}
Processed job, returning output: {'output': 'You said: Hello RunPod'}

Common variations

Use async handler functions by defining async def handler(job): and running with an async event loop.
Integrate OpenAI or other AI SDKs inside the handler to perform inference.
Customize input/output schema based on your application needs.

python

import os
import runpod
from openai import OpenAI

runpod.api_key = os.environ["RUNPOD_API_KEY"]
openai_client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

def handler(job):
    prompt = job.get("input", {}).get("prompt", "")
    response = openai_client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": prompt}]
    )
    text = response.choices[0].message.content
    return {"output": text}

if __name__ == "__main__":
    runpod.serverless.start({"handler": handler})

output

Waiting for jobs...
Received job: {'input': {'prompt': 'Hello AI'}}
Processed job, returning output: {'output': 'Hello! How can I assist you today?'}

Troubleshooting

If you see runpod.api_key not set error, ensure RUNPOD_API_KEY is exported in your environment.
For handler exceptions, add try-except blocks to log errors and return meaningful messages.
Verify your handler returns a dictionary with an output key to avoid runtime errors.

✅

Key Takeaways

Use the runpod package and set runpod.api_key from environment variable RUNPOD_API_KEY.
Define a handler(job) function that processes input and returns output dictionary for serverless jobs.
Start the serverless handler with runpod.serverless.start({"handler": handler}).
You can integrate any AI SDK inside the handler for inference or processing.
Handle errors gracefully and ensure your handler returns the expected output format.

Verified 2026-04 · gpt-4o-mini

Verify ↗