Install & Compatibility
Where this runs
tested against v5.1.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.960 runs
installs and imports cleanly · install 0.0s · import 1.164s · 42.2MB
glibcpy 3.10–3.960 runs
installs and imports cleanly · install 5.0s · import 1.066s · 44MB
42MB installed
● package 42MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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.
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}")
Debug
Known issues
gotchaRunwayML 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.fixEnsure `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).
affects: All versions
gotchaAPI 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.fixUse 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.
affects: All versions
breakingDependency 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.fixEnsure `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'`).
affects: >=4.7.1
deprecatedThe 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.fixDo 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.
affects: SDK for API access: All versions. Model SDK: Deprecated as of March 28, 2022.
Errors
Common errors & fixes
runwayml.APIStatusError: API response 401: Unauthorized
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.
fixSet 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
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.
fixReview 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.
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).
fixInspect 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)
Compatibility issues between Python versions, `typing-extensions`, and `pydantic` when using advanced type hints like `Literal` or `TypedDict` that are backported via `typing-extensions`.
fixEnsure 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.
Upgrade
Version history
5.1.0latest on PyPI · released Jun 12, 2026
Audit
Dependencies
python>=3.9requiredMinimum Python version required for the SDK.
httpxrequiredPowers synchronous and asynchronous HTTP requests internally.
pydanticrequiredUsed for type definitions of request parameters and response fields.
typing-extensionsrequiredProvides backports of new `typing` module features, crucial for compatibility with Pydantic across various Python versions, especially below 3.10.
aiohttpoptionalOptional dependency for improved asynchronous client performance.
python-dotenvoptionalRecommended for managing API keys via .env files.