gigai-tools

Node client and CLI for the GigAI Tools API. Run PDF, image, SVG and QR tools from code. The free plan gives 1,000 tasks a month with no card.

No dependencies. Node 18+.

Install

npm install gigai-tools

Get a key

Create an account at gigai.tools/developers and make an API key in the dashboard. Set it as GIGAI_API_KEY or pass apiKey.

One call

import { Client } from "gigai-tools";

const client = new Client();

// Merge two PDFs
await client.run("merge-pdf", { files: ["a.pdf", "b.pdf"], output: "merged.pdf" });

// Compress an image to fit under 200 KB
await client.run("compress-image", { files: ["photo.jpg"], options: { target_kb: 200 }, output: "small.jpg" });

// Generate a QR code (no input file - the text is the payload)
await client.run("generate-qr", { options: { text: "https://example.com" }, output: "qr.png" });

run() imports your files, runs the tool, exports the result and downloads it. Files can also be https:// URLs and the server fetches them.

CLI

The package installs a gigai command:

export GIGAI_API_KEY=gk_live_...

gigai tools
gigai run merge-pdf a.pdf b.pdf -o merged.pdf
gigai run generate-qr --text "https://example.com" -o qr.png
gigai jobs

Job graphs

Chain tools in one job. Each task names its inputs and the server runs them in dependency order:

let job = await client.createJob({
  in:  { operation: "import/url", url: "https://example.com/report.pdf" },
  rot: { operation: "rotate-pdf", input: ["in"], angle: 90 },
  txt: { operation: "pdf-to-text", input: ["rot"] },
  out: { operation: "export/url", input: ["txt"] },
}, { retentionS: 600 });

job = await client.wait(job.id);
const exportTask = job.tasks.find((t) => t.name === "out");
await client.download(exportTask.result.files[0].url, "report.txt");

Pass idempotencyKey to make retries safe: the same key returns the same job instead of running the work twice.

Errors

Every failure throws GigaiError with a machine-readable code (invalid_option, file_too_large, quota_exceeded, target_unreachable, ...), the human message, and the offending parameter when there is one.

Privacy

File contents are never logged. Results are deleted after the retention you choose (default 1 hour, retention_s: 0 means one download or 60 seconds) and deletion is verified. The web tools at gigai.tools never need an account - accounts exist only for this API.