One call does the whole round trip: upload, queue the job, follow it, hand you the result. No key is needed to start: without one you get the same free daily allowance a person gets in the browser.

npm install @formatika/sdk

Quick start

import { readFile, writeFile } from 'node:fs/promises'
import { Formatika } from '@formatika/sdk'

const formatika = new Formatika()

const result = await formatika.run({
  tool: 'image.convert',
  files: { filename: 'photo.heic', data: await readFile('photo.heic') },
  params: { format: 'webp', quality: 82 },
})

for (const file of result.files) {
  await writeFile(file.filename, await file.download())
}

Works anywhere fetch does — Node 20+, Bun, Deno, edge runtimes. Nothing from node: is imported, so bundlers have nothing to shim.

Keys and limits

const formatika = new Formatika({ apiKey: process.env.FORMATIKA_API_KEY })

FORMATIKA_API_KEY is picked up from the environment on its own, so passing apiKey is only needed when you keep the key somewhere else. Create keys in your account.

Without a key the client is an anonymous caller with the free daily allowance. With a key the allowance is larger, and work beyond it is paid with credits.

Tools and their parameters

const tools = await formatika.tools()
// → { id: 'image.convert', title, description, accept, maxFiles, params: <JSON Schema> }

params is the very schema the service validates against, so it can be fed to a form generator, a validator or an agent without being copied by hand. The list is live: tools added to formatika show up here without a new release of this package.

Progress, cancelling and timeouts

const controller = new AbortController()
setTimeout(() => controller.abort(), 30_000)

const result = await formatika.run({
  tool: 'video.compress',
  files: bigVideo,
  params: { targetMB: 24 },
  onProgress: (percent) => console.log(percent),
  signal: controller.signal,
})

Aborting stops the work on the server too, not just the waiting: a running encode is cancelled within a second. The same happens when the wait runs out (timeoutMs, three minutes by default) — nothing is left burning CPU for a result nobody is waiting for.

Errors

import { FormatikaError } from '@formatika/sdk'

try {
  await formatika.run({ tool: 'image.convert', files, params: { format: 'webp' } })
} catch (error) {
  if (error instanceof FormatikaError) {
    error.code // 'RATE_LIMITED' | 'QUOTA_EXCEEDED' | 'UNSUPPORTED_FORMAT' | …
    error.retryable // whether repeating the same call makes sense
    error.retryAfterSeconds // when the service told us how long to wait
  }
}

Retries are yours to make, deliberately. Repeating a job means a second job and a second charge, so the client never does it behind your back — it tells you whether repeating is sensible and, when the service said so, how long to wait.

A failed job raises the job's own code (ENGINE_FAILED, CORRUPT_INPUT, …), not the HTTP status: the request went fine, the work did not.

Step by step

run is the whole path; the steps are public too, when you need to hold the pieces yourself — a queue of your own, progress in a database, a job outliving the process:

const upload = await formatika.upload('pdf.merge', file)
const job = await formatika.createJob({ tool: 'pdf.merge', uploadIds: [upload.id] })

const done = await formatika.wait(job.id) // or poll formatika.job(job.id) yourself
const bytes = await formatika.download(done.files[0])

await formatika.cancel(job.id) // while it is queued or running

Result links are signed and short-lived: they are made to be downloaded now, not stored.

Privacy

Files are processed and deleted; results live for a limited time and then go. Nothing is kept for training, analysis or resale — that is the point of the service, not a footnote.