RunwayML Python SDK

4.12.0 · active · verified Thu Apr 16

The `runwayml` Python library provides convenient, type-safe access to the RunwayML REST API, allowing Python 3.9+ applications to integrate generative AI models. It offers both synchronous and asynchronous clients powered by `httpx`, with optional `aiohttp` support for improved concurrency. The library is actively maintained with frequent releases, incorporating new API features and bug fixes.

Common errors

```
runwayml.APIStatusError: API response 401: Unauthorized
```
cause The API key provided is missing, invalid, improperly formatted, or the associated account does not have sufficient credits or is disabled. Keys must start with 'key_' followed by 128 hexadecimal characters.

fix Set the `RUNWAYML_API_SECRET` environment variable or `api_key` parameter with a correct, active, and funded RunwayML API key (e.g., `key_0123...`). Double-check for typos or leading/trailing whitespace. Verify your organization's billing status on dev.runwayml.com.
```
runwayml.APIStatusError: API response 400: Bad Request
```
cause The input parameters provided to an API endpoint are incorrect or malformed. This can include invalid image URLs, unsupported aspect ratios, incorrect model names, or content that violates API guidelines.

fix Review the specific error message for details on which field is invalid. Consult the RunwayML API documentation for the correct format, types, and constraints for the endpoint you are calling (e.g., image dimensions, acceptable prompt length, valid `ratio` values).
```
runwayml.TaskFailedError: The task failed to generate.
```
cause An asynchronous generation task (e.g., image-to-video) failed. Common reasons include content moderation violations (SAFETY failures), internal processing errors (INTERNAL.BAD_OUTPUT), or issues with provided assets (ASSET.INVALID).

fix Inspect the `e.taskDetails` attribute of the `TaskFailedError` for specific failure codes and messages. Adjust input prompts or assets to comply with content policies, or retry the operation if the error indicates a transient internal issue. Do not retry if the failure indicates an issue with your inputs.
```
TypeError: 'type' object is not subscriptable (when using `typing.Literal` on Python < 3.8, or similar typing issues)
```
cause Compatibility issues between Python versions, `typing-extensions`, and `pydantic` when using advanced type hints like `Literal` or `TypedDict` that are backported via `typing-extensions`.

fix Ensure your Python version is >= 3.9. Upgrade `typing-extensions` to the latest compatible version with your installed `pydantic` (e.g., `pip install --upgrade typing-extensions pydantic`). If using Python < 3.10, explicitly ensure `typing-extensions` is installed and up-to-date.

Warnings

gotcha RunwayML API keys are organization-scoped and require prepayment to activate. They are displayed only once upon creation. If lost, the key must be disabled and a new one generated. Web app credits are separate from API credits and cannot be used interchangeably.
Fix: Ensure `RUNWAYML_API_SECRET` environment variable is correctly set with a valid, prepaid, organization-scoped API key. Always copy your API key immediately upon creation. Verify billing status in the RunwayML Developer Portal (dev.runwayml.com).
gotcha API tasks are asynchronous and require polling to retrieve results. While the SDK provides `wait_for_task_output()` for convenience, be aware of underlying polling mechanisms. Frequent manual polling without exponential backoff can lead to rate limiting.
Fix: Use the SDK's built-in `wait_for_task_output()` method or implement polling with a minimum interval of 5 seconds, adding jitter and exponential backoff for robustness when manually handling task status.
breaking Dependency updates in v4.7.1 related to `typing-extensions` and `pydantic` could cause conflicts in environments with older, incompatible versions of these libraries. For example, specific `typing-extensions` versions might be required for Pydantic to function correctly, especially on Python versions older than 3.10.
Fix: Ensure `typing-extensions` and `pydantic` are up-to-date or match versions known to be compatible with your Python version. If encountering issues, try pinning `typing-extensions` to a version compatible with your Pydantic installation and Python runtime (e.g., `pip install 'typing-extensions>=4.6.0,<5.0.0'`).
deprecated The separate `runwayml/model-sdk` for porting custom machine learning models to the Runway platform has been deprecated. This is distinct from the `runwayml` SDK for API access, but can be a point of confusion.
Fix: Do not attempt to use the `runway-python` or `runwayml/model-sdk` for porting models. The current `runwayml` library is solely for interacting with the RunwayML cloud API and its pre-trained models.

Install

pip install runwayml Standard installation
pip install runwayml[aiohttp] Install with aiohttp for async performance
pip install python-dotenv runwayml Recommended for API key management

Imports

RunwayML
```
from runwayml import RunwayML
```
Main synchronous client for interacting with the RunwayML API.
AsyncRunwayML
```
from runwayml import AsyncRunwayML
```
Asynchronous client for non-blocking API calls.
TaskFailedError
```
from runwayml import TaskFailedError
```
Exception raised when an API task initiated (e.g., video generation) fails.
DefaultAioHttpClient
```
from runwayml import DefaultAioHttpClient
```
Used to configure `AsyncRunwayML` to use `aiohttp` for HTTP requests.

Quickstart

This quickstart demonstrates how to initialize the RunwayML client with an API key from an environment variable and create an image-to-video generation task. It utilizes the SDK's built-in `wait_for_task_output()` method for simplified asynchronous task polling and includes basic error handling for common API failures.

import os
from runwayml import RunwayML, TaskFailedError

# Ensure RUNWAYML_API_SECRET is set in your environment or .env file
# Recommended: use python-dotenv for local development.
# Example: os.environ["RUNWAYML_API_SECRET"] = "key_YOUR_API_KEY_HERE"

client = RunwayML(
    api_key=os.environ.get("RUNWAYML_API_SECRET", "")
)

if not client.api_key:
    print("Error: RUNWAYML_API_SECRET environment variable not set.")
    print("Please set your RunwayML API key before running the quickstart.")
    exit(1)

try:
    # Example: Create an image-to-video task using Gen-4.5 model
    print("Creating image-to-video task...")
    image_to_video_task = client.image_to_video.create(
        model="gen4_turbo",
        prompt_image="https://example.com/assets/bunny.jpg",
        ratio="1280:720",
        prompt_text="The bunny is eating a carrot",
    ).wait_for_task_output() # SDK provides auto-polling

    print(f"Task completed. Generated video ID: {image_to_video_task.id}")
    # Further details like output URLs can be accessed via image_to_video_task.output

except TaskFailedError as e:
    print(f"Task failed: {e.taskDetails}")
    print("Check the error details for specific reasons like content moderation or invalid inputs.")
except Exception as e:
    print(f"An unexpected error occurred: {e}")

view raw JSON →