# How to Use the quickdesign AI Media Generation Plugin: A Complete Guide > Learn to use the quickdesign AI media generation plugin with this comprehensive guide. Connect Claude Code agents to QuickDesign for CLI-based image, video, and ad creation. - Repository: [Anthropic/claude-plugins-community](https://github.com/anthropics/claude-plugins-community) - Tags: how-to-guide - Published: 2026-09-08 --- **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. ```bash 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`](https://github.com/anthropics/claude-plugins-community/blob/main/quickdesign/README.md) (lines 48-62), this command ensures your local environment matches the plugin's requirements before copying [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) and its companion reference files into the Claude Code skills directory. ```bash 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. ```bash export QUICKDESIGN_TOKEN="" quickdesign whoami ``` ## Core Architecture Components ### Claude Code Skill Bundle When you execute `quickdesign init`, the CLI copies [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) from [`quickdesign/skills/quickdesign/SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/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 `. 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`](https://github.com/anthropics/claude-plugins-community/blob/main/quickdesign/skills/quickdesign/models/nano-banana-2.md) for parameter specifics. ```bash 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. ```bash 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. ```bash # 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. ```bash 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. ```bash 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`](https://github.com/anthropics/claude-plugins-community/blob/main/quickdesign/README.md) (lines 97-112) to generate 16 parallel ad concepts from a single product URL. ```bash 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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/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 `, 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`](https://github.com/anthropics/claude-plugins-community/blob/main/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`](https://github.com/anthropics/claude-plugins-community/blob/main/quickdesign/skills/quickdesign/pipelines/ugc-video.md), ensures consistent voice characteristics when stitching multiple AI-generated clips into a cohesive narrative.