Introduction to 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. The FluidGhost API lets your own code do this end to end: submit a source with your settings, poll until it's done, and collect the results — either into your FluidGhost Drive or as one-time links that delete on download.

This page introduces the API and its mental model. When you're ready to make your first call, jump to the quickstart.

The job model

The whole API is built around one idea: a job.

• You submit a source and a set of settings. The source is an image or video; the settings say how to uniquify it and how many variants to produce.
• FluidGhost runs the job on a worker. Uniquifying a batch — especially video — takes real compute, so a job is asynchronous: you get a jobId back immediately, then poll its status.
• You collect the variants. When the job finishes, each variant carries a result you can download. Where those results live is your choice (see Delivery modes).

So a typical integration looks like: submit the job → poll the status → download each variant.

What you can do with an API key

A per-account API key gives your code everything it needs:

• Submit a spoof job — one photo or video, your settings, up to 50 variants. See POST /jobs.
• Poll a job — read its status, progress, and per-variant results. See GET /jobs/{id}.
• Download a one-time result — stream a variant; it deletes on a successful download. See GET /jobs/{id}/download/{variant}.

Prefer not to write the HTTP yourself? Use the official SDKs — npm install fluidghost or pip install fluidghost.

Account-level operations — generating and revoking API keys, topping up your balance, managing your team — live in the dashboard, not the API.

The mental model

A few resources, in a fixed relationship. Read this top-to-bottom and the rest of the docs will click into place.

1. Job — one uniquify run. Your API key owns it. A job takes one source and produces copies variants.
2. Source — the image or video you submit, either as a multipart file upload or a pre-uploaded key. Supported: JPEG, PNG, WebP, TIFF, HEIC, AVIF, MP4, MOV.
3. Settings — how to uniquify. A named preset (recipeId for a bundled one, presetId for one of yours, or none at all if your API key has a default preset bound to it), or a full recipe (recipeConfig) — the complete node graph the Studio builds. Either way the convenience knobs (copies, strength, options) adjust it per call. See Configuring your own settings.
4. Variant — one produced result. Each has its own seed, so no two variants are alike. A variant carries a resultKey/url (or a one-time download link), an authentic fileName, and an optional detection-risk audit.
5. Delivery mode — where results go. drive writes them to your FluidGhost Drive; ephemeral returns one-time links that delete on download. See Delivery modes.

API key  (one account, generated in the dashboard)
└── Job  (one source + your settings)
    └── Variant × copies   (each distinct: own seed, metadata, filename)
        ├── delivery: drive      → saved to your FluidGhost Drive
        └── delivery: ephemeral  → one-time download link (deletes on download)

Delivery modes

Every job picks how its results are delivered:

• drive (default for the web app) — each variant is written to your FluidGhost Drive, into a per-session folder, exactly as the Studio does. Results persist until you delete them.
• ephemeral (the one-time path) — results are not saved to your Drive. Instead each variant gets a short-lived download link served by the API. A link deletes its object on the first successful download, and anything never downloaded is purged after one hour. Multi-copy jobs return one link per variant. This is the mode for "spoof it, grab it, and leave nothing behind." See the One-time results guide.

Base URLs

What	URL
API base	https://api-ghost.fluidvip.com/api
Dashboard (generate your API key)	https://ghost.fluidvip.com

Every route lives under the /api prefix, so the full base for any call is:

https://api-ghost.fluidvip.com/api

Versioning. New fields and endpoints may be added under /api, but existing behavior won't change underneath you. A future breaking change would ship under a new prefix. See Versioning.

How authentication works (in one line)

Send your API key as a bearer token in the Authorization header.

curl https://api-ghost.fluidvip.com/api/options \
  -H "Authorization: Bearer fg_sk_live_8f3c..."

The key is per-account and authorizes exactly the actions in these docs. Full details are in Authentication.

The error envelope at a glance

Errors return a flat JSON body with a machine-readable error code and a human message:

{ "error": "insufficient_balance", "message": "Not enough balance for this job.", "details": { "balance": 0.4, "required": 3 } }

error maps to the HTTP status (401 → unauthorized, 402 → insufficient_balance, 429 → rate_limited, and so on). The full table is in Errors.

What running a job costs

Uniquifying costs compute, so FluidGhost charges your shared ecosystem balance — the same balance FluidTalk conversations draw on — at a per-variant rate. The balance is debited before the job is enqueued and refunded if the job fails, both idempotent on the job id. When the balance can't cover a job, the API returns 402 insufficient_balance and nothing runs. Top up in the dashboard. See Billing.

Next steps

• Quickstart — generate a key and run your first job end to end.
• Authentication — generate your API key and send it correctly.
• Core concepts — a deeper tour of jobs, variants, settings, and delivery.
• One-time results — the ephemeral, delete-on-download flow.
• API reference — every endpoint, parameter, and field.