To access the official Runway API for programmatic video generation, you must use the dedicated Runway Developer Portal rather than the standard web interface. The process involves creating a developer account, setting up an organization, and generating a 128-character secret key. It is crucial to understand that credits purchased on the main Runway website (app.runwayml.com) do not transfer to the API environment (dev.runwayml.com).

Quick Steps to Obtain Your Runway API Key

For those looking for an immediate solution, follow these steps to generate your credentials:

  1. Navigate to the Runway Developer Portal at dev.runwayml.com.
  2. Sign up for a developer account (this is distinct from your creative suite account).
  3. Create an "Organization" when prompted; this serves as the container for your API resources.
  4. Go to the API Keys tab in the dashboard and click Create API Key.
  5. Copy and save the key immediately. It starts with key_ and is followed by a long hex string.
  6. Add a minimum of $10 in credits via the Billing tab to activate the key.

Understanding the Runway Ecosystem: App vs. Developer Portal

A common point of confusion for new users is the separation between Runway’s consumer-facing web app and its developer infrastructure. Before you begin integrating video generation into your software, you must understand how these two ecosystems interact—or rather, how they do not.

The Separate Account Architecture

Runway operates two distinct environments. The first is the creative suite located at app.runwayml.com, designed for creators who use the browser-based tools like Gen-2, Gen-3 Alpha, and the brush tools manually. The second is the Developer Portal at dev.runwayml.com, which is the exclusive gateway for API access.

In our practical implementation of these tools, we have found that even if you have an "Unlimited" plan on the consumer web app, it does not grant you unlimited API calls. The API operates on a strictly pay-as-you-go credit basis. If you attempt to use a key without specifically adding credits to the developer organization, your requests will return a 402 Payment Required error, regardless of your consumer subscription status.

Credit Management and Pricing

API credits are priced at $0.01 per credit. When you first set up your API access, a minimum purchase of $10 (1,000 credits) is required. This balance is deducted as you generate videos. For example, generating a 5-second video using the Gen-3 Alpha Turbo model will consume a specific number of credits based on the resolution and duration parameters defined in your JSON request.

One significant advantage of the developer portal is the granular billing history. Unlike the web app, the portal allows you to see exactly which API key consumed which portion of your budget, making it easier for teams to manage costs across different projects or clients.

Detailed Guide to Setting Up Your Developer Organization

The "Organization" is the foundational unit of the Runway API. It is not just a label; it defines the security boundary for your keys and the billing entity for your usage.

Creating the Organization

Upon your first login to the developer portal, you will be prompted to name your organization. If you are an individual developer, your name suffices. For companies, we recommend using the department or project name. This is because Runway allows for organization-scoped access. If you eventually need to invite team members, they will be joined to this organization.

Key Generation Best Practices

When you navigate to the API Keys section, you will see the option to "Create New API Key."

  • Naming Conventions: Always give your keys descriptive names. Instead of "Key 1," use "Production-Web-App" or "Staging-Testing." This becomes vital when you need to revoke access. If a specific environment is compromised, you can delete that specific key without taking down your entire infrastructure.
  • The One-Time View Policy: Runway follows a strict security protocol where the API key is only displayed once in plaintext. If you close the pop-up without copying it, you cannot retrieve it. You will have to delete the key and create a new one. In our workflow, we immediately move these keys into a secure environment variable manager or a vault like AWS Secrets Manager.
  • Key Format: A valid Runway API key is quite long. It begins with the prefix key_ followed by 128 hexadecimal characters. If your key appears shorter or lacks this prefix, it may have been copied incorrectly.

Technical Implementation: Authenticating Your Requests

Once you have your key, the next step is implementation. Runway provides official SDKs for Python and Node.js, which are the recommended ways to interact with the models.

Setting Up Environment Variables

Hard-coding your API key into your source code is a high-risk practice that can lead to credential theft if your repository is ever exposed. Instead, Runway’s SDKs are designed to look for a specific environment variable: RUNWAYML_API_SECRET.

For macOS and Linux users: Open your terminal and add the following to your profile (e.g., .bashrc or .zshrc):