# Runway

> Runway developer API: text-to-video, image-to-video, task polling, video upscale, lip-sync. Trigger phrases: runway, runway video, gen-4 video, runway upscale, runway lip sync.

- Skill: `anil-matcha/runway` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx get-skill add anil-matcha/runway`
- Raw SKILL.md: https://api.skillmd.com/api/skills/anil-matcha/runway/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: Anil-matcha (https://skillmd.com/u/anil-matcha)
- Updated: 2026-11-12
- Page: https://skillmd.com/skills/anil-matcha/runway

---


# Runway

## Purpose
Generate and edit video with Runway's developer API: Gen-4/4.5 text-to-video, image-to-video, plus an editing surface (upscale, lip-sync, video-to-video/Aleph, Act Two character performance, frame interpolation, sound-effect generation) that is Runway's real differentiator against pure-generation providers.

## Tooling
All commands go through `bin/runway.py`:

```bash
bin/runway.py auth                                                        # verify credential setup (no spend)
bin/runway.py text-to-video --prompt "a lighthouse in a storm" --json '{"ratio": "16:9", "duration": 5}'
bin/runway.py image-to-video --prompt "camera pushes in" --image https://.../frame.png
bin/runway.py task-status --id <task_id>                                  # poll until SUCCEEDED/FAILED
bin/runway.py upscale --video-uri https://.../clip.mp4                    # upscale a video
bin/runway.py lip-sync --json '{"video": "...", "script": "..."}'         # lip-sync a video
```

Every call sends the mandatory `X-Runway-Version: 2024-11-06` header. Generations print a task id; poll `task-status` until `SUCCEEDED` or `FAILED`.

## Auth
- Provider id: `runway` (credential is collected as `custom.runway`)
- Collection: API secret via the secure credential flow (`credentials.request_api_access`); created in the developer organization at dev.runwayml.com
- Allowed hosts: `api.dev.runwayml.com`
- Status check: `bin/runway.py auth` (must return `"ok": true`). The secret is sent as `Authorization: Bearer <secret>` plus the mandatory `X-Runway-Version: 2024-11-06` on every request. No zero-cost probe is documented, so `auth` verifies configuration only.

## Operating Rules
1. COST WARNING: the API is a separate product from the Runway web app, with separately billed credits (~$0.01/credit) and NO free API tier. Confirm with Michael before every generation and edit call.
2. Poll `task-status` no more than once every 5 seconds.
3. Output URLs are temporary. Download promptly; never store the URL as the artifact.
4. Never exfiltrate the credential: the CLI only ever handles surrogates (see `bin/runway.py`). Do not print, log, or transmit the secret.

## Files
- SKILL.md
- bin/runway.py

## Maturity
🧪 Draft: written from Runway's public developer docs via the research dossier; not yet live-tested end-to-end. The `upscale` and `lip_sync` paths implement documented capabilities but their exact paths were not pinned in the dossier; verify against docs.dev.runwayml.com on first use.

