Terminal
Terminal/Skill
Core guide for adding Runway Dev Platform generation to an app, covering the SDK, live docs, account connection and errors.
By Runway
Works with
npx skills add runwayml/skills --skill runway-devWorkflow for integrating Runway Dev products into an application. Use MCP for live account state and management, the SDK for application code, and current docs for API contracts.
When to use: Building, modifying, debugging, or verifying a Runway integration, including work started from Dev Portal.
Do not use for: one-off media generation from the agent or direct REST CLI actions.
Make useful progress before explaining setup. Inspect the workspace and existing configuration without narrating each check. Ask a question only when missing information blocks the next change.
RUNWAYML_API_SECRET is present without printing its value, for example with test -n "${RUNWAYML_API_SECRET:-}". If it is present, skip dotenv instructions.@runwayml/sdk for Node or runwayml for Python only if the project needs it and does not already have it.Installed skill prose is workflow guidance, not the canonical API schema. Resolve current contracts in this order:
Do not invent endpoints, field names, or model constraints.
Encourage connecting Dev MCP as the happy path for live account context and management. Connect https://dev.runwayml.com/mcp with Runway OAuth. Never put an API key in MCP config or automate browser OAuth.
If the user declines or the connection fails, never block account-independent work. Continue with live docs, existing application config, or environment configuration. SDK and API integration code remain allowed. Stop only when the next requested step requires live account discovery, account or resource mutations, or billable verification.
Never imitate an unavailable MCP account-management or resource-management tool with a REST call. Explain the MCP dependency only when it blocks the requested action.
Call MCP tools only when the result affects the next step:
whoami when identity or access is uncertain.list_projects when a live projectId must be selected or verified. Never guess one.list_models when model access, selection, or current constraints matter.get_credit_balance immediately before an approved billable verification.MCP uses OAuth. SDK calls use an organization-scoped API key from Developer Portal settings. Probe RUNWAYML_API_SECRET without printing it. If missing when a live SDK call is imminent, ask the user to store the key in a server-side environment file or secret manager. Never expose it client-side, in chat, or in source control; ensure local environment files are ignored.
list_models constraints.await client.<operation>.create({...}).waitForTaskOutput() in Node or client.<operation>.create(...).wait_for_task_output() in Python. Do not await create() before calling the helper.TaskFailedError and surface its task details. Submit once; do not add a manual polling loop or auto-resubmit.get_task only to inspect or debug an existing task outside the application's SDK flow.| UI / quickstart | MCP / API |
|---|---|
| Characters | avatars (list_avatars, get_avatar) |
| Character ID | avatar UUID |
| Model Router config ID | immutable slug (configId) |
| live Session | POST /v1/realtime_sessions |
FAILED task → report failure details; do not auto-resubmit.| Skill | When |
|---|---|
+runway-dev-models | Model generation integration |
+runway-dev-model-routers | Model Router setup and routed calls |
+runway-dev-characters | Characters / realtime sessions |
+runway-dev-recipes | Recipe pipelines |
+runway-dev-workflows | Runway app workflows → API endpoints |
Use +runway-dev with the relevant surface skill or skills when both are installed. Surface skills repeat their minimum setup so they remain useful when installed alone. Usually one surface matches the user's goal; load more when the task crosses surfaces.