Image Edit Skill
This skill guides the implementation of image editing and modification functionality using the z-ai-web-dev-sdk package and CLI tool, enabling intelligent transformation and editing of images based on text descriptions.
Skills Path
Skill Location: {project_path}/skills/image-edit
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-edit.ts for a working example.
Overview
Image Edit allows you to build applications that modify, transform, and enhance existing images using AI models. Perfect for redesigning assets, creating variations, improving visual content, and transforming images based on textual descriptions.
IMPORTANT: z-ai-web-dev-sdk MUST be used in backend code only. Never use it in client-side code.
SDK API Method
The image editing functionality uses the following API method:
javascript
await zai.images.generations.edit({
prompt: string, // Required: Description of the edit to apply
images: [{ url: string }], // Required: Array with image URL or base64 data URL
size?: string, // Optional: Output size (default: '1024x1024')
model?: string // Optional: Model name
})
Important: The images parameter must be an array of objects with a url property, not a plain string.
API Endpoint: POST /images/generations/edit
Returns: ImageGenerationResponse with base64 encoded edited image
Prerequisites
The z-ai-web-dev-sdk package is already installed. Import it as shown in the examples below.
Basic Image Editing
Simple Image Transformation
javascript
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
async function editImage(imageSource, editPrompt, outputPath, size = '1024x1024') {
const zai = await ZAI.create();
const response = await zai.images.generations.edit({
prompt: editPrompt,
images: [{ url: imageSource }], // Array of objects with url property
size: size
});
const imageBase64 = response.data[0].base64;
// Save edited image
const buffer = Buffer.from(imageBase64, 'base64');
fs.writeFileSync(outputPath, buffer);
console.log(`Edited image saved to ${outputPath}`);
return outputPath;
}
// Usage - Using remote image URL
await editImage(
'https://example.com/landscape.jpg',
'Transform this landscape into a night scene with stars and moon',
'./landscape_night.png'
);
// Usage - Using local image converted to base64
import { readFileSync } from 'fs';
const imageBuffer = readFileSync('./photo.jpg');
const base64Image = imageBuffer.toString('base64');
const dataUrl = `data:image/jpeg;base64,${base64Image}`;
await editImage(
dataUrl,
'Change the cat to a dog, keep everything else the same',
'./dog_version.png'
);
Create Image Variations
javascript
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
async function createVariation(imageSource, baseDescription, variation, outputPath, size = '1024x1024') {
const zai = await ZAI.create();
// Combine base description with variation request
const prompt = `${baseDescription}, ${variation}`;
const response = await zai.images.generations.edit({
prompt: prompt,
images: [{ url: imageSource }],
size: size
});
const imageBase64 = response.data[0].base64;
const buffer = Buffer.from(imageBase64, 'base64');
fs.writeFileSync(outputPath, buffer);
return {
path: outputPath,
prompt: prompt,
variation: variation
};
}
// Usage - Create variations from original image
await createVariation(
'https://example.com/headshot.jpg',
'Professional headshot photo',
'with blue background instead of gray',
'./headshot_blue.png'
);
await createVariation(
'./smartphone.png',
'Product photo of smartphone',
'on wooden table instead of white background',
'./product_wood.png'
);
Multiple Image Sizes for Editing
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 editImageWithSize(imageSource, editPrompt, 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.edit({
prompt: editPrompt,
images: [{ url: imageSource }],
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 - Edit with different aspect ratios
await editImageWithSize(
'./logo.png',
'Redesign the logo to be more modern and minimalist',
'1024x1024',
'./logo_redesigned.png'
);
await editImageWithSize(
'https://example.com/portrait.jpg',
'Transform the portrait to landscape orientation, sunset lighting',
'1344x768',
'./portrait_landscape.png'
);
CLI Tool Usage
The z-ai CLI tool provides a convenient way to edit images directly from the command line.
Basic CLI Usage
bash
# Edit image with full options
z-ai image-edit --prompt "Change the background to sunset colors" --image "./photo.png" --output "./edited.png"
# Short form
z-ai image-edit -p "Make it darker and moodier" -i "./original.jpg" -o "./moody.png"
# Specify output size
z-ai image-edit -p "Redesign in modern style" -i "./design.png" -o "./modern.png" -s 1344x768
# Using remote image URL
z-ai image-edit -p "Convert to landscape orientation" -i "https://example.com/photo.png" -o "./landscape.png" -s 1344x768
CLI Parameters
--prompt, -p: Required - Description of the edit to apply--image, -i: Required - Original image URL or local file path--output, -o: Required - Output image file path (PNG format)--size, -s: Optional - Image size, default is 1024x1024--help, -h: Optional - Display help information
Supported Sizes
1024x1024, 768x1344, 864x1152, 1344x768, 1152x864, 1440x720, 720x1440
CLI Use Cases for Image Editing
bash
# Redesign existing asset
z-ai image-edit -p "Redesign the logo with gradients and modern styling" -i "./logo.png" -o "./logo_v2.png" -s 1024x1024
# Change color scheme
z-ai image-edit -p "Change color scheme to blue and white, professional style" -i "./original.png" -o "./recolored.png" -s 1440x720
# Style transformation
z-ai image-edit -p "Transform to oil painting style, vibrant colors" -i "./photo.jpg" -o "./oil_painting.png" -s 1152x864
# Background replacement
z-ai image-edit -p "Replace background with modern office setting" -i "./portrait.png" -o "./new_background.png" -s 1344x768
# Lighting adjustment
z-ai image-edit -p "Adjust to golden hour lighting, warm tones" -i "./landscape.jpg" -o "./golden_hour.png" -s 1024x1024
# Element modification
z-ai image-edit -p "Replace the red car with a blue motorcycle" -i "./scene.png" -o "./modified.png" -s 1344x768
# Mood transformation
z-ai image-edit -p "Transform to dark moody atmosphere with dramatic lighting" -i "./bright.jpg" -o "./moody.png" -s 1440x720
# Using remote image URL
z-ai image-edit -p "Add a hat to the person" -i "https://example.com/photo.png" -o "./result.png" -s 1024x1024
Advanced Use Cases
Batch Image Editing
javascript
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
import path from 'path';
async function batchEditImages(editInstructions, 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 < editInstructions.length; i++) {
try {
const instruction = editInstructions[i];
const filename = `edited_${i + 1}.png`;
const outputPath = path.join(outputDir, filename);
const response = await zai.images.generations.edit({
prompt: instruction.prompt,
images: [{ url: instruction.imageSource }],
size: size
});
const imageBase64 = response.data[0].base64;
const buffer = Buffer.from(imageBase64, 'base64');
fs.writeFileSync(outputPath, buffer);
results.push({
success: true,
instruction: instruction.prompt,
path: outputPath,
size: buffer.length
});
console.log(`✓ Edited: ${filename}`);
} catch (error) {
results.push({
success: false,
instruction: editInstructions[i].prompt,
error: error.message
});
console.error(`✗ Failed: ${editInstructions[i].prompt} - ${error.message}`);
}
}
return results;
}
// Usage - Create multiple variations from the same image
const editInstructions = [
{
imageSource: './original.jpg',
prompt: 'Change background to blue gradient'
},
{
imageSource: './original.jpg',
prompt: 'Transform to black and white, high contrast'
},
{
imageSource: './original.jpg',
prompt: 'Add sunset lighting effects'
}
];
const results = await batchEditImages(editInstructions, './edited-images');
console.log(`Edited ${results.filter(r => r.success).length} images`);
Image Editing Service
javascript
import ZAI from 'z-ai-web-dev-sdk';
import fs from 'fs';
import path from 'path';
import crypto from 'crypto';
class ImageEditingService {
constructor(outputDir = './edited-images') {
this.outputDir = outputDir;
this.zai = null;
this.editHistory = [];
}
async initialize() {
this.zai = await ZAI.create();
if (!fs.existsSync(this.outputDir)) {
fs.mkdirSync(this.outputDir, { recursive: true });
}
}
generateFilename(editPrompt) {
const hash = crypto
.createHash('md5')
.update(`${editPrompt}-${Date.now()}`)
.digest('hex')
.substring(0, 8);
return `edited_${hash}.png`;
}
async edit(imageSource, editPrompt, options = {}) {
const {
size = '1024x1024',
saveToHistory = true,
filename = null
} = options;
const response = await this.zai.images.generations.edit({
prompt: editPrompt,
images: [{ url: imageSource }],
size: size
});
const imageBase64 = response.data[0].base64;
const buffer = Buffer.from(imageBase64, 'base64');
// Determine output path
const outputFilename = filename || this.generateFilename(editPrompt);
const outputPath = path.join(this.outputDir, outputFilename);
fs.writeFileSync(outputPath, buffer);
const result = {
path: outputPath,
imageSource: imageSource,
editPrompt: editPrompt,
size: size,
fileSize: buffer.length,
timestamp: new Date().toISOString()
};
// Save to history
if (saveToHistory) {
this.editHistory.push(result);
}
return result;
}
async createVariations(imageSource, basePrompt, variations, options = {}) {
const results = [];
for (const variation of variations) {
const fullPrompt = `${basePrompt}, ${variation}`;
const result = await this.edit(imageSource, fullPrompt, options);
result.variation = variation;
results.push(result);
}
return results;
}
getEditHistory() {
return this.editHistory;
}
clearHistory() {
this.editHistory = [];
}
}
// Usage
const service = new ImageEditingService();
await service.initialize();
// Single edit
const edited = await service.edit(
'./original.jpg',
'Transform to watercolor painting style',
{ size: '1024x1024' }
);