Image Generation Skill
This skill guides the implementation of image generation functionality using the z-ai-web-dev-sdk package and CLI tool, enabling creation of high-quality images from text descriptions.
Skills Path
Skill Location: {project_path}/skills/image-generation
this skill is located at above path in your project.
Reference Scripts: Example test scripts are available in the {Skill Location}/scripts/ directory for quick testing and reference. See {Skill Location}/scripts/image-generation.ts for a working example.
Overview
Image Generation allows you to build applications that create visual content from text prompts using AI models, enabling creative workflows, design automation, and visual content production.
IMPORTANT: z-ai-web-dev-sdk MUST be used in backend code only. Never use it in client-side code.
Prerequisites
The z-ai-web-dev-sdk package is already installed. Import it as shown in the examples below.
Basic Image Generation
Simple Image Creation
javascript
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
async function generateImage(prompt, outputPath) {
const zai = await ZAI.create();
const response = await zai.images.generations.create({
prompt: prompt,
size: '1024x1024'
});
const imageBase64 = response.data[0].base64;
// Save image
const buffer = Buffer.from(imageBase64, 'base64');
fs.writeFileSync(outputPath, buffer);
console.log(`Image saved to ${outputPath}`);
return outputPath;
}
// Usage
await generateImage(
'A cute cat playing in the garden',
'./cat_image.png'
);
Multiple Image Sizes
javascript
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
// Supported sizes
const SUPPORTED_SIZES = [
'1024x1024', // Square
'768x1344', // Portrait
'864x1152', // Portrait
'1344x768', // Landscape
'1152x864', // Landscape
'1440x720', // Wide landscape
'720x1440' // Tall portrait
];
async function generateImageWithSize(prompt, size, outputPath) {
if (!SUPPORTED_SIZES.includes(size)) {
throw new Error(`Unsupported size: ${size}. Use one of: ${SUPPORTED_SIZES.join(', ')}`);
}
const zai = await ZAI.create();
const response = await zai.images.generations.create({
prompt: prompt,
size: size
});
const imageBase64 = response.data[0].base64;
const buffer = Buffer.from(imageBase64, 'base64');
fs.writeFileSync(outputPath, buffer);
return {
path: outputPath,
size: size,
fileSize: buffer.length
};
}
// Usage - Different sizes
await generateImageWithSize(
'A beautiful landscape',
'1344x768',
'./landscape.png'
);
await generateImageWithSize(
'A portrait of a person',
'768x1344',
'./portrait.png'
);
CLI Tool Usage
The z-ai CLI tool provides a convenient way to generate images directly from the command line.
Basic CLI Usage
bash
# Generate image with full options
z-ai image --prompt "A beautiful landscape" --output "./image.png"
# Short form
z-ai image -p "A cute cat" -o "./cat.png"
# Specify size
z-ai image -p "A sunset" -o "./sunset.png" -s 1344x768
# Portrait orientation
z-ai image -p "A portrait" -o "./portrait.png" -s 768x1344
CLI Use Cases
bash
# Website hero image
z-ai image -p "Modern tech office with diverse team collaborating" -o "./hero.png" -s 1440x720
# Product image
z-ai image -p "Sleek smartphone on minimalist desk, professional product photography" -o "./product.png" -s 1024x1024
# Blog post illustration
z-ai image -p "Abstract visualization of data flowing through networks" -o "./blog_header.png" -s 1344x768
# Social media content
z-ai image -p "Vibrant illustration of community connection" -o "./social.png" -s 1024x1024
# Website favicon/logo
z-ai image -p "Simple geometric logo with blue gradient, minimal design" -o "./logo.png" -s 1024x1024
# Background pattern
z-ai image -p "Subtle geometric pattern, pastel colors, website background" -o "./bg_pattern.png" -s 1440x720
Advanced Use Cases
Batch Image Generation
javascript
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
import path from 'path';
async function generateImageBatch(prompts, outputDir, size = '1024x1024') {
const zai = await ZAI.create();
// Ensure output directory exists
if (!fs.existsSync(outputDir)) {
fs.mkdirSync(outputDir, { recursive: true });
}
const results = [];
for (let i = 0; i < prompts.length; i++) {
try {
const prompt = prompts[i];
const filename = `image_${i + 1}.png`;
const outputPath = path.join(outputDir, filename);
const response = await zai.images.generations.create({
prompt: prompt,
size: size
});
const imageBase64 = response.data[0].base64;
const buffer = Buffer.from(imageBase64, 'base64');
fs.writeFileSync(outputPath, buffer);
results.push({
success: true,
prompt: prompt,
path: outputPath,
size: buffer.length
});
console.log(`✓ Generated: ${filename}`);
} catch (error) {
results.push({
success: false,
prompt: prompts[i],
error: error.message
});
console.error(`✗ Failed: ${prompts[i]} - ${error.message}`);
}
}
return results;
}
// Usage
const prompts = [
'A serene mountain landscape at sunset',
'A futuristic city with flying cars',
'An underwater coral reef teeming with life'
];
const results = await generateImageBatch(prompts, './generated-images');
console.log(`Generated ${results.filter(r => r.success).length} images`);
Image Generation Service
javascript
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
import path from 'path';
import crypto from 'crypto';
class ImageGenerationService {
constructor(outputDir = './generated-images') {
this.outputDir = outputDir;
this.zai = null;
this.cache = new Map();
}
async initialize() {
this.zai = await ZAI.create();
if (!fs.existsSync(this.outputDir)) {
fs.mkdirSync(this.outputDir, { recursive: true });
}
}
generateCacheKey(prompt, size) {
return crypto
.createHash('md5')
.update(`${prompt}-${size}`)
.digest('hex');
}
async generate(prompt, options = {}) {
const {
size = '1024x1024',
useCache = true,
filename = null
} = options;
// Check cache
const cacheKey = this.generateCacheKey(prompt, size);
if (useCache && this.cache.has(cacheKey)) {
const cachedPath = this.cache.get(cacheKey);
if (fs.existsSync(cachedPath)) {
return {
path: cachedPath,
cached: true,
prompt: prompt,
size: size
};
}
}
// Generate new image
const response = await this.zai.images.generations.create({
prompt: prompt,
size: size
});
const imageBase64 = response.data[0].base64;
const buffer = Buffer.from(imageBase64, 'base64');
// Determine output path
const outputFilename = filename || `${cacheKey}.png`;
const outputPath = path.join(this.outputDir, outputFilename);
fs.writeFileSync(outputPath, buffer);
// Cache result
if (useCache) {
this.cache.set(cacheKey, outputPath);
}
return {
path: outputPath,
cached: false,
prompt: prompt,
size: size,
fileSize: buffer.length
};
}
clearCache() {
this.cache.clear();
}
getCacheSize() {
return this.cache.size;
}
}
// Usage
const service = new ImageGenerationService();
await service.initialize();
const result = await service.generate(
'A modern office space',
{ size: '1440x720' }
);
console.log('Generated:', result.path);
Website Asset Generator
bash
# Using CLI for quick website asset generation
z-ai image -p "Modern tech hero banner, blue gradient" -o "./assets/hero.png" -s 1440x720
z-ai image -p "Team collaboration illustration" -o "./assets/team.png" -s 1344x768
z-ai image -p "Simple geometric logo" -o "./assets/logo.png" -s 1024x1024
Best Practices
1. Effective Prompt Engineering
javascript
function buildEffectivePrompt(subject, style, details = []) {
const components = [
subject,
style,
...details,
'high quality',
'detailed'
];
return components.filter(Boolean).join(', ');
}
// Usage
const prompt = buildEffectivePrompt(
'mountain landscape',
'oil painting style',
['sunset lighting', 'dramatic clouds', 'reflection in lake']
);
// Result: "mountain landscape, oil painting style, sunset lighting, dramatic clouds, reflection in lake, high quality, detailed"
2. Size Selection Helper
javascript
function selectOptimalSize(purpose) {
const sizeMap = {
'hero-banner': '1440x720',
'blog-header': '1344x768',
'social-square': '1024x1024',
'portrait': '768x1344',
'product': '1024x1024',
'landscape': '1344x768',
'mobile-banner': '720x1440',
'thumbnail': '1024x1024'
};
return sizeMap[purpose] || '1024x1024';
}
// Usage
const size = selectOptimalSize('hero-banner');
await generateImage('website hero image', size, './hero.png');
3. Error Handling
javascript
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
async function safeGenerateImage(prompt, size, outputPath, retries = 3) {
let lastError;
for (let attempt = 1; attempt <= retries; attempt++) {
try {
const zai = await ZAI.create();
const response = await zai.images.generations.create({
prompt: prompt,
size: size
});
if (!response.data || !response.data[0] || !response.data[0].base64) {
throw new Error('Invalid response from image generation API');
}
const imageBase64 = response.data[0].base64;
const buffer = Buffer.from(imageBase64, 'base64');
fs.writeFileSync(outputPath, buffer);
return {
success: true,
path: outputPath,
attempts: attempt
};
} catch (error) {
lastError = error;
console.error(`Attempt ${attempt} failed:`, error.message);
if (attempt < retries) {
// Wait before retry (exponential backoff)
await new Promise(resolve => setTimeout(resolve, 1000 * attempt));
}
}
}
return {
success: false,
error: lastError.message,
attempts: retries
};
}
Common Use Cases
- Website Design: Generate hero images, backgrounds, and visual assets
- Marketing Materials: Create social media graphics and promotional images
- Product Visualization: Generate product mockups and variations
- Content Creation: Produce blog post illustrations and thumbnails
- Brand Assets: Create logos, icons, and brand imagery
- UI/UX Design: Generate interface elements and illustrations
- Game Development: Create concept art and game assets
- E-commerce: Generate product images and lifestyle shots
Integration Examples
Express.js API Endpoint
javascript
import express from 'express';
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
import path from 'path';
const app = express();
app.use(express.json());
app.use('/images', express.static('generated-images'));
let zaiInstance;
const outputDir = './generated-images';
async function initZAI() {
zaiInstance = await ZAI.create();
if (!fs.existsSync(outputDir)) {
fs.mkdirSync(outputDir, { recursive: true });
}
}
app.post('/api/generate-image', async (req, res) => {
try {
const { prompt, size = '1024x1024' } = req.body;
if (!prompt) {
return res.status(400).json({ error: 'Prompt is required' });
}
const response = await zaiInstance.images.generations.create({
prompt: prompt,
size: size
});