{"id":7694,"library":"runwayml","title":"RunwayML Python SDK","description":"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.","status":"active","version":"4.12.0","language":"en","source_language":"en","source_url":"https://github.com/runwayml/sdk-python","tags":["AI","Machine Learning","Generative AI","Video Generation","Image Generation","API Client","Media Processing"],"install":[{"cmd":"pip install runwayml","lang":"bash","label":"Standard installation"},{"cmd":"pip install runwayml[aiohttp]","lang":"bash","label":"Install with aiohttp for async performance"},{"cmd":"pip install python-dotenv runwayml","lang":"bash","label":"Recommended for API key management"}],"dependencies":[{"reason":"Minimum Python version required for the SDK.","package":"python>=3.9","optional":false},{"reason":"Powers synchronous and asynchronous HTTP requests internally.","package":"httpx","optional":false},{"reason":"Used for type definitions of request parameters and response fields.","package":"pydantic","optional":false},{"reason":"Provides backports of new `typing` module features, crucial for compatibility with Pydantic across various Python versions, especially below 3.10.","package":"typing-extensions","optional":false},{"reason":"Optional dependency for improved asynchronous client performance.","package":"aiohttp","optional":true},{"reason":"Recommended for managing API keys via .env files.","package":"python-dotenv","optional":true}],"imports":[{"note":"Main synchronous client for interacting with the RunwayML API.","symbol":"RunwayML","correct":"from runwayml import RunwayML"},{"note":"Asynchronous client for non-blocking API calls.","symbol":"AsyncRunwayML","correct":"from runwayml import AsyncRunwayML"},{"note":"Exception raised when an API task initiated (e.g., video generation) fails.","symbol":"TaskFailedError","correct":"from runwayml import TaskFailedError"},{"note":"Used to configure `AsyncRunwayML` to use `aiohttp` for HTTP requests.","symbol":"DefaultAioHttpClient","correct":"from runwayml import DefaultAioHttpClient"}],"quickstart":{"code":"import os\nfrom runwayml import RunwayML, TaskFailedError\n\n# Ensure RUNWAYML_API_SECRET is set in your environment or .env file\n# Recommended: use python-dotenv for local development.\n# Example: os.environ[\"RUNWAYML_API_SECRET\"] = \"key_YOUR_API_KEY_HERE\"\n\nclient = RunwayML(\n    api_key=os.environ.get(\"RUNWAYML_API_SECRET\", \"\")\n)\n\nif not client.api_key:\n    print(\"Error: RUNWAYML_API_SECRET environment variable not set.\")\n    print(\"Please set your RunwayML API key before running the quickstart.\")\n    exit(1)\n\ntry:\n    # Example: Create an image-to-video task using Gen-4.5 model\n    print(\"Creating image-to-video task...\")\n    image_to_video_task = client.image_to_video.create(\n        model=\"gen4_turbo\",\n        prompt_image=\"https://example.com/assets/bunny.jpg\",\n        ratio=\"1280:720\",\n        prompt_text=\"The bunny is eating a carrot\",\n    ).wait_for_task_output() # SDK provides auto-polling\n\n    print(f\"Task completed. Generated video ID: {image_to_video_task.id}\")\n    # Further details like output URLs can be accessed via image_to_video_task.output\n\nexcept TaskFailedError as e:\n    print(f\"Task failed: {e.taskDetails}\")\n    print(\"Check the error details for specific reasons like content moderation or invalid inputs.\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"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).","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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'`).","message":"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.","severity":"breaking","affected_versions":">=4.7.1"},{"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.","message":"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.","severity":"deprecated","affected_versions":"SDK for API access: All versions. Model SDK: Deprecated as of March 28, 2022."}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","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.","error":"runwayml.APIStatusError: API response 401: Unauthorized"},{"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).","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.","error":"runwayml.APIStatusError: API response 400: Bad Request"},{"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.","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).","error":"runwayml.TaskFailedError: The task failed to generate."},{"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.","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`.","error":"TypeError: 'type' object is not subscriptable (when using `typing.Literal` on Python < 3.8, or similar typing issues)"}]}