Full Runway API Setup
PREREQUISITE: Run
first to ensure the project has server-side capability.
This recipe guides a user through the complete process of integrating Runway's public API into their project. It chains together the compatibility check, API key setup, and API integration skills.
Workflow
Phase 1: Compatibility Check
Use
to analyze the user's project.
- Identify the project type (Node.js, Python, etc.)
- Verify server-side capability
- Check runtime version compatibility
- Look for existing Runway SDK installation
If the project is INCOMPATIBLE, stop and explain the options:
- Add a backend (Express, FastAPI, etc.)
- Use a fullstack framework (Next.js, SvelteKit, Nuxt, Remix)
- Add serverless functions (Vercel Functions, AWS Lambda)
- Create a separate backend service
If NEEDS CHANGES, help the user make the required changes before proceeding.
If COMPATIBLE, proceed to Phase 2.
Phase 2: API Key Setup
Use
to configure credentials.
- Direct the user to https://dev.runwayml.com/ to create an account and API key
- Install the appropriate SDK ( for Node.js, for Python)
- Configure the environment variable
- Update to exclude
- Remind about credit purchase requirement ($10 minimum)
Wait for the user to confirm they have their API key before proceeding.
Phase 3: Determine What to Integrate
Ask the user what they want to build. Based on their response, use the appropriate integration skill:
| User wants... | Skill to use |
|---|
| Generate videos from text | (text-to-video) |
| Animate images into video | (image-to-video) + if local files |
| Edit/transform existing videos | (video-to-video) + |
| Generate images from text | |
| Generate images with references | + if local refs |
| Text-to-speech | |
| Sound effects | |
| Voice isolation/dubbing | + |
| Real-time conversational avatar | + +integrate-character-embed
|
| Avatar with domain knowledge | + + +integrate-character-embed
|
| Multiple capabilities | Integrate each one, sharing the same client instance |
Phase 4: Write the Integration Code
Based on the user's framework and needs:
- Create the API route/handler — server-side endpoint that calls Runway
- Add upload handling if the user needs to accept files from their users
- Add error handling — catch and handle task failures
- Handle output storage — remind user that output URLs expire in 24-48 hours
Phase 5: Test and Verify
Help the user:
- Run a test generation to verify everything works
- Check for common issues (missing env var, insufficient credits, wrong model)
- Confirm output is accessible
Decision Tree for Upload Requirements
When the user's workflow involves images or videos as input:
Does the input come from a public HTTPS URL?
├── YES → Pass the URL directly to the API
└── NO → Is it a local file or user-uploaded file?
├── YES → Use +integrate-uploads to upload first, then pass runway:// URI
└── NO → Is it small enough for a data URI? (< 5MB image, < 16MB video)
├── YES → Convert to base64 data URI
└── NO → Use +integrate-uploads
Important Reminders
- Never expose the API key in client-side code. All API calls must happen server-side.
- Output URLs expire. Always download and store generated content.
- Credits are required. The API won't work without prepaid credits.
- Rate limits exist. Rate limits exist. You should always check what is the rate limit before attempting concurrent generations.
- Content moderation applies to both inputs and outputs. Safety-flagged inputs are non-refundable.
- Be cost-conscious. Help users pick the right model for their budget. Credit cost can be found on https://docs.dev.runwayml.com/guides/pricing/