Quick Start

This guide will help you install Renku, set up your workspace, configure API keys, and generate your first AI-powered video.

Prerequisites

Before installing Renku, ensure you have:

• Node.js 18+ - Download from nodejs.org
• pnpm - Install with npm install -g pnpm
• FFmpeg (optional) - For native video export without Docker. Download from ffmpeg.org

Installation

Install the Renku CLI globally:

npm install -g @gorenku/cli

Verify the installation:

renku --version

Create a Workspace

Initialize a new Renku workspace:

renku init --root=/path/to/your/workspace

For example:

renku init --root=~/my-creations

This creates:

• ~/.config/renku/cli-config.json - Configuration file
• {workspace}/.gitignore - Ignores **/builds/ and **/artifacts/
• {workspace}/catalog/ containing:
  • models/ - Supported model configurations
  • producers/ - Supported producer definitions
  • blueprints/ - Example blueprints to get started

Note: Builds and artifacts are created in your current working directory when running renku generate, not in the workspace root. This supports project-based workflows.

Configure API Keys

Renku uses multiple AI providers. You’ll need API keys for the providers used by your chosen blueprint.

Providers

Depending on the blueprint and the models you select, you may need keys for the following providers:

Provider	Purpose	Get API Key
OpenAI	Script generation, prompt creation	platform.openai.com
Replicate	Video, audio, image generation	replicate.com
fal.ai	Video, audio, image generation	fal.ai
Wavespeed AI	Video, audio, image generation	wavespeed.ai

Set Environment Variables

When you run renku init, a placeholder script named env.sh is created in ~/.config/renku/. Edit this file to add your API keys:

# Renku API Keys Configuration
# Replace the placeholder values with your actual API keys
# Then source this file: source ~/.config/renku/env.sh

export REPLICATE_API_TOKEN="your-replicate-api-token-here"
export FAL_KEY="your-fal-api-key-here"
export WAVESPEED_API_KEY="your-wavespeed-api-key-here"
export OPENAI_API_KEY="your-openai-api-key-here"

Run Your First Blueprint

1. Create a Project from a Blueprint

First go to your workspace that you created earlier:

cd /path/to/your/workspace

Browse available blueprints in the catalog directory:

ls ./catalog/blueprints/

For this tutorial, we’ll use the ken-burns blueprint which generates a video with a Ken Burns effect, audio and background music. Create a new project based on this blueprint:

renku new:blueprint my-first-video --using=ken-burns

This creates a my-first-video/ folder with:

• my-first-video.yaml - Your blueprint file (copied and renamed from the catalog)
• input-template.yaml - Template for inputs configuration
• Any additional files (prompt producers, schemas, etc.)

Note: Always use new:blueprint to create your own copy of a blueprint. Never reference blueprints directly from the catalog - this ensures you can customize them and keeps your projects self-contained.

2. Configure Your Inputs

The input-template.yaml file is already included in your project. Edit it with your desired parameters:

cd my-first-video

Here’s an example configuration which will generate a 20-second video about the Eiffel Tower in a Ghibli style, each segment will have 1 image and there will be 2 segments in total. We are using the Replicate and OpenAI as providers, so you would need to have their API keys set in your environment.

inputs:
  InquiryPrompt: "Tell me about the history of the Eiffel Tower."
  Duration: 20
  NumOfSegments: 2
  NumOfImagesPerNarrative: 1
  Style: "Ghibli"
  Size: "1K"
  AspectRatio: "16:9"
  Audience: "Adult"
  VoiceId: "Wise_Woman"
  Emotion: neutral

models:
  - model: gpt-5-mini
    provider: openai
    producerId: ScriptProducer
    config:
      text_format: json_schema
  - model: gpt-5-mini
    provider: openai
    producerId: ImagePromptProducer
    config:
      text_format: json_schema
  - model: google/nano-banana
    provider: replicate
    producerId: ImageProducer
  - model: minimax/speech-2.6-hd
    provider: replicate
    producerId: AudioProducer
  - model: timeline/ordered
    provider: renku
    producerId: TimelineComposer
    config:
      tracks: ["Image", "Audio"]
      masterTracks: ["Audio"]
      numTracks: 2
      audioClip:
        artifact: AudioSegments
        volume: 0.9
      imageClip:
        artifact: ImageSegments[Image]

3. Validate with Dry Run

Before using real API credits, validate your setup with a dry run (from within your project directory):

renku generate \
  --inputs=./input-template.yaml \
  --blueprint=./my-first-video.yaml \
  --dry-run

The dry run:

• Validates your blueprint and inputs
• Shows the execution plan
• Creates mock artifacts (no API calls)

4. Run Full Generation

When you’re ready, run the full generation:

renku generate \
  --inputs=./input-template.yaml \
  --blueprint=./my-first-video.yaml

Watch as Renku:

1. Generates a narration script using OpenAI
2. Creates audio for each segment using your chosen voice
3. Saves all artifacts to the build director.

5. View the Results

Open the generated content in the viewer:

renku viewer:view --last

This starts a local viewer server and opens your browser to preview the generated content.

Understanding the Output

After generation, your current working directory contains:

{project}/                       # Current working directory
├── builds/                      # GITIGNORED - build data
│   └── movie-{id}/
│       ├── blobs/               # Generated files (audio, images, etc.)
│       ├── manifests/           # Artifact metadata
│       ├── events/              # Execution logs
│       └── runs/                # Execution plans
└── artifacts/                   # GITIGNORED - symlinks to build outputs
    └── movie-{id}/
        ├── Script.txt           # Generated narration script
        ├── Segment_0.mp3        # Audio for segment 0
        ├── Segment_1.mp3        # Audio for segment 1
        └── Segment_2.mp3        # Audio for segment 2

The artifacts/ directory contains human-readable symlinks to your generated content. Use renku list to see all builds in the current project.

Next Steps

You’ve successfully generated your first AI video content with Renku!

Explore More Blueprints

Try other example blueprints by browsing the catalog and creating your own copies:

# See available blueprints
ls ./catalog/blueprints/

# Create a new project from any blueprint
renku new:blueprint my-documentary --using=documentary-talkinghead

Each blueprint you create contains an input-template.yaml that documents the required inputs.

Create a Blueprint from Scratch

You can also create a completely new blueprint without copying from the catalog:

renku new:blueprint my-custom-workflow

This creates a scaffold blueprint with all required sections that you can customize.

Using Claude Code for Blueprint Creation

If you’re using Claude Code or other AI coding agents that support skills, you can install the Renku plugin to get AI-assisted blueprint creation.

Install the Renku plugin:

/install-plugin https://github.com/keremk/renku/tree/main/renku-plugin

Once installed, you can use the create-blueprint skill to have Claude help you design and create blueprints through natural conversation:

/renku-plugin:create-blueprint

The skill guides you through:

• Understanding your video requirements
• Selecting appropriate producers and models
• Creating the blueprint YAML structure
• Setting up prompt producers for AI-driven content
• Validating and testing with dry runs

This is especially useful for complex blueprints with multiple producers and custom prompt logic.

Learn the Workflow

Read the Usage Guide to learn:

• How to edit and iterate on generated content
• Using layer-by-layer generation for cost control
• Browsing available models and producers

Deep Dive

For advanced users:

• CLI Reference - Complete command documentation
• Blueprint Authoring - Create custom workflows

Troubleshooting

Missing API Credentials

Error: OPENAI_API_KEY not found

Solution: Export your API key or add it to a .env file in your workspace.

Blueprint Not Found

Error: Blueprint file not found

Solution: Use the full path to the blueprint file. After renku init, blueprints are in {workspace}/catalog/blueprints/.

Provider Rate Limits

The providers have rate limits that may depend on your tier or how much you loaded your account with. Setting —concurrency to a higher value than 1 will likely trigger these limits. Concurrency will allow you to parallelize requests, but if you hit rate limits, try lowering the concurrency or upgrading your plan with the provider.

Dry Run Works, Real Run Fails

Check that:

1. All required API keys are set
2. Check your provider logs to diagnose issues. Sometimes you may be hitting rate limits or safety filters.
3. Your API accounts have sufficient credits
4. The model names in the inputs file are valid and currently available.

Run renku producers:list --blueprint=<path> to see available models and check for missing tokens.