How to Use the quickdesign AI Media Generation Plugin: A Complete Guide

The quickdesign AI media generation plugin connects Claude Code agents to the QuickDesign cloud platform, enabling CLI-based generation of images, videos, ads, and post-processing through the npm package @quickdesign/cli and a Claude Code skill bundle.

The quickdesign plugin is an open-source tool maintained in the anthropics/claude-plugins-community repository that bridges local development environments with cloud-based AI media services. By installing the CLI and bootstrapping the Claude Code skill system, you can generate production-ready visuals, UGC videos, and advertising assets directly from your terminal without managing complex API integrations.

Installation and Initial Setup

Install the CLI Binary

The primary interface for the quickdesign AI media generation plugin is the @quickdesign/cli npm package. This executable handles all HTTP communication with the QuickDesign BFF, manages authentication, and polls long-running generation jobs.

npm install -g @quickdesign/cli

Bootstrap the Environment

Running quickdesign init performs three critical operations: it checks for system dependencies like ffmpeg, copies the Claude Code skill bundle to ~/.claude/skills/quickdesign/, and initiates the OAuth authentication flow. According to the source code in quickdesign/README.md (lines 48-62), this command ensures your local environment matches the plugin's requirements before copying SKILL.md and its companion reference files into the Claude Code skills directory.

quickdesign init

Authentication Methods

The plugin supports two authentication modes. Interactive users run quickdesign login to trigger a browser-based OAuth flow that stores access and refresh tokens in ~/.config/quickdesign/auth.json with 0600 permissions. For CI/CD environments, override the token by setting the QUICKDESIGN_TOKEN environment variable with a valid Supabase JWT.

export QUICKDESIGN_TOKEN="<supabase-jwt>"
quickdesign whoami

Core Architecture Components

Claude Code Skill Bundle

When you execute quickdesign init, the CLI copies SKILL.md from quickdesign/skills/quickdesign/SKILL.md into your local skills directory. This file contains the cardinal rules (lines 24-65) that govern how Claude Code agents interact with the plugin, including mandatory @ImageN reference labels, voice continuity preservation, and cost-confirmation gates for credit-heavy operations.

Dynamic Model Registry

Unlike static plugins, quickdesign queries available models at runtime using commands like quickdesign video models and quickdesign image models. The system never hard-codes model names; instead, default selections such as Seedance 2.0 R2V for UGC video generation are defined in the skill's model cards located at quickdesign/skills/quickdesign/models/seedance-2.0-r2v.md.

Job Lifecycle Management

All generation commands follow an asynchronous job pattern. When you trigger a creation task, the CLI returns a request_id immediately. Use the --wait flag to block and poll until completion, or capture the ID for later retrieval with quickdesign ... wait <id>. This polling-based architecture eliminates the need for inbound webhooks, making the plugin safe for headless CI environments and firewalled networks.

Generating AI Media Content

Creating Images with Nano Banana

The plugin supports multiple image models including Nano Banana 2 and GPT-Image variants. Specify your model using the --model flag and reference the model card at quickdesign/skills/quickdesign/models/nano-banana-2.md for parameter specifics.

quickdesign image generate \
  --prompt "studio photo of a silver bracelet on white background" \
  --model nano-banana-2 \
  --wait -o ./bracelet.jpg

Generating UGC Videos

For user-generated content workflows, the Seedance 2.0 R2V provider supports image-to-video generation with voice continuity. Use --reference-image to pass visual assets and structure prompts using the @ImageN syntax enforced by the skill's cardinal rules.

quickdesign video generate --provider seedance \
  --reference-image https://cdn.example.com/bracelet.jpg \
  --reference-image https://cdn.example.com/model.jpg \
  --prompt "@Image2 in @Image3, holds @Image1 toward camera. She says: 'Check out this sleek bracelet!' No music score. No subtitles or on-screen text." \
  --aspect-ratio 9:16 --duration 5 --wait -o ./catwalk.mp4

Multi-Segment Video Workflows

For complex narratives requiring shot continuity, chain multiple generation commands using the request ID. Extract audio from the first segment using ffmpeg, then reference that audio file in subsequent parallel generations to maintain consistent voice characteristics across scenes.

# Start segment 1 and capture ID

JOB1=$(quickdesign video generate --provider seedance \
       --reference-image seg1.png --prompt "...first segment..." \
       --duration 12 --wait | jq -r '.request_id')

# Extract audio for continuity

ffmpeg -y -i seg1.mp4 -vn -acodec libmp3lame seg1-audio.mp3

# Generate remaining segments in parallel

quickdesign video generate --provider seedance \
  --reference-image seg2.png --reference-audio seg1-audio.mp3 \
  --duration 12 --prompt "...second segment..." -o seg2.mp4 &

quickdesign video generate --provider seedance \
  --reference-image seg3.png --reference-audio seg1-audio.mp3 \
  --duration 12 --prompt "...third segment..." -o seg3.mp4 &
wait

Post-Processing and Advanced Features

Adding Karaoke-Style Subtitles

The plugin provides dedicated post-processing endpoints for video enhancement. The quickdesign video subtitle command accepts TikTok-style formatting and automatic language detection.

quickdesign video subtitle ./final.mp4 \
  --style tiktok --language en \
  -o ./final-subbed.mp4 --wait

Video Upscaling

Enhance resolution using providers like Topaz or ByteDance. The --factor parameter controls the upscale multiplier.

quickdesign upscale --video ./lowres.mp4 --provider topaz \
  --factor 2 --wait -o ./highres.mp4

Smart Ad Creator (Advantage+)

The advantage-plus pipeline leverages the Brand DNA and Spy Brands features documented in quickdesign/README.md (lines 97-112) to generate 16 parallel ad concepts from a single product URL.

quickdesign ad-creator advantage-plus \
  --product-url https://kizik.com/products/bowen-black \
  --wait -o ./ads
ls ./ads/   # Contains one .jpg per generated concept

Understanding the Skill System

The Claude Code integration relies on structured documentation within quickdesign/skills/quickdesign/. The SKILL.md file serves as the agent's instruction manual, while subdirectories contain:

• Model Cards: Technical specifications for Seedance 2.0 R2V and Nano Banana 2
• Pipeline Guides: Detailed workflows like ugc-video.md for multi-segment production
• Reference Documentation: Rules for voice continuity and subtitle placement

Agents read these files to construct valid commands without requiring users to memorize API parameters. The cardinal rules in SKILL.md lines 24-65 specifically require cost confirmation before executing credit-intensive operations, protecting against accidental spend.

Summary

• The quickdesign AI media generation plugin bridges Claude Code and the QuickDesign cloud via the @quickdesign/cli npm package.
• Authentication supports OAuth for interactive use and QUICKDESIGN_TOKEN environment variables for CI pipelines.
• Job lifecycle uses asynchronous polling with request IDs rather than webhooks, enabling safe headless operation.
• Media generation supports images (Nano Banana 2), videos (Seedance 2.0 R2V), and parallel ad creation (Advantage+).
• Post-processing includes karaoke subtitles and Topaz-powered upscaling.
• Skill integration through ~/.claude/skills/quickdesign/SKILL.md enforces best practices like @ImageN labeling and cost gates.

Frequently Asked Questions

How do I install the quickdesign plugin for Claude Code?

Install the global npm package @quickdesign/cli, then run quickdesign init to copy the skill files to ~/.claude/skills/quickdesign/ and authenticate. The initialization process verifies ffmpeg availability and sets up the OAuth token store at ~/.config/quickdesign/auth.json.

Can I use the quickdesign plugin in CI/CD environments without interactive login?

Yes. Set the QUICKDESIGN_TOKEN environment variable to a valid Supabase JWT before running CLI commands. This bypasses the browser-based OAuth flow required by quickdesign login, making it suitable for GitHub Actions or other automated pipelines.

What is the difference between --wait and manual job polling?

The --wait flag blocks the CLI process and automatically polls the QuickDesign BFF until the job completes, writing the final file to the -o destination. Without --wait, the command returns immediately with a request_id that you can later check using quickdesign ... wait <id>, allowing you to free up the terminal or run multiple jobs in parallel.

How does the plugin ensure voice continuity across video segments?

The skill system documented in SKILL.md requires extracting audio from initial segments using ffmpeg and passing it to subsequent generations via the --reference-audio parameter. This technique, detailed in quickdesign/skills/quickdesign/pipelines/ugc-video.md, ensures consistent voice characteristics when stitching multiple AI-generated clips into a cohesive narrative.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}