The ViucraftClient provides methods for uploading, deleting, inspecting, and listing images. All methods return promises and include automatic retry on rate-limit (429) responses.
uploadImage(file, metadata?)
Upload an image to VIUCraft.
| Parameter | Type | Required | Description |
|---|---|---|---|
file | File | Blob | Buffer | Yes | The image data to upload |
metadata | Record | No | Optional metadata to attach to the image |
Returns: Promise
Typescript
interface UploadResponse {
status: 'success' | 'error';
image_id?: string;
error_message?: string;
}
Node.js Example
Typescript
import fs from 'fs';
const buffer = fs.readFileSync('/path/to/photo.jpg');
const result = await client.uploadImage(buffer, {
album: 'vacation',
year: 2026,
});
console.log(result.image_id); // "a1b2c3d4..."
Browser Example
Typescript
const input = document.querySelector<HTMLInputElement>('#file-input');
input.addEventListener('change', async () => {
const file = input.files[0];
const result = await client.uploadImage(file);
console.log('Uploaded:', result.image_id);
});
deleteImage(imageId)
Delete an image by its ID.
| Parameter | Type | Required | Description |
|---|---|---|---|
imageId | string | Yes | UUID of the image to delete |
Returns: Promise
Typescript
interface DeleteResponse {
success: boolean;
message?: string;
}
Typescript
const result = await client.deleteImage('a1b2c3d4');
console.log(result.success); // true
console.log(result.message); // "Image deleted successfully"
getImageInfo(imageId)
Retrieve metadata and details about an image.
| Parameter | Type | Required | Description |
|---|---|---|---|
imageId | string | Yes | UUID of the image |
Returns: Promise
Typescript
interface ImageInfo {
id: string;
filename?: string;
width?: number;
height?: number;
format?: string;
size?: number;
created_at?: string;
metadata?: Record<string, unknown>;
}
Typescript
const info = await client.getImageInfo('a1b2c3d4');
console.log(`${info.width}x${info.height} ${info.format}`);
// "1920x1080 jpeg"
listImages(page?, limit?)
List all images for the authenticated customer, with pagination.
| Parameter | Type | Required | Description |
|---|---|---|---|
page | number | No | Page number (>= 1, default 1) |
limit | number | No | Results per page (1–100, default 20) |
Returns: Promise
Typescript
interface ImageListResponse {
images: ImageInfo[];
total: number;
page: number;
limit: number;
}
Typescript
const list = await client.listImages(1, 50);
console.log(`Showing ${list.images.length} of ${list.total} images`);
for (const img of list.images) {
console.log(`${img.id} — ${img.format} (${img.size} bytes)`);
}
Pagination Pattern
Typescript
async function getAllImages(client: ViucraftClient): Promise<ImageInfo[]> {
const all: ImageInfo[] = [];
let page = 1;
const limit = 100;
while (true) {
const response = await client.listImages(page, limit);
all.push(...response.images);
if (all.length >= response.total) break;
page++;
}
return all;
}
End-to-End Workflow
Typescript
import fs from 'fs';
import { ViucraftClient } from 'viucraft';
const client = new ViucraftClient({
apiKey: process.env.VIUCRAFT_API_KEY!,
subdomain: 'mycompany',
});
// 1. Upload
const buffer = fs.readFileSync('photo.jpg');
const upload = await client.uploadImage(buffer, { source: 'gallery' });
const imageId = upload.image_id!;
console.log('Uploaded:', imageId);
// 2. Get info
const info = await client.getImageInfo(imageId);
console.log(`Original: ${info.width}x${info.height}`);
// 3. Build transformation URLs
const thumbnail = client.image(imageId)
.thumbnail(200, 200, 'attention')
.setFormat('webp')
.quality(80)
.toURL();
const hero = client.image(imageId)
.resize(1200, 630)
.brightness(1.1)
.sharpen(0.5)
.quality(90)
.toURL();
console.log('Thumbnail:', thumbnail);
console.log('Hero:', hero);
// 4. List all images
const list = await client.listImages();
console.log(`Total images: ${list.total}`);
// 5. Delete when done
await client.deleteImage(imageId);
console.log('Deleted');