@swiftimg/sdk

Zero-dependency JavaScript/TypeScript SDK for swiftimg — fast image & GIF hosting and an image CDN/API. Works in Node ≥ 18 and the browser (both have global fetch). No build step, no dependencies, fully typed.

Install

npm i @swiftimg/sdk

Quickstart

import { createClient, buildTransformUrl } from "@swiftimg/sdk";

const swift = createClient({ apiKey: process.env.SWIFTIMG_KEY });

// Upload
const img = await swift.upload(
  { data: await fs.readFile("cat.png"), filename: "cat.png" },
  { title: "My cat", tags: ["pets", "cat"] }
);
console.log(img.pageUrl, img.directUrl);

// Build a resized WebP URL (unsigned — works when URL signing is off)
const thumb = buildTransformUrl(img, { w: 320, fmt: "webp" });

// In production, get a signed, transform-capable URL (Developer plan)
const { url } = await swift.signedUrl(img.id, { w: 640, fmt: "webp", ttl: 3600 });

API

createClient({ apiKey?, baseUrl?, clientId?, source?, fetch? }) returns a client:

• upload(input, meta?) — input is a Blob or { data, filename?, type? }.
• get(id) — metadata, variants, and tags.
• mine() — your uploads (needs an API key).
• search(query, { limit? }) / trending() / recent() — public images.
• searchGifs(query, { limit? }) / trendingGifs({ limit? }) — public GIFs.
• setTags(id, tags) — replace an image's tags.
• signedUrl(id, { w?, h?, fmt?, q?, ttl? }) — time-limited transform URL (Developer/Business).
• delete(id, deleteToken?) — delete by API key or delete token.

buildTransformUrl(target, { w?, h?, fmt?, q? }) builds an unsigned transform URL from a direct URL or an upload result. Errors throw SwiftimgError with status and code.

apiKey falls back to SWIFTIMG_KEY and baseUrl to SWIFTIMG_API. MIT licensed. Full docs: https://swiftimg.com/developers