Python SDK

Install the SDK, authenticate, and make your first call. Async throughout, with types generated from the schemas.

Introduction

The Runware Python SDK gives you one client for the whole platform: Runware's models for image, video, audio, LLMs and 3D, and your own Serverless apps, both behind the same API key. It is async throughout, with types generated from the schemas.

This page gets you to a working client: installing the package, authenticating, and the settings that shape how it behaves. What you do with that client splits by what you are calling.

Page	What it covers
Calling models	transports, typed parameters, schema validation, concurrency, streaming, and the utilities around them
Calling serverless apps	invoking an endpoint on your own app and reading the task back
Errors	the single exception type and the codes to branch on

Installation

The SDK requires Python 3.11 or higher.

pip

pip install runware-sdk

uv add runware-sdk

Quick start

The fastest path is REST with sync delivery. The server holds the connection open until the task completes and returns the result in the same response:

import asyncio
from runware import Runware

async def main():
    async with Runware(api_key="your-api-key", transport="rest") as client:
        images = await client.run({
            "taskType": "imageInference",
            "model": "runware:101@1",
            "positivePrompt": "A serene mountain landscape at sunset",
            "width": 1024,
            "height": 1024,
            "deliveryMethod": "sync",
        })
        print(images[0]["imageURL"])

asyncio.run(main())

The async with block manages the underlying HTTP session. You can also call await client.connect() and await client.disconnect() explicitly if you need finer control over the lifecycle.

Set RUNWARE_API_KEY in your environment and the SDK picks it up automatically. The api_key= argument is only needed when you want to override it for a specific client instance.

Configuration

Most apps only need to set api_key (or rely on RUNWARE_API_KEY in the env). The full Runware constructor accepts:

from runware import Runware

client = Runware(
    api_key="your-api-key",
    transport="websocket",
    # Timeouts
    timeout=120_000,           # Per-request ms cap
    poll_timeout=600_000,      # Async-delivery polling cap
    # Validation behavior
    validate=True,             # Toggle JSON-Schema validation (off by default)
    # Logging
    debug=True,                # Stdout JSON logs; pass log_sink for a custom sink
)

Per-call overrides live on RunOptions. Use them to tighten the timeout for a fast task or to provide an asyncio.Event for cancellation:

from runware import Runware, RunOptions
import asyncio

cancel = asyncio.Event()

options = RunOptions(
    timeout=30_000,
    cancel_event=cancel,
    validate=False,
)

result = await client.run(payload, options)

Source

The SDK is open source. Issues and pull requests are welcome.

Repository: github.com/runware/runware-python