fluidghost
v2.1.0
Published
Official TypeScript/JavaScript client for the FluidGhost API. Spoof a photo, video, or carousel with your API key and get back distinct variants with device-authentic metadata — submit, poll, download.
Maintainers
Readme
fluidghost
Official TypeScript/JavaScript client for the FluidGhost API.
FluidGhost turns one photo or video into a set of distinct variants — each a fresh, standalone capture with its own metadata, its own pixels, and a device-authentic filename. This SDK spoofs media with your API key, over the submit → poll → download loop (a single photo, a video, or a whole carousel), and inspects metadata (read-only).
- Full API docs: https://ghost.fluidvip.com/docs/
- Works in Node.js 18+ (uses the built-in
fetch,FormData, andBlob).
Install
npm install fluidghostAuthentication
Mint an API key in the dashboard (Settings → API keys at https://ghost.fluidvip.com). Keep it server-side — never ship it in client code. A secret API key can submit jobs, read and download their results, and inspect metadata (management keys only provision).
import { FluidGhost } from "fluidghost";
const fg = new FluidGhost({ apiKey: process.env.FLUIDGHOST_KEY! });Spoof a photo or video
If your API key has a saved preset bound to it (pick it when you create the key in the dashboard), the key already carries the settings — the whole call is just the image:
const job = await fg.run({ image: { path: "photo.jpg" } });Otherwise name the settings on the call, as below. Note that recipeId, recipeConfig
and presetId override the key's bound preset.
run() submits a job and waits for it to finish. Results are one-time links:
downloadVariant() streams the bytes and the object is deleted on a successful download
(a second call throws 410). Photos and videos both go through the same call — the type is
detected from the file.
import { FluidGhost } from "fluidghost";
import { writeFile } from "node:fs/promises";
const fg = new FluidGhost({ apiKey: process.env.FLUIDGHOST_KEY! });
const job = await fg.run({
image: { path: "photo.jpg" }, // or a video: { path: "clip.mp4" }
recipeId: "full-refresh",
copies: 3,
options: { noise: 35, ultraSafe: true },
});
for (const v of job.variants) {
if (v.status !== "completed") continue;
const bytes = await fg.downloadVariant(job.jobId, v.index);
await writeFile(v.fileName ?? `variant-${v.index}.jpg`, bytes);
console.log(`${v.fileName} risk=${v.detectionRisk} (${v.riskBand})`);
}Manual submit + poll
const { jobId } = await fg.createJob({ image: { path: "photo.jpg" }, recipeId: "full-refresh", copies: 5 });
const done = await fg.waitForJob(jobId, { onPoll: (j) => console.log(j.status, j.progress) });You can also pass in-memory bytes instead of a path:
await fg.createJob({ image: { data: myUint8Array, filename: "photo.jpg" }, recipeId: "full-refresh" });Spoof a carousel (matched set)
A carousel is a set of photos posted together. spoofCarousel() submits one linked job per
file — sharing a session and a running filename sequence so the outputs read as a single
cohesive post — and waits for all of them.
const jobs = await fg.spoofCarousel(
[{ path: "slide1.jpg" }, { path: "slide2.jpg" }, { path: "slide3.jpg" }],
{ recipeId: "full-refresh" },
);
for (const job of jobs) {
const v = job.variants[0];
const bytes = await fg.downloadVariant(job.jobId, v.index);
await writeFile(v.fileName!, bytes);
}For a fully cohesive set (the same device across every slide), pass a
recipeConfigorpresetIdthat pins a device — otherwise each slide picks its own device family.
Inspect metadata
Read-only checks that need no job. They use the inspect:read scope (secret keys have it by
default) and share one rate-limit bucket (60 requests/min per account). Each takes the same file
input as the spoof calls: { path } or { data, filename }.
// Metadata grouped by container (EXIF, GPS, XMP, MakerNotes, ...)
const meta = await fg.inspect({ path: "photo.jpg" });
console.log(meta.format, meta.tagCount, meta.groups.IFD0?.Model);
// Deep forensic verdict: metadata, container structure, C2PA
const report = await fg.inspectForensics({ path: "photo.jpg" });
console.log(report.status, report.verdict, report.findings.length);
// Perceptual comparison of an original and a variant (no job is created)
const cmp = await fg.inspectCompare({ path: "original.jpg" }, { path: "variant.jpg" });
console.log(cmp.detectionRisk, cmp.band, cmp.matchThreshold);
// Metadata of one of your finished job's variants, read server-side
const resultMeta = await fg.inspectResult(job.jobId, 0);A key without inspect:read gets a FluidGhostError with status 403 and code
insufficient_scope.
Settings
Provide exactly one recipe source (or bind a default preset to your key and omit all three; any of the three you do send overrides the key's preset):
| Field | Meaning |
| --- | --- |
| recipeId | A bundled starter, e.g. "full-refresh". |
| presetId | A saved preset created in the dashboard (e.g. "sys:full-refresh"). |
| recipeConfig | A full recipe graph (advanced). |
| copies | Number of variants, 1–50. |
| strength | Global strength 0–100. |
| options | Extra knobs merged onto the recipe, e.g. { noise: 35, ultraSafe: true }. |
Errors
Every non-2xx response throws a FluidGhostError mirroring the API's { error, message, details }:
import { FluidGhostError } from "fluidghost";
try {
await fg.run({ image: { path: "photo.jpg" }, recipeId: "full-refresh", copies: 3 });
} catch (e) {
if (e instanceof FluidGhostError) {
console.error(e.status, e.code, e.message, e.details);
if (e.code === "rate_limited") await sleep((e.retryAfter ?? 5) * 1000);
if (e.code === "insufficient_balance") { /* top up in the dashboard */ }
}
}Configuration
new FluidGhost({
apiKey: "fg_sk_live_…",
baseUrl: "https://api-ghost.fluidvip.com", // default; override for a proxy
fetch: customFetch, // optional
});License
MIT
