Python Runware SDK

Note

A new official SDK is available at runware-python. It covers the full inference and utility surface with REST or WebSocket transports and gets all new features going forward. This library remains supported during the transition.

The Python Runware SDK is used to run image inference with the Runware API, powered by the Runware inference platform. It can be used to generate images with text-to-image and image-to-image. It also allows the use of an existing gallery of models or selecting any model or LoRA from the CivitAI gallery. The API also supports upscaling, background removal, inpainting and outpainting, and a series of other ControlNet models.

Get API Access

To use the Python Runware SDK, you need to obtain an API key. Follow these steps to get API access:

1. Create a free account with Runware.
2. Once you have created an account, you will receive an API key and trial credits.

Important: Please keep your API key private and do not share it with anyone. Treat it as a sensitive credential.

Documentation

For detailed documentation and API reference, please visit the Runware Documentation or refer to the docs folder in the repository. The documentation provides comprehensive information about the available classes, methods, and parameters, along with code examples to help you get started with the Runware SDK Python.

Installation

To install the Python Runware SDK, use the following command:

pip install runware

Usage

Before using the Python Runware SDK, make sure to set your Runware API key in the environment variable RUNWARE_API_KEY. You can do this by creating a .env file in your project root and adding the following line:

RUNWARE_API_KEY = "your_api_key_here"

Generating Images

To generate images using the Runware API, you can use the imageInference method of the Runware class. Here's an example:

fromrunwareimportRunware, IImageInferenceasyncdefmain() ->None:
runware=Runware(api_key=RUNWARE_API_KEY)
awaitrunware.connect()
request_image=IImageInference(
positivePrompt="a beautiful sunset over the mountains",
model="civitai:36520@76907", numberResults=4, negativePrompt="cloudy, rainy",
height=512, width=512, )
images=awaitrunware.imageInference(requestImage=request_image)
forimageinimages:
print(f"Image URL: {image.imageURL}")

Enabling teaCache/deepCache/fbCache for faster inference

Some models support teaCache, deepCache, and fbCache for faster inference, with the trade-off of quality loss with more aggressive settings.

fromrunwareimportRunware, IImageInference, IAcceleratorOptionsasyncdefmain() ->None:
runware=Runware(api_key=RUNWARE_API_KEY)
awaitrunware.connect()
request_image=IImageInference(
positivePrompt="a beautiful sunset over the mountains",
model="civitai:943001@1055701", # using Shuttle v3 for this test, to showcase the power on 3rd party Flux finetunes.numberResults=1,
negativePrompt="cloudy, rainy",
height=1024,
width=1024,
acceleratorOptions=IAcceleratorOptions(
teaCache=True,
teaCacheDistance=0.6, # 0.6 is at the more moderate-to-extreme end, and 0.1 is at the more conservative end.
),
)
images=awaitrunware.imageInference(requestImage=request_image)
forimageinimages:
print(f"Image URL: {image.imageURL}")

Using fbCache for enhanced performance

fbCache (First Block Cache) provides additional acceleration options for compatible models:

fromrunwareimportRunware, IImageInference, IAcceleratorOptionsasyncdefmain() ->None:
runware=Runware(api_key=RUNWARE_API_KEY)
awaitrunware.connect()
request_image=IImageInference(
positivePrompt="a futuristic cityscape with flying cars",
model="runware:108@22", # Qwen model with fbCache supportnumberResults=1,
height=1024,
width=1024,
acceleratorOptions=IAcceleratorOptions(
fbcache=True, # Enable First Block cachecacheStartStep=0, # Start caching from step 0cacheStopStep=8# Stop caching at step 8
),
)
images=awaitrunware.imageInference(requestImage=request_image)
forimageinimages:
print(f"Image URL: {image.imageURL}")

teaCache

• teaCache is a boolean that enables or disables the teaCache feature. If set to True, it will use teaCache for faster inference.
  • It is specific to transformer models, Flux and SD3. teaCache does not work for UNet models like SDXL or SD1x.
• teaCacheDistance is a float between 0.0 and 1.0, where 0.0 is the most conservative and 1.0 is the most aggressive.
• cacheStartStep and cacheStopStep are integers that represent the start and end steps of the teaCache and DeepCache process.
  • cacheStartStep is the step at which the generator starts to skip blocks and reduce quality; cacheStopStep is the step at which the teaCache process ends, returning to full fidelity steps.
  • If not specified, teaCache (or DeepCache) will be enabled throughout the entire image generation process, which may be undesirable for preserving quality.

deepCache

• deepCache is a boolean that enables or disables the deepCache feature. If set to True, it will use deepCache for faster inference.
• deepCacheInterval represents the frequency of feature caching, specified as the number of steps between each cache operation.
  • A larger cache interval makes inference faster, and costs more quality.
  • The default value is 3
• deepCacheBranchId represents which branch of the network (ordered from the shallowest to the deepest layer) is responsible for executing the caching processes.
  • Opting for a lower branch ID will result in a more aggressive caching process, while a higher branch ID will yield a more conservative approach.
  • The default value is 0

fbCache

• fbcache is a boolean that enables or disables the First Block cache feature. If set to True, it will use fbCache for faster inference.
  • fbCache is compatible with specific models and provides additional acceleration options.
  • Works in conjunction with cacheStartStep and cacheStopStep to control the caching behavior.
• cacheStartStep and cacheStopStep control the range of steps where caching is applied.
  • cacheStartStep: The step at which caching begins (default: 0)
  • cacheStopStep: The step at which caching ends (default: total steps)
  • These parameters allow fine-grained control over when caching is active during the generation process.

Asynchronous Processing with Webhooks

The Runware SDK supports asynchronous processing via webhooks for long-running operations. When you provide a webhookURL, the API immediately returns a task response and sends the final result to your webhook endpoint when processing completes.

How it works

1. Include webhookURL parameter in your request
2. Receive immediate response with taskType and taskUUID
3. Final result is POSTed to your webhook URL when ready

Supported operations:

• Image Inference
• Photo Maker
• Image Caption
• Image Background Removal
• Image Upscale
• Prompt Enhance
• Video Inference

Example

fromrunwareimportRunware, IImageInferenceasyncdefmain() ->None:
runware=Runware(api_key=RUNWARE_API_KEY)
awaitrunware.connect()
request_image=IImageInference(
positivePrompt="a beautiful mountain landscape",
model="civitai:36520@76907",
height=512,
width=512,
webhookURL="https://your-server.com/webhook/runware"
)
# Returns immediately with task inforesponse=awaitrunware.imageInference(requestImage=request_image)
print(f"Task Type: {response.taskType}")
print(f"Task UUID: {response.taskUUID}")
# Result will be sent to your webhook URL

Webhook Payload Format

Your webhook endpoint will receive a POST request with the same format as synchronous responses:

 "data": [
{
"taskType": "imageInference",
"taskUUID": "a770f077-f413-47de-9dac-be0b26a35da6",
"imageUUID": "77da2d99-a6d3-44d9-b8c0-ae9fb06b6200",
"imageURL": "https://im.runware.ai/image/...",
"cost": 0.0013
}
]
}

Video Inference with Async Delivery Method

For long-running video generation tasks, you can use deliveryMethod="async" to submit the task and retrieve results later. This is useful for handling system interruptions, batch processing, or building queue-based systems.

fromrunwareimportRunware, IVideoInferenceasyncdefmain() ->None:
runware=Runware(api_key=RUNWARE_API_KEY)
awaitrunware.connect()
# Submit video task with async delivery methodrequest=IVideoInference(
model="openai:3@2",
positivePrompt="A beautiful sunset over the ocean",
duration=4,
width=1280,
height=720,
deliveryMethod="async",
)
response=awaitrunware.videoInference(requestVideo=request)
task_uuid=response.taskUUIDprint(f"Task submitted: {task_uuid}")
# Later, retrieve resultsvideos=awaitrunware.getResponse(
taskUUID=task_uuid,
numberResults=1
)
forvideoinvideos:
print(f"Video URL: {video.videoURL}")

Parameters:

• deliveryMethod: Set to "async" to return immediately with IAsyncTaskResponse containing taskUUID instead of waiting for completion
• Use getResponse(taskUUID) to retrieve results at any time
• deliveryMethod="sync" waits for complete results (may timeout for long-running tasks)

Training (Async Only)

Training is a long-running task type.

• deliveryMethod="sync" is not supported for training and raises a ValueError
• Use deliveryMethod="async" and retrieve final results with getResponse(taskUUID)

importuuidfromrunwareimportRunware, ITraining, ITrainingImportModel, ITrainingInputsasyncdefmain() ->None:
runware=Runware(api_key=RUNWARE_API_KEY)
awaitrunware.connect()
request_training=ITraining(
taskUUID=str(uuid.uuid4()),
model="runware:illustrative@training",
deliveryMethod="async",
importModel=ITrainingImportModel(
air="runware:illustrative@0",
name="Runware Illustrative Training Model",
uniqueIdentifier="runware_illustrative_model_1",
version="1.0",
private=False,
heroImageURL="https://example.com/hero-image.png",
shortDescription="First training model",
),
inputs=ITrainingInputs(
dataset="example/pictures.zip"
),
)
training_task=awaitrunware.training(requestTraining=request_training)
results=awaitrunware.getResponse(taskUUID=training_task.taskUUID)
print(results)

After training, you can run image inference with the trained model:

importuuidfromrunwareimportRunware, IImageInference, IInputs, IInputReferenceasyncdefmain() ->None:
runware=Runware(api_key=RUNWARE_API_KEY)
awaitrunware.connect()
request_image=IImageInference(
taskUUID=str(uuid.uuid4()),
model="runware:illustrative@0",
positivePrompt="a horse",
numberResults=1,
width=1024,
height=1025,
deliveryMethod="sync",
)
image_task=awaitrunware.imageInference(requestImage=request_image)
print(f"Image inference task submitted: {image_task.taskUUID}")

Retrieving Original Task Request/Response

To inspect the original request payload and response for a past task, use getTaskDetails(taskUUID). Known request task types are parsed into SDK request objects when possible; unknown task types remain raw dictionaries. details.response is normalized to a list:

• success: parsed items from response.data[] (typed when known)
• failure: items from response.errors[]

fromrunwareimportRunwareasyncdefmain() ->None:
runware=Runware(api_key=RUNWARE_API_KEY)
awaitrunware.connect()
details=awaitrunware.getTaskDetails(
taskUUID="a770f077-f413-47de-9dac-be0b26a35da6"
)
print("Original request:", details.request)
print("Original response:", details.response)

Enhancing Prompts

To enhance prompts using the Runware API, you can use the promptEnhance method of the Runware class. Here's an example:

fromrunwareimportRunware, IPromptEnhanceasyncdefmain() ->None:
runware=Runware(api_key=RUNWARE_API_KEY)
awaitrunware.connect()
prompt="A beautiful sunset over the mountains"prompt_enhancer=IPromptEnhance(
prompt=prompt,
promptVersions=3,
promptMaxLength=64,
)
enhanced_prompts=awaitrunware.promptEnhance(promptEnhancer=prompt_enhancer)
forenhanced_promptinenhanced_prompts:
print(enhanced_prompt.text)

Removing Image Background

To remove the background from an image using the Runware API, you can use the imageBackgroundRemoval method of the Runware class. Here's an example:

fromrunwareimportRunware, IImageBackgroundRemovalasyncdefmain() ->None:
runware=Runware(api_key=RUNWARE_API_KEY)
awaitrunware.connect()
image_path="image.jpg"remove_image_background_payload=IImageBackgroundRemoval(inputImage=image_path)
processed_images=awaitrunware.imageBackgroundRemoval(
removeImageBackgroundPayload=remove_image_background_payload
)
forimageinprocessed_images:
print(image.imageURL)

Image-to-Text Conversion

To convert an image to text using the Runware API, you can use the imageCaption method of the Runware class. Here's an example:

fromrunwareimportRunware, IImageCaptionasyncdefmain() ->None:
runware=Runware(api_key=RUNWARE_API_KEY)
awaitrunware.connect()
image_path="image.jpg"request_image_to_text_payload=IImageCaption(inputImage=image_path)
image_to_text=awaitrunware.imageCaption(
requestImageToText=request_image_to_text_payload
)
print(image_to_text.text)

Video Caption

To generate captions for videos using the Runware API, you can use the videoCaption method of the Runware class. The SDK automatically polls for results when using async delivery. Here's an example:

fromrunwareimportRunware, IVideoCaption, IVideoCaptionInputsasyncdefmain() ->None:
runware=Runware(api_key=RUNWARE_API_KEY)
awaitrunware.connect()
request_caption=IVideoCaption(
model="memories:1@1",
inputs=IVideoCaptionInputs(
video="https://example.com/video.mp4"
),
deliveryMethod="async",
includeCost=True
)
caption_response=awaitrunware.videoCaption(
requestVideoCaption=request_caption
)
print(f"Caption: {caption_response.text}")
ifcaption_response.cost:
print(f"Cost: {caption_response.cost}")

Video Caption Parameters:

• model: Caption model identifier (e.g., "memories:1@1")
• inputs: IVideoCaptionInputs containing the video URL or UUID
• deliveryMethod: "async" (with automatic polling) or use webhookURL for webhook delivery
• includeCost: Include cost information in the response (optional)
• webhookURL: Webhook URL for async delivery without polling (optional)

Video Background Removal

To remove the background from videos you can use the videoBackgroundRemoval method of the Runware class. The SDK automatically polls for results when using async delivery. Here's an example:

fromrunwareimportRunware, IVideoBackgroundRemoval, IVideoBackgroundRemovalInputs, IVideoBackgroundRemovalSettingsasyncdefmain() ->None:
runware=Runware(api_key=RUNWARE_API_KEY)
awaitrunware.connect()
request_bg_removal=IVideoBackgroundRemoval(
model="bria:51@1",
inputs=IVideoBackgroundRemovalInputs(
video="https://example.com/video.mp4"
),
outputFormat="WEBM",
includeCost=True,
settings=IVideoBackgroundRemovalSettings(
rgba=[255, 255, 255, 0] )
)
processed_videos=awaitrunware.videoBackgroundRemoval(
requestVideoBackgroundRemoval=request_bg_removal
)
forvideoinprocessed_videos:
print(f"Video URL: {video.videoURL}")
ifvideo.cost:
print(f"Cost: {video.cost}")

Video Background Removal Parameters:

• model: Background removal model identifier (e.g., "bria:51@1")
• inputs: IVideoBackgroundRemovalInputs containing the video URL or UUID
• outputFormat: Output video format ("WEBM", "MP4", etc.)
• includeCost: Include cost information in the response (optional)
• settings: IVideoBackgroundRemovalSettings for custom background configuration
• webhookURL: Webhook URL for async delivery without polling (optional)

Background Removal Settings:

• rgba: Background color as [R, G, B, A] array (0-255 for RGB, 0.0-1.0 for alpha)

Upscaling Images

To upscale an image using the Runware API, you can use the imageUpscale method of the Runware class. Here's an example:

fromrunwareimportRunware, IImageUpscaleasyncdefmain() ->None:
runware=Runware(api_key=RUNWARE_API_KEY)
awaitrunware.connect()
image_path="image.jpg"upscale_factor=4upscale_gan_payload=IImageUpscale(
inputImage=image_path, upscaleFactor=upscale_factor
)
upscaled_images=awaitrunware.imageUpscale(upscaleGanPayload=upscale_gan_payload)
forimageinupscaled_images:
print(image.imageURL)

Photo Maker

Use the photoMaker method of the Runware class. Here's an example:

fromrunwareimportRunware, IPhotoMakerimportuuidasyncdefmain() ->None:
runware=Runware(api_key=RUNWARE_API_KEY)
awaitrunware.connect()
request_image=IPhotoMaker(
model="civitai:139562@344487",
positivePrompt="img of a beautiful lady in a forest",
steps=35,
numberResults=1,
height=512,
width=512,
style="No style",
strength=40,
outputFormat="WEBP",
includeCost=True,
taskUUID=str(uuid.uuid4()),
inputImages=[
"https://im.runware.ai/image/ws/0.5/ii/74723926-22f6-417c-befb-f2058fc88c13.webp",
"https://im.runware.ai/image/ws/0.5/ii/64acee31-100d-4aa1-a47e-6f8b432e7188.webp",
"https://im.runware.ai/image/ws/0.5/ii/1b39b0e0-6bf7-4c9a-8134-c0251b5ede01.webp",
"https://im.runware.ai/image/ws/0.5/ii/f4b4cec3-66d9-4c02-97c5-506b8813182a.webp"
],
)
photos=awaitrunware.photoMaker(requestPhotoMaker=request_image)
forphotoinphotos:
print(f"Image URL: {photo.imageURL}")

ACE++

ACE++ (Advanced Character Edit) is an advanced framework for character-consistent image generation and editing. It allows you to create new images from a single reference image while preserving identity, and edit existing images without retraining the model.

Note: When using ACE++, you must set the model parameter to runware:102@1.

Character-Consistent Generation

To generate new images while preserving character identity from a reference image:

fromrunwareimportRunware, IImageInference, IAcePlusPlusasyncdefmain() ->None:
runware=Runware(api_key=RUNWARE_API_KEY)
awaitrunware.connect()
# Upload your reference image firstreference_image=awaitrunware.uploadImage("path/to/reference_image.jpg")
request_image=IImageInference(
positivePrompt="photo of man wearing a business suit in a modern office",
model="runware:102@1", # Required model for ACE++height=1024,
width=1024,
numberResults=1,
acePlusPlus=IAcePlusPlus(
inputImages=[reference_image.imageUUID], # Reference image for character identityrepaintingScale=0.3# Lower values (0.0-0.5) preserve more identity
)
)
images=awaitrunware.imageInference(requestImage=request_image)
forimageinimages:
print(f"Image URL: {image.imageURL}")

Character-Consistent Editing

To edit existing images while preserving character identity using masks:

fromrunwareimportRunware, IImageInference, IAcePlusPlusasyncdefmain() ->None:
runware=Runware(api_key=RUNWARE_API_KEY)
awaitrunware.connect()
# Upload your reference image and maskreference_image=awaitrunware.uploadImage("path/to/reference_image.jpg")
mask_image=awaitrunware.uploadImage("path/to/mask_image.png")
request_image=IImageInference(
positivePrompt="photo of woman wearing a red dress",
model="runware:102@1", # Required model for ACE++height=1024,
width=1024,
numberResults=1,
acePlusPlus=IAcePlusPlus(
inputImages=[reference_image.imageUUID], # Reference imageinputMasks=[mask_image.imageUUID], # Mask for selective editingrepaintingScale=0.7# Higher values (0.5-1.0) follow prompt more in edited areas
)
)
images=awaitrunware.imageInference(requestImage=request_image)
forimageinimages:
print(f"Image URL: {image.imageURL}")

ACE++ Parameters:

• inputImages: Array containing exactly one reference image (required)
• inputMasks: Array containing at most one mask image (optional, for editing)
• repaintingScale: Float between 0.0 and 1.0
  • 0.0: Maximum character identity preservation
  • 1.0: Maximum adherence to prompt instructions
  • For generation: Use 0.0-0.5 for strong resemblance
  • For editing: Use 0.5-1.0 for more creative freedom in edited areas

Mask Requirements:

• The mask should be a black and white image
• White (255) represents areas to be edited
• Black (0) represents areas to be preserved
• Supported formats: PNG, JPG, WEBP

Generating Images with refiner

To generate images using the Runware API with refiner support, you can use the imageInference method of the Runware class. Here's an example:

fromrunwareimportRunware, IImageInference, IRefinerasyncdefmain() ->None:
runware=Runware(api_key=RUNWARE_API_KEY)
awaitrunware.connect()
refiner=IRefiner(
model="civitai:101055@128080",
startStep=2,
startStepPercentage=None,
)
request_image=IImageInference(
positivePrompt="a beautiful sunset over the mountains",
model="civitai:101055@128078",
numberResults=4,
negativePrompt="cloudy, rainy",
height=512,
width=512,
refiner=refiner
)
images=awaitrunware.imageInference(requestImage=request_image)
forimageinimages:
print(f"Image URL: {image.imageURL}")

Using ControlNet with Image Inference

To use ControlNet for image inference in the Runware SDK, you can use a class IControlNetGeneral. Here's an example of how to set up and use this feature:

fromrunwareimportRunware, IImageInference, IControlNetGeneral, EControlModeasyncdefmain() ->None:
runware=Runware(api_key=RUNWARE_API_KEY)
awaitrunware.connect()
controlNet=IControlNetGeneral(
startStep=1,
endStep=30,
weight=0.5,
controlMode=EControlMode.BALANCED.value,
guideImage="https://huggingface.co/datasets/mishig/sample_images/resolve/main/canny-edge.jpg",
model='civitai:38784@44716'
)
request_image=IImageInference(
positivePrompt="a beautiful sunset",
model='civitai:4384@128713',
controlNet=[controlNet],
numberResults=1,
height=512,
width=512,
outputType="URL",
seed=1568,
steps=40
)
images=awaitrunware.imageInference(requestImage=request_image)
forimageinimages:
print(f"Image URL: {image.imageURL}")

This example demonstrates how to configure and use a ControlNet to enhance the image inference process.

Inferencing Ace++ Pipeline

To use Ace++ in the Runware SDK, you can use a class IAcePlusPlus. Here's an example of how to set up and use this feature: Much more examples are in examples/ace++

fromrunwareimportRunware, IImageInference, IAcePlusPlusasyncdefmain() ->None:
runware=Runware(api_key=RUNWARE_API_KEY)
awaitrunware.connect()
# Upload your reference image and maskreference_image="https://raw.githubusercontent.com/ali-vilab/ACE_plus/refs/heads/main/assets/samples/application/logo_paste/1_ref.png"mask_image="https://raw.githubusercontent.com/ali-vilab/ACE_plus/refs/heads/main/assets/samples/application/logo_paste/1_1_m.png"init_image="https://raw.githubusercontent.com/ali-vilab/ACE_plus/refs/heads/main/assets/samples/application/logo_paste/1_1_edit.png"request_image=IImageInference(
positivePrompt="The logo is printed on the headphones.",
model="runware:102@1", # Required model for ACE++taskUUID="68020b8f-bbcf-4779-ba51-4f3bb00aef6a",
height=1024,
width=1024,
numberResults=1,
steps=28,
CFGScale=50.0,
referenceImages=[reference_image], # Reference imageacePlusPlus=IAcePlusPlus(
inputImages=[init_image], # Input imageinputMasks=[mask_image], # Mask for selective editingrepaintingScale=1.0,
taskType="subject"# Can be one of "portrait", "subject", "local_editing"
),
)
print(f"Sending request: {request_image}")
images=awaitrunware.imageInference(requestImage=request_image)
forimageinimages:
print(f"Image URL: {image.imageURL}")

This example demonstrates how to configure and use a ControlNet to enhance the image inference process.

Generating Images with OpenAI Models (DALL-E 2 & DALL-E 3)

The Runware SDK supports OpenAI's DALL-E 2 and DALL-E 3 models for image generation. These models offer high-quality image generation with various configuration options.

DALL-E 2

fromrunwareimportRunware, IImageInference, IOpenAIProviderSettingsasyncdefmain() ->None:
runware=Runware(api_key=RUNWARE_API_KEY)
awaitrunware.connect()
# DALL-E 2 configurationprovider_settings=IOpenAIProviderSettings(
quality="high",
background="transparent"# Optional: for transparent backgrounds
)
request_image=IImageInference(
positivePrompt="A cute cartoon robot character",
model="openai:1@1", # DALL-E 2 model identifierwidth=1024,
height=1024,
numberResults=1,
outputFormat="PNG",
includeCost=True,
providerSettings=provider_settings
)
images=awaitrunware.imageInference(requestImage=request_image)
forimageinimages:
print(f"Image URL: {image.imageURL}")

DALL-E 3

fromrunwareimportRunware, IImageInference, IOpenAIProviderSettingsasyncdefmain() ->None:
runware=Runware(api_key=RUNWARE_API_KEY)
awaitrunware.connect()
# DALL-E 3 with HD qualityprovider_settings=IOpenAIProviderSettings(
quality="hd"# Options: "hd" or "standard"
)
request_image=IImageInference(
positivePrompt="A futuristic city with flying cars, highly detailed",
model="openai:2@3", # DALL-E 3 model identifierwidth=1024,
height=1024,
numberResults=1,
outputFormat="PNG",
includeCost=True,
providerSettings=provider_settings
)
images=awaitrunware.imageInference(requestImage=request_image)
forimageinimages:
print(f"Image URL: {image.imageURL}")

OpenAI Provider Settings:

• quality: Image quality setting
  • DALL-E 2: "high" (recommended)
  • DALL-E 3: "hd" or "standard"
• background: (DALL-E 2 only) Set to "transparent" for transparent backgrounds
• style: (Optional) Additional style parameters

Model Identifiers:

• DALL-E 2: "openai:1@1"
• DALL-E 3: "openai:2@3"

Inferencing Video Models

To inference Video Generation Models in the Runware SDK, you can use a class IVideoInference. Almost every video model support its own providerSettings: IMinimaxProviderSettings, IBytedanceProviderSettings, IGoogleProviderSettings, IKlingAIProviderSettings, IPixverseProviderSettings, IViduProviderSettings. More examples can be found in examples/video.

Here's an example of an image-to-video (i2v) task using Google's Veo3:

importasynciofromrunwareimportRunware, IVideoInference, IGoogleProviderSettings, IFrameImageasyncdefmain():
runware=Runware(
api_key=RUNWARE_API_KEY,
)
awaitrunware.connect()
request=IVideoInference(
positivePrompt="spinning galaxy",
model="google:3@0",
width=1280,
height=720,
numberResults=1,
seed=10,
includeCost=True,
frameImages=[ # Comment this to use t2vIFrameImage(
inputImage="https://github.com/adilentiq/test-images/blob/main/common/image_15_mb.jpg?raw=true",
),
],
providerSettings=IGoogleProviderSettings(
generateAudio=True,
enhancePrompt=True
)
)
videos=awaitrunware.videoInference(requestVideo=request)
forvideoinvideos:
print(f"Video URL: {video.videoURL}")
print(f"Cost: {video.cost}")
print(f"Seed: {video.seed}")
print(f"Status: {video.status}")
if__name__=="__main__":
asyncio.run(main())

Audio Inference

To generate audio using the Runware SDK, you can use the audioInference method with the IAudioInference class. The SDK supports various audio generation models including ElevenLabs and other providers.

Here's an example of generating audio using ElevenLabs:

importasynciofromrunwareimportRunware, IAudioInference, IAudioSettingsasyncdefmain() ->None:
runware=Runware(api_key=RUNWARE_API_KEY)
awaitrunware.connect()
# Create audio settingsaudio_settings=IAudioSettings(
sampleRate=22050, # Sample rate in Hzbitrate=32# Audio bitrate
)
# Create audio inference requestrequest_audio=IAudioInference(
model="elevenlabs:1@1", # ElevenLabs modelpositivePrompt="upbeat electronic music with synthesizers and drums",
outputFormat="MP3", # Output format: MP3, WAV, etc.outputType="URL", # Return URL or base64audioSettings=audio_settings,
numberResults=1, # Number of audio files to generateduration=10, # Duration in secondsincludeCost=True# Include cost information
)
audio_results=awaitrunware.audioInference(requestAudio=request_audio)
foraudioinaudio_results:
print(f"Audio URL: {audio.audioURL}")
print(f"Duration: {audio.duration}")
print(f"Cost: {audio.cost}")
if__name__=="__main__":
asyncio.run(main())

Audio Settings

The IAudioSettings class allows you to configure audio generation parameters:

• sampleRate: Audio sample rate in Hz (e.g., 22050, 44100)
• bitrate: Audio bitrate for compressed formats

Audio Inference Parameters

The IAudioInference class supports the following parameters:

• model: Audio generation model identifier (e.g., "elevenlabs:1@1")
• positivePrompt: Text description of the audio to generate
• outputFormat: Output audio format ("MP3", "WAV", etc.)
• outputType: Return type ("URL" or "BASE64")
• audioSettings: Audio configuration settings
• numberResults: Number of audio files to generate
• duration: Duration of the generated audio in seconds
• includeCost: Whether to include cost information in the response

Text inference with tools (function calling)

Set tools on ITextInference to declare functions (ITextInferenceTool with toolType="function", name, description, schema). Add assistant tools rows and role": "tool" messages using API field names id and input (or use ITextInferenceMessage / ITextInferenceMessageTool with toolId / toolInput on the Python side).

importasynciofromrunwareimportRunware, ITextInference, ITextInferenceToolasyncdefmain() ->None:
runware=Runware(api_key=RUNWARE_API_KEY)
awaitrunware.connect()
req=ITextInference(
model="deepseek:v4@flash",
messages=[
{"role": "user", "content": "Weather in Tokyo?"},
{"role": "assistant", "tools": [{"id": "c1", "name": "get_weather", "input": {"city": "Tokyo"}}]},
{"role": "tool", "id": "c1", "content": "22°C, partly cloudy."},
],
tools=[
ITextInferenceTool(
toolType="function",
name="get_weather",
description="Get weather for a city.",
schema={"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
),
],
settings={"maxTokens": 300},
)
fortinawaitrunware.textInference(req):
print(t.text)
if__name__=="__main__":
asyncio.run(main())

Text inference streaming

To stream text inference (e.g. LLM chat) over HTTP SSE, set deliveryMethod="stream". The SDK yields content chunks (strings) and a final IText with usage and cost:

importasynciofromrunwareimportRunware, ITextInference, ITextInferenceMessageasyncdefmain() ->None:
runware=Runware(api_key=RUNWARE_API_KEY)
awaitrunware.connect()
request=ITextInference(
model="runware:qwen3-thinking@1",
messages=[ITextInferenceMessage(role="user", content="Explain photosynthesis in one sentence.")],
deliveryMethod="stream",
includeCost=True,
)
stream=awaitrunware.textInference(request)
asyncforchunkinstream:
ifisinstance(chunk, str):
print(chunk, end="", flush=True)
else:
print(chunk)
asyncio.run(main())

Streaming uses the same concurrency limit as other requests (RUNWARE_MAX_CONCURRENT_REQUESTS). To allow longer streams, set RUNWARE_TEXT_STREAM_TIMEOUT (milliseconds; default 600000).

Model Upload

To upload model using the Runware API, you can use the uploadModel method of the Runware class. Here are examples:

fromrunwareimportRunware, IUploadModelCheckPointasyncdefmain() ->None:
runware=Runware(api_key=RUNWARE_API_KEY)
awaitrunware.connect()
payload=IUploadModelCheckPoint(
air='qatests:68487@08629',
name='yWO8IaKwez',
heroImageURL='https://raw.githubusercontent.com/adilentiq/test-images/refs/heads/main/image.jpg',
downloadURL='https://repo-controlnets-r2.runware.ai/controlnet-zoe-depth-sdxl-1.0.safetensors''/controlnet-zoe-depth-sdxl-1.0.safetensors.part-001-1',
uniqueIdentifier='aq2w3e4r5t6y7u8i9o0p1q2w3e4r5t6y7u8i9o0p1q2w3e4r5t6y7u8i9o0p1234',
version='1.0',
tags=['tag1', 'tag2', 'tag2'],
architecture='flux1d',
type='base',
defaultWeight=0.8,
format='safetensors',
positiveTriggerWords='my trigger word',
shortDescription='a model description',
private=False,
defaultScheduler='Default',
comment='some comments if you want to add for internal use',
)
uploaded=awaitrunware.modelUpload(payload)
print(f"Response : {uploaded}")

fromrunwareimportRunware, IUploadModelLoraasyncdefmain() ->None:
runware=Runware(api_key=RUNWARE_API_KEY)
awaitrunware.connect()
payload=IUploadModelLora(
air='qatests:68487@08629',
name='yWO8IaKwez',
heroImageURL='https://raw.githubusercontent.com/adilentiq/test-images/refs/heads/main/image.jpg',
downloadURL='https://repo-controlnets-r2.runware.ai/controlnet-zoe-depth-sdxl-1.0.safetensors''/controlnet-zoe-depth-sdxl-1.0.safetensors.part-001-1',
uniqueIdentifier='aq2w3e4r5t6y7u8i9o0p1q2w3e4r5t6y7u8i9o0p1q2w3e4r5t6y7u8i9o0p1234',
version='1.0',
tags=['tag1', 'tag2', 'tag2'],
architecture='flux1d',
defaultWeight=0.8,
format='safetensors',
positiveTriggerWords='my trigger word',
shortDescription='a model description',
private=False,
comment='some comments if you want to add for internal use',
)
uploaded=awaitrunware.modelUpload(payload)
print(f"Response : {uploaded}")

fromrunwareimportRunware, IUploadModelControlNetasyncdefmain() ->None:
runware=Runware(api_key=RUNWARE_API_KEY)
awaitrunware.connect()
payload=IUploadModelControlNet(
air='qatests:68487@08629',
name='yWO8IaKwez',
heroImageURL='https://raw.githubusercontent.com/adilentiq/test-images/refs/heads/main/image.jpg',
downloadURL='https://repo-controlnets-r2.runware.ai/controlnet-zoe-depth-sdxl-1.0.safetensors''/controlnet-zoe-depth-sdxl-1.0.safetensors.part-001-1',
uniqueIdentifier='aq2w3e4r5t6y7u8i9o0p1q2w3e4r5t6y7u8i9o0p1q2w3e4r5t6y7u8i9o0p1234',
version='1.0',
tags=['tag1', 'tag2', 'tag2'],
architecture='flux1d',
format='safetensors',
shortDescription='a model description',
private=False,
comment='some comments if you want to add for internal use',
)
uploaded=awaitrunware.modelUpload(payload)
print(f"Response : {uploaded}")

Image Background Removal

There are two ways to remove the background from an image.

1. Using the settings parameter of the IImageBackgroundRemoval class.
2. Without using the settings parameter and using the model parameter to specify the model to use.

Using the settings parameter

Note: When using the rgba parameter, the final a value is a float between 0.0 and 1.0, but a value of 1-255 will be internally scaled down to the correct float range.

fromrunwareimportRunware, RunwareAPIError, IImage, IImageBackgroundRemoval, IBackgroundRemovalSettingsimportasyncioimportosfromdotenvimportload_dotenvload_dotenv(override=True)
asyncdefmain() ->None:
runware=Runware(
api_key=os.environ.get("RUNWARE_API_KEY")
)
awaitrunware.connect()
background_removal_settings=IBackgroundRemovalSettings(
rgba=[255, 255, 255, 0],
alphaMatting=True,
postProcessMask=True,
returnOnlyMask=False,
alphaMattingErodeSize=10,
alphaMattingForegroundThreshold=240,
alphaMattingBackgroundThreshold=10
)
request_image=IImageBackgroundRemoval(
taskUUID="abcdbb9c-3bd3-4d75-9234-bffeef994772",
inputImage="https://raw.githubusercontent.com/adilentiq/test-images/refs/heads/main/common/headphones.jpeg",
settings=background_removal_settings,
outputType="URL",
outputFormat="PNG",
includeCost=True,
)
print(f"Payload: {request_image}")
try:
processed_images: List[IImage] =awaitrunware.imageBackgroundRemoval(
removeImageBackgroundPayload=request_image
)
exceptRunwareAPIErrorase:
print(f"API Error: {e}")
print(f"Error Code: {e.code}")
exceptExceptionase:
print(f"Unexpected Error: {e}")
else:
print("Processed Image with the background removed:")
print(processed_images)
forimageinprocessed_images:
print(image.imageURL)
asyncio.run(main())

Using the model parameter

fromrunwareimportRunware, RunwareAPIError, IImage, IImageBackgroundRemovalimportasyncioimportosfromdotenvimportload_dotenvload_dotenv(override=True)
asyncdefmain() ->None:
runware=Runware(
api_key=os.environ.get("RUNWARE_API_KEY"),
)
awaitrunware.connect()
request_image=IImageBackgroundRemoval(
taskUUID="abcdbb9c-3bd3-4d75-9234-bffeef994772",
model="runware:110@1",
inputImage="https://raw.githubusercontent.com/adilentiq/test-images/refs/heads/main/common/headphones.jpeg"
)
print(f"Payload: {request_image}")
try:
processed_images: List[IImage] =awaitrunware.imageBackgroundRemoval(
removeImageBackgroundPayload=request_image
)
exceptRunwareAPIErrorase:
print(f"API Error: {e}")
print(f"Error Code: {e.code}")
exceptExceptionase:
print(f"Unexpected Error: {e}")
else:
print("Processed Image with the background removed:")
print(processed_images)
forimageinprocessed_images:
print(image.imageURL)
asyncio.run(main())

For more detailed usage and additional examples, please refer to the examples directory.

Configuring Timeouts

The Runware SDK provides configurable timeout settings for different operations through environment variables. All timeout values are in milliseconds.

Timeout Configuration

Set environment variables to customize timeout behavior:

# Concurrency
RUNWARE_MAX_CONCURRENT_REQUESTS=15 # Max concurrent API requests per client (default: 15)# Image Operations (milliseconds)
RUNWARE_IMAGE_INFERENCE_TIMEOUT=300000 # Image generation (default: 5 min)
RUNWARE_IMAGE_OPERATION_TIMEOUT=120000 # Caption, upscale, background removal (default: 2 min)
RUNWARE_IMAGE_UPLOAD_TIMEOUT=60000 # Image upload (default: 1 min)
RUNWARE_MAX_POLLS_IMAGE_GENERATION=480 # Max polling attempts for async image / getResponse (default: 480)# Model Operations (milliseconds)
RUNWARE_MODEL_UPLOAD_TIMEOUT=900000 # Model upload (default: 15 min)# Video Operations (milliseconds)
RUNWARE_VIDEO_INITIAL_TIMEOUT=30000 # Initial response wait (default: 30 sec)
RUNWARE_VIDEO_POLLING_DELAY=3000 # Delay between status checks (default: 3 sec)
RUNWARE_MAX_POLLS_VIDEO_GENERATION=480 # Max polling attempts for video / caption / upscale / bg removal (default: 480, ~24 min total)# 3D Operations
RUNWARE_MAX_POLLS_3D_GENERATION=480 # Max polling attempts for 3D inference / getResponse (default: 480)# Audio Operations (milliseconds)
RUNWARE_AUDIO_INFERENCE_TIMEOUT=300000 # Audio generation (default: 5 min)
RUNWARE_AUDIO_POLLING_DELAY=1000 # Delay between status checks (default: 1 sec)
RUNWARE_MAX_POLLS_AUDIO_GENERATION=240 # Max polling attempts for audio inference (default: 240, ~4 min total)# Text Operations (milliseconds)
RUNWARE_TEXT_STREAM_TIMEOUT=600000 # Text inference streaming (SSE) read timeout (default: 10 min)# Other Operations (milliseconds)
RUNWARE_PROMPT_ENHANCE_TIMEOUT=60000 # Prompt enhancement (default: 1 min)
RUNWARE_WEBHOOK_TIMEOUT=30000 # Webhook acknowledgment (default: 30 sec)
RUNWARE_TIMEOUT_DURATION=480000 # General operations (default: 8 min)

Usage Example

importos# Configure before importing Runwareos.environ["RUNWARE_VIDEO_POLLING_DELAY"] ="5000"# 5 seconds between checksos.environ["RUNWARE_MAX_POLLS_VIDEO_GENERATION"] ="600"# Allow up to 50 minutesfromrunwareimportRunwareasyncdefmain():
runware=Runware(api_key=os.getenv("RUNWARE_API_KEY"))
awaitrunware.connect()
# Your code here

Note: For long-running video operations, consider using webhooks or deliveryMethod="async" to avoid timeout issues with extended generation times.