VisionFly SDK

Official SDK for the VisionFly Image API — upload, transform, list/delete, and generate images, all returning one optimized CDN URL.

Works in the browser and in Node.js 18+ (uses the global fetch). Ships ESM and CommonJS builds with TypeScript types.

Installation

npm install visionfly-sdk

Quick start

import { VisionFly } from "visionfly-sdk";

const vf = new VisionFly({ apiKey: "your-api-key" });

// 1. Upload — returns an image id and CDN URL
const { imageId, url } = await vf.upload(file);

// 2. Build a transformed URL (no network call — just string building)
const thumb = vf.url(imageId, { width: 400, format: "webp", quality: 70 });
// → https://img.visionfly.ai/img_abc123?w=400&f=webp&q=70

v2 is a breaking change from v1. Auth is now a single apiKey (no apiSecret/login). transformImage()/getSrcSet() are replaced by the synchronous url()/srcset() builders, and uploadImage() is now upload(). See Migration.

Authentication

Pass your API key. It's sent as the X-API-Key header on every request.

const vf = new VisionFly({
  apiKey: "your-api-key",
  // optional overrides:
  // baseUrl: "https://api.visionfly.ai",
  // cdnUrl: "https://img.visionfly.ai",
  // fetch: customFetch, // defaults to global fetch
});

Usage

Upload

const result = await vf.upload(file, { project: "my-website" }); // project is optional
// { imageId, url, size, contentType }

Transform URLs (no network call)

url() builds a CDN URL with transforms applied on the fly. It's a pure function — call it as often as you like.

vf.url("img_abc123", {
  width: 800,
  height: 600,
  quality: 85,
  format: "webp", // auto | webp | avif | jpeg | png
  fit: "cover", // contain | cover | fill | crop
  blur: 5, // 0–100
  sharpen: 10, // 0–100
  brightness: 10, // -100–100
  contrast: 15, // -100–100
  saturation: -10, // -100–100
  hue: 30, // 0–360
  gamma: 1.2, // 1.0–3.0
  optimize: true,
});

Responsive srcset

const srcset = vf.srcset("img_abc123", {
  widths: [400, 800, 1200, 1600],
  transform: { format: "webp", quality: 75 },
});

// <img src={vf.url("img_abc123", { width: 800 })} srcSet={srcset} sizes="(max-width:768px) 100vw, 50vw" />

List images (paginated)

const { images, nextCursor, total } = await vf.listImages({
  project: "my-website", // optional filter (slug)
  limit: 50, // 1–100
  cursor, // pass the previous nextCursor for the next page
});

Delete images

await vf.deleteImages("img_abc123");
await vf.deleteImages(["img_a", "img_b"]); // up to 50 per call

Generate an image (AI)

Returns a Blob of the image bytes. Standard = 1 credit, HD = 2 credits.

const blob = await vf.generate("a red bicycle on a misty street", {
  quality: "hd",
});

// Browser: const objectUrl = URL.createObjectURL(blob);
// Node:    const buf = Buffer.from(await blob.arrayBuffer());

Remove background

Returns a transparent PNG Blob. Pass a file or a src URL.

const png = await vf.removeBackground({ file });
const png2 = await vf.removeBackground({
  src: "https://img.visionfly.ai/img_abc123",
});

CommonJS

const { VisionFly } = require("visionfly-sdk");
const vf = new VisionFly({ apiKey: "your-api-key" });

Error handling

Any non-2xx response throws a VisionFlyError carrying the HTTP status and the backend's message.

import { VisionFly, VisionFlyError } from "visionfly-sdk";

try {
  await vf.upload(file);
} catch (err) {
  if (err instanceof VisionFlyError) {
    console.error(err.status, err.message); // e.g. 413 "File size exceeds the 50MB limit"
  }
}

API reference

| Method | Returns | Notes | | ------------------------------------------------------ | ----------------------------- | ---------------------------- | | new VisionFly({ apiKey, baseUrl?, cdnUrl?, fetch? }) | — | apiKey required | | url(imageId, options?) | string | Pure builder, no request | | srcset(imageId, { widths?, transform? }) | string | Pure builder, no request | | upload(file, { project? }) | Promise<UploadResult> | POST /cdn/upload | | listImages({ project?, limit?, cursor? }) | Promise<ListImagesResult> | GET /cdn/images | | deleteImages(ids) | Promise<DeleteImagesResult> | DELETE /cdn/images, max 50 | | generate(prompt, { quality? }) | Promise<Blob> | POST /image/generate | | removeBackground({ file?, src? }) | Promise<Blob> | POST /image/remove-bg |

Migrating from v1

• new VisionFly({ apiKey, apiSecret }) → new VisionFly({ apiKey }) (no secret).
• uploadImage({ file }) → upload(file). The response now has imageId and url.
• transformImage({ src, ... }) (async, hit the API) → url(imageId, { ... }) (sync, no request).
• getSrcSet({ src, widths }) → srcset(imageId, { widths, transform }) (returns a plain srcset string).
• New: listImages, deleteImages, generate, removeBackground.
• The React/Next helper components from v1 are not part of v2 (kept under legacy/ in the repo).

Support Email

[email protected]

License

ISC