rw-recipe-full-setup

What this skill does

# Full Runway API Setup

> **PREREQUISITE:** Run `+rw-check-compatibility` 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 `+rw-check-compatibility` to analyze the user's project.

1. Identify the project type (Node.js, Python, etc.)
2. Verify server-side capability
3. Check runtime version compatibility
4. 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 `+rw-setup-api-key` to configure credentials.

1. Direct the user to https://dev.runwayml.com/ to create an account and API key
2. Install the appropriate SDK (`@runwayml/sdk` for Node.js, `runwayml` for Python)
3. Configure the `RUNWAYML_API_SECRET` environment variable
4. Update `.gitignore` to exclude `.env`
5. 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       | `+rw-integrate-video` (text-to-video)                                              |
| Animate images into video       | `+rw-integrate-video` (image-to-video) + `+rw-integrate-uploads` if local files       |
| Edit/transform existing videos  | `+rw-integrate-video` (video-to-video) + `+rw-integrate-uploads`                      |
| Generate images from text       | `+rw-integrate-image`                                                              |
| Generate images with references | `+rw-integrate-image` + `+rw-integrate-uploads` if local refs                         |
| Text-to-speech                  | `+rw-integrate-audio`                                                              |
| Sound effects                   | `+rw-integrate-audio`                                                              |
| Voice isolation/dubbing         | `+rw-integrate-audio` + `+rw-integrate-uploads`                                       |
| Real-time conversational avatar | `+rw-integrate-characters` + `+rw-integrate-character-embed` (React UI)               |
| Avatar with domain knowledge    | `+rw-integrate-characters` + `+rw-integrate-documents` + `+rw-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:

1. **Create the API route/handler** — server-side endpoint that calls Runway
2. **Add upload handling** if the user needs to accept files from their users
3. **Add error handling** — catch and handle task failures
4. **Handle output storage** — remind user that output URLs expire in 24-48 hours

### Phase 5: Test and Verify

Help the user:

1. Run a test generation to verify everything works
2. Check for common issues (missing env var, insufficient credits, wrong model)
3. 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 +rw-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 +rw-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/