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