mcpField
G
gen-ai-use

gen-ai-use

github.com/picsartCreative & media6367 installsUpdated 1d ago
Repository

About gen-ai-use

gen-ai-use is a usage guide for the Picsart `gen-ai` CLI, for people generating media through the Picsart API from a terminal. It covers image, video, and audio generation, along with model lookup, batch jobs, and Drive file operations.

Key features

  1. 01Generate images, videos, and audio
  2. 02Run image processing operations
  3. 03Check model capabilities and pricing
  4. 04Run and resume batch generation
  5. 05Manage Picsart Drive files

Use cases

  1. 01Generate images or videos from a terminal
  2. 02Run batch jobs and resume generation
  3. 03Upload or download Picsart Drive files

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/picsart/gen-ai-skills --skill gen-ai-use

After installing, type/gen-ai-usein Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

references/
ADVANCED.md
BATCH.md
COMPLETIONS.md
DRIVE.md
EXAMPLES.md
FLAGS.md
TROUBLESHOOTING.md

Details

From the project README

gen-ai CLI — Usage Guide

The gen-ai CLI generates AI images, videos, and audio from the terminal via the Picsart API.

When to Use

See the description above.

Prerequisites

Picsart gen-ai CLI installed and authenticated (gen-ai login). Note that gen-ai whoami only reads cached credentials from disk and reports "✓ Authenticated" if a token file exists with the right shape — it doesn't check expiry and makes no network call, so it succeeding is not proof that a subsequent network-dependent command will succeed.

How to Run

Use the agent's terminal tool to invoke gen-ai commands as described in the Procedure below.

Quick Reference

  • Auth: login, logout, whoami
  • Generation: generate, remove-bg, change-bg, enhance, vectorize, redo, extend
  • Models / pricing: models, models info, models compare, pricing, credits, validate
  • Batch: batch run, batch status, batch resume
  • Drive: upload, upload-to-drive, download, list
  • Config: config get | set | list | keys | unset
  • History: history, history last, history files, history clear
  • Utilities: completion, update

Run gen-ai <command> --help for full flag details, or see references/FLAGS.md.

Procedure

See sections below for the detailed walkthrough.

Pitfalls

  • Stale model ID — using a name from memory that's been renamed/removed → run gen-ai models first or gen-ai validate -m <id>.
  • Passing --image to a non-i2v video model — it's silently ignored, not auto-mapped. Confirm with gen-ai models info <id>.
  • Forgetting --no-input in CI — the CLI sits waiting for an interactive prompt and the job times out. Always pair --script (or --no-input) with non-TTY contexts.
  • Mixing --multi and --batch — they're mutually exclusive --input-dir modes; pick one.

Verification

Run gen-ai whoami to confirm authentication, then re-run the failed command with --debug. If the command still fails, check the error type before assuming it's a login problem: AuthError ("Not authenticated...") means credentials are genuinely bad and gen-ai login is the fix; NetworkError (message names a transport failure like "fetch failed", or a proxy/connectivity hint) means the CLI's process can't reach the network — re-running login won't help, restoring/escalating network access will.

Where to look

When NOT to use

  • SDK-level integration questions → consult the @picsart/ai-sdk reference / specs/ source
  • Picsart web miniapp or mobile flows → unrelated
  • New backend models that aren't in the catalog yet → backend MR first; CLI picks them up automatically once they ship in @picsart/ai-sdk

Install & auth

# Signed binary (no Node required) — recommended
curl -fsSL https://picsart.com/gen-ai-cli/install.sh | bash

# Or via npm (requires Node 22+)
npm install -g @picsart/gen-ai

gen-ai login     # OAuth browser flow
gen-ai whoami    # verify

Generate

# Interactive wizard
gen-ai generate

# Image, fully specified
gen-ai generate -m flux-2-pro -p "a sunset over mountains" -s

# Image-to-image
gen-ai generate -m gemini-3.1-flash-image -i ~/photo.jpg -p "make it watercolor"

# Text-to-video
gen-ai generate -m kling-v3-pro -p "a cat playing piano" --ar 16:9

# Image-to-video (--image is auto-mapped to startFrame for i2v models)
gen-ai generate -m veo-3.1 -i ~/photo.jpg -p "camera zooms in" -d 5

Image operations

gen-ai remove-bg -i photo.jpg
gen-ai change-bg -i photo.jpg -p "tropical beach sunset"
gen-ai enhance   -i photo.jpg                       # upscale / enhance
gen-ai vectorize -i logo.png                        # raster → SVG

All operation commands accept the same output flags as generate (--download, --save-to-drive, --drive-folder, --open, --clipboard, --json, --quiet, etc.). See references/FLAGS.md.

Browse models, check pricing

Model IDs change as new versions ship — always check the live catalog:

gen-ai models                       # list (filter --mode, --provider)
gen-ai models info <id>             # capabilities, inputs, aspect ratios
gen-ai models compare <a> <b>       # side-by-side
gen-ai pricing <model-id>           # credit cost
gen-ai credits                      # remaining balance

Important defaults

  • Drive auto-save — results save to Picsart Drive in folder gen-ai-cli by default. Disable with --no-save-to-drive; use --drive-folder NAME for a custom folder.
  • startFrame mapping — for i2v models (VEO, Kling i2v, Wan, Luma, Seedance, Runway), -i / --image is auto-mapped to ctx.startFrame.
  • Script mode — --script = --silent --quiet --json, the right combo for piping or CI.
  • CI mode — pass --no-input to fail fast instead of hanging on interactive prompts.

When to reach for the reference files

Comments

Markdown supported