ai-media-cli

ai-media-cli

The easiest way to generate AI images, videos, music, and speech from JavaScript / TypeScript.
Use it as a CLI, via npx, or as a library in your own projects.

Powered by Kubeez — a simple, powerful API for AI media generation.

Why ai-media-cli?

• One package for images, videos, music, and speech generation
• Works as a CLI tool, npx command, and TypeScript / JavaScript library
• Simple ai-media-cli login — no config files to create
• Built-in --wait flag to poll until generation completes
• Automatic retry with backoff on server errors and rate limits
• Custom error classes — APIError, TimeoutError for clean error handling
• Table output for models with pricing — or --json for scripting
• Fully typed with TypeScript, 46 tests
• Supports 40+ AI models from top providers (OpenAI, Google, Black Forest Labs, ByteDance, xAI, and more)

Table of Contents

• Quick Start
• Installation
• Authentication
• CLI Commands
• Library Usage
• Available Models & Pricing
• Examples
• Development
• API Documentation
• License

Quick Start

# No install needed — just use npx
npx ai-media-cli login YOUR_API_KEY
npx ai-media-cli generate -p "a cyberpunk cityscape at sunset" -m nano-banana-2 --wait

Get your API key at kubeez.com -> API Keys.

Installation

Global Install (recommended for CLI)

npm install -g ai-media-cli
# or
bun install -g ai-media-cli

Then use anywhere:

ai-media-cli generate -p "a beautiful mountain landscape" -m nano-banana-2 --wait

As a Library

npm install ai-media-cli
# or
bun add ai-media-cli

import { AIImageClient } from "ai-media-cli";

const client = new AIImageClient({ apiKey: "your-key" });

const gen = await client.generateMedia({
  prompt: "a serene Japanese garden in autumn",
  model: "nano-banana-2",
});

const result = await client.pollForCompletion(gen.generation_id);
console.log(result.outputs?.[0]?.url);

Authentication

Option 1: Login command (recommended)

ai-media-cli login YOUR_API_KEY

Saves to ~/.ai-image-cli/config.json with 600 permissions. One-time setup.

ai-media-cli whoami     # show masked key + balance
ai-media-cli logout     # remove saved key

Option 2: Environment variable

export AI_IMAGE_API_KEY=your_api_key_here

Environment variable always takes priority over the config file.

CLI Commands

Authentication

Command	Description
ai-media-cli login <key>	Save API key to ~/.ai-image-cli
ai-media-cli logout	Remove saved key
ai-media-cli whoami	Show masked key and balance

Generation

# List models with pricing table
ai-media-cli models
ai-media-cli models --type image
ai-media-cli models --type video --json

# Generate images
ai-media-cli generate -p "a cute robot painting" -m nano-banana-2 --wait
ai-media-cli generate -p "cinematic landscape" -m nano-banana-2 -a 16:9 --wait
ai-media-cli generate -p "portrait" -m nano-banana-2 -n "blurry, low quality" --wait

# Generate video
ai-media-cli generate -p "ocean waves" -m kling-v2 --type text-to-video --duration 5 --sound --wait

# Image-to-video
ai-media-cli generate -p "camera zoom" -m kling-v2 --type image-to-video --source-urls URL --wait

# Image-to-image
ai-media-cli generate -p "watercolor style" -m 5-lite-image-to-image --type image-to-image --source-urls URL --wait

# Music
ai-media-cli music -p "lo-fi hip hop beat" --instrumental --wait
ai-media-cli music -p "epic orchestral soundtrack" -m V5 --wait

# Text-to-speech
ai-media-cli dialogue -d '[{"text":"Hello!","voice":"Adam"},{"text":"Hi!","voice":"Emily"}]'

# Ad copy
ai-media-cli ad-copy -r https://example.com/ad.png --product-text "Premium headphones" --variants 3

Utilities

ai-media-cli upload -f ./photo.jpg                    # Upload media
ai-media-cli status -i GENERATION_ID --wait           # Check/poll status
ai-media-cli balance                                  # Check credits
ai-media-cli generations --status completed           # List generations

All generate options:

Flag	Description	Default
-p, --prompt	Generation prompt (required)	—
-m, --model	Model (required)	—
-t, --type	text-to-image, image-to-image, text-to-video, image-to-video	text-to-image
-n, --negative-prompt	What to avoid	""
-a, --aspect-ratio	1:1, 16:9, 9:16, etc.	1:1
-d, --duration	Video duration (seconds)	—
-q, --quality	Quality level	—
-s, --seed	Reproducibility seed	0
--sound	Enable audio on video	false
--fixed-lens	Fixed camera lens	false
--source-urls	Source media URLs	—
-w, --wait	Poll until done	false

Full CLI reference: docs/CLI_REFERENCE.md

Library Usage

Basic Setup

import { AIImageClient } from "ai-media-cli";

const client = new AIImageClient({
  apiKey: process.env.AI_IMAGE_API_KEY!,
});

Generate an Image

const gen = await client.generateMedia({
  prompt: "a futuristic city with flying cars",
  model: "nano-banana-2",
  aspect_ratio: "16:9",
  negative_prompt: "blurry, watermark",
});

const result = await client.pollForCompletion(gen.generation_id);
console.log("Image URL:", result.outputs?.[0]?.url);

Generate Video

const video = await client.generateMedia({
  prompt: "timelapse of clouds over mountains",
  model: "kling-v2",
  generation_type: "text-to-video",
  duration: "5",
  sound: true,
});

const result = await client.pollForCompletion(video.generation_id);

Generate Music

const music = await client.generateMusic({
  prompt: "energetic rock anthem",
  instrumental: false,
  model: "V5",
});

const result = await client.pollForCompletion(music.generation_id, "music");

Text-to-Speech

const speech = await client.generateDialogue({
  dialogue: [
    { text: "Welcome to our podcast!", voice: "Adam" },
    { text: "Thanks for having me!", voice: "Emily" },
  ],
  stability: 0.7,
  language_code: "en",
});

Error Handling

import { AIImageClient, APIError, TimeoutError } from "ai-media-cli";

try {
  await client.generateMedia({ prompt: "test", model: "bad" });
} catch (error) {
  if (error instanceof APIError) {
    console.error(`HTTP ${error.statusCode}: ${error.message}`);
    if (error.isRateLimited) console.error("Slow down!");
    if (error.isUnauthorized) console.error("Check your API key");
  }
  if (error instanceof TimeoutError) {
    console.error(`Timed out after ${error.attempts} polls`);
  }
}

All Exports

import { AIImageClient, APIError, ConfigError, TimeoutError } from "ai-media-cli";
import type {
  ClientOptions,
  GenerateMediaRequest,
  GenerateMusicRequest,
  GenerateDialogueRequest,
  GenerateAdCopyRequest,
  GenerateResponse,
  DialogueLine,
  GenerationStatus,
  GenerationOutput,
  BalanceResponse,
  UploadResponse,
  GenerationsListParams,
  ModelsResponse,
  Model,
} from "ai-media-cli";

Full library guide: docs/LIBRARY_USAGE.md

Available Models & Pricing

Kubeez uses a credit-based system. Each model has a different cost per generation.

90+ models across 8 providers. Highlights:

Image (27 models, from 3 credits)

Model	Provider	Credits	Speed
Z-image	Alibaba	3	~4s
nano-banana	Google	7	~10s
imagen-4-fast	Google	7	~30s
seedream-v4-5	ByteDance	9	~21s
flux-2-1K	Black Forest Labs	10	~32s
gpt-1.5-image-medium	OpenAI	10	~34s
imagen-4	Google	13	~33s
nano-banana-2	Google	14	~42s
grok-text-to-image	xAI	14	~30s
gpt-1.5-image-high	OpenAI	32	~30s

Video (40+ models, from 12 credits)

Model	Provider	Credits	Details
seedance-1-5-pro-480p-4s	ByteDance	12	4s 480p
kling-2-6-text-to-video-5s	Kuaishou	90	5s
veo3-1-fast-text-to-video	Google	99	Fast
kling-3-0-pro	Kuaishou	125	Pro quality
kling-2-6-text-to-video-5s-audio	Kuaishou	175	5s + audio
veo3-1-text-to-video	Google	390	High quality

Music & Speech

Model	Credits	Features
V5 (default)	19	Vocals + instrumental
V4_5PLUS	19	Vocals + instrumental
suno-lyrics-generation	2	Lyrics only
text-to-dialogue-v3	21	Multi-speaker TTS (ElevenLabs)

Plans

Plan	Best For	Savings
Free Trial	Testing (free credits on signup)	—
Starter	Light experimentation	4% vs. PAYG
Pro	Full experience (most popular)	~20% vs. PAYG
Powerhouse	High-volume production	~44% vs. PAYG

Yearly billing saves an additional ~16%. See kubeez.com/pricing.

# Check real-time model pricing
ai-media-cli models

# Check your balance
ai-media-cli balance

Full models list: docs/MODELS.md

Examples

Batch generate with different seeds

for i in 1 2 3 4 5; do
  ai-media-cli generate -p "abstract art variation $i" -m nano-banana-2 --seed $i --wait
done

Upload and transform

URL=$(ai-media-cli upload -f photo.jpg | jq -r '.url')
ai-media-cli generate -p "anime style" -m 5-lite-image-to-image --type image-to-image --source-urls "$URL" --wait

Express API

import express from "express";
import { AIImageClient } from "ai-media-cli";

const app = express();
const client = new AIImageClient({ apiKey: process.env.AI_IMAGE_API_KEY! });

app.use(express.json());

app.post("/api/generate", async (req, res) => {
  const { prompt, model = "nano-banana-2" } = req.body;
  const gen = await client.generateMedia({ prompt, model });
  const result = await client.pollForCompletion(gen.generation_id);
  res.json(result);
});

app.listen(3000);

Node.js script

import { AIImageClient } from "ai-media-cli";

const client = new AIImageClient({ apiKey: process.env.AI_IMAGE_API_KEY! });

const gen = await client.generateMedia({
  prompt: "tech company banner, gradient purple to blue, minimalist",
  model: "nano-banana-2",
  aspect_ratio: "16:9",
});

const result = await client.pollForCompletion(gen.generation_id);
if (result.status === "completed") {
  console.log("Ready:", result.outputs?.[0]?.url);
}

Development

git clone https://github.com/sebyx07/js-ai-image-cli.git
cd js-ai-image-cli
bun install

bun run dev -- --help          # Run CLI
bun test                       # 46 tests
bun run lint                   # Biome linting
bun run build                  # TypeScript build

API Documentation

• Kubeez API Docs — full OpenAPI spec
• API Keys — manage your keys
• Pricing — plans and credit packages

License

MIT