Vision API — Node.js client

Official Node.js and TypeScript client for Vision API — send an image or a PDF, describe the fields you want in plain language, get structured JSON back with a confidence level on every value.

Website — https://visionapi.io
Documentation — https://docs.visionapi.io
API keys — https://app.visionapi.io/dashboard/keys
Preset catalog — https://visionapi.io/presets
Playground — https://visionapi.io/playground
Support — https://support.visionapi.io · https://visionapi.io/contact-us

Install

npm install @devrobotlabs/visionapi

Node 18.17 or newer. No dependencies — the client uses the runtime's own fetch, FormData and crypto.

Quick start

import { VisionAPI } from '@devrobotlabs/visionapi';

const vision = new VisionAPI(); // reads process.env.VISION_API_KEY

const res = await vision.analyze({ file: 'invoice.pdf', preset: 'invoice' });

console.log(res.result.invoice_id.value); // 'A-10422'
console.log(res.result.total.value);      // 1284.5 — or null, if the invoice has no total
console.log(res.credits_used, res.credits_remaining);

Requests are metered in credits, per image and per selected PDF page — see pricing for current rates. Failures cost nothing: the reservation is released in full on any non-2xx, so there is no compensating logic to write.

Server-side only. There is no publishable key and no test mode — an API key is a live spending credential. Never ship one to a browser or a mobile app. For a frontend, put this library behind your own endpoint (see Using it from a browser).

Reading a result

Two rules explain almost every surprise:

1. Every scalar is wrapped. { value, confidence }, where confidence is 'low', 'mid' or 'high'. Read result.total.value, not result.total.

2. A preset response contains every field of that preset — including the ones the document does not carry, which come back as { value: null, confidence: 'low' }. A key being present does not mean a value was found. Check value !== null.

Line-item arrays are the one shape worth looking at twice. The array itself is not wrapped; each cell inside each row is:

{
  "invoice_id": { "value": "A-10422", "confidence": "high" },
  "carrier":    { "value": null,      "confidence": "low"  },
  "line_item": [
    {
      "description": { "value": "Widget", "confidence": "high" },
      "quantity":    { "value": 2,        "confidence": "high" },
      "amount":      { "value": 25.0,     "confidence": "mid"  }
    }
  ]
}

The library ships helpers for the common readings, so you rarely have to spell that out:

import { unwrap, value, rows, present, missing, belowConfidence } from '@devrobotlabs/visionapi';

const res = await vision.analyze({ file: 'invoice.pdf', preset: 'invoice' });

unwrap(res.result);                    // { invoice_id: 'A-10422', carrier: null, line_item: [{ description: 'Widget', … }] }
unwrap(res.result, { dropNull: true }); // only what was actually found
value(res.result, 'total', 0);         // 1284.5, or 0 when absent
rows(res.result, 'line_item');         // Row[] — [] when the invoice has no lines
present(res.result);                   // ['invoice_id', 'total', 'line_item']
missing(res.result);                   // ['carrier', …]
belowConfidence(res.result, 'high');   // fields to route to a human

Types are exported for all of it — AnalyzeResponse, Field, Row, ResultValue, Detection, Task, and the isField / isRows narrowing guards.

What you can send

Exactly one file source per call:

await vision.analyze({ file: 'invoice.pdf', preset: 'invoice' });              // a path
await vision.analyze({ file: buffer, preset: 'invoice' });                     // Buffer / Uint8Array
await vision.analyze({ file: { data: bytes, filename: 'scan.png' }, … });      // bytes + a name
await vision.analyze({ fileUrl: 'https://example.com/invoice.pdf', … });       // a public URL
await vision.analyze({ fileBase64: b64, … });                                  // base64, `data:` prefix optional

JPEG, PNG, WebP, TIFF and PDF, up to 20 MB and 50 pages. The type is detected from magic bytes — the filename is ignored.

Options

Option	Default	What it does
`preset`	—	A catalog name, or `'auto'` to let the API classify the file first (free).
`schema`	—	Custom fields, alone or on top of a preset.
`schemaName`	—	A schema saved in your dashboard. Excludes `preset` and `schema`.
`pages`	all	PDF page selection, e.g. `'1-3,7'`. You pay for selected pages only.
`languageHint`	auto	ISO 639-1 code, e.g. `'es'`.
`detail`	`'standard'`	`'high'` renders pages at higher resolution. Same cost, slower.
`output`	`'json'`	`'text'` returns raw OCR text instead of fields.
`includeRawText`	`false`	Adds `full_text`, the whole transcription, alongside `result`.
`minConfidence`	`'low'`	Fields below the level come back `null`, with confidence preserved.

Custom fields

A schema is a flat object: each key is a field name, each value describes what to extract. It is compiled before any credit moves, so a bad schema costs nothing.

const res = await vision.analyze({
  file: 'invoice.pdf',
  preset: 'invoice',
  schema: {
    // Plain form — the string is the description, type defaults to string.
    machine_serial: 'Serial number of the machine being invoiced, without the "SN:" prefix',

    // Typed form.
    total_net: { type: 'number', description: 'Total before tax' },
    signed_on: { type: 'date', description: 'Date the contract was signed' },
    is_paid:   { type: 'boolean', description: 'Whether the invoice is stamped PAID' },

    // Reserved key: injects fields into every row of the preset's line-item array.
    line_item: { lot_number: 'The lot number printed on the line, if present' },
  },
});

Field names must match ^[a-z][a-z0-9_]{0,63}$. Types are string (default), number, boolean, date, array and object. A custom name that collides with a preset field is a 422 schema_field_conflict — rename it, or use the preset's own field.

Descriptions are the prompt. "The invoice number exactly as printed, without the #" extracts better than "invoice number". Say what to do when the value is missing or ambiguous if it matters.

Reuse a combination by saving it:

await vision.createSchema({ name: 'our-invoices', preset: 'invoice', schema: { machine_serial: '…' } });
await vision.analyze({ file: 'invoice.pdf', schemaName: 'our-invoices' });

Picking a preset

28 presets ship with the API. Fetch the catalog rather than hardcoding field names from memory — presets are versioned, and the catalog is the source of truth:

const presets = await vision.presets();              // no API key required
const invoice = await vision.preset('invoice');
invoice.fields.map((f) => `${f.name}: ${f.description}`);

Three ways to choose:

// 1. You know what it is.
await vision.analyze({ file: 'receipt.jpg', preset: 'receipt' });

// 2. You don't, and you want the data anyway. Classification is free.
const res = await vision.analyze({ file: 'unknown.pdf', preset: 'auto' });
res.detection.preset;        // what ran
res.detection.fallback;      // true = "shape unknown", not a match
res.detection.alternatives;  // the rest of the ranking, best first

// 3. The *type* is the decision — routing a mixed inbox, or refusing to spend
//    on a 40-page PDF until you know what it is. Far cheaper than extracting.
const guess = await vision.detect({ file: 'unknown.pdf' });
if (guess.recommended === 'invoice' && !guess.fallback) {
  await vision.analyze({ file: 'unknown.pdf', preset: 'invoice' });
}

detect reads page 1 only, so an image and a 300-page PDF cost the same, and it is metered in batches rather than per call: most calls report credits_used: 0 and an occasional one carries the charge. See pricing for the rate.

Questions instead of fields

Up to 5 questions about one file, priced exactly like an extraction. The questions themselves are free.

const res = await vision.ask({
  file: 'photo.jpg',
  questions: ['Is there a dog in the image?', 'How many people are visible?'],
});

for (const a of res.answers) {
  console.log(a.question, '→', a.verdict, a.answer);
}

verdict is 'yes', 'no', 'uncertain' (a yes/no question the image does not settle) or 'n/a' (not a yes/no question). Branch on it instead of parsing the prose.

Long jobs: async and webhooks

Synchronous requests are killed at 60 seconds with a 504 sync_timeout. Anything that might run longer — a long PDF, detail: 'high', a batch — belongs on the queue.

// Submit, then poll. waitForTask handles the polling loop and the failure case.
const task = await vision.analyzeAndWait(
  { file: 'contract-80-pages.pdf', preset: 'contract', pages: '1-50' },
  { pollInterval: 2000, maxWait: 15 * 60_000, onPoll: (t) => console.log(t.status) },
);
console.log(task.result.parties.value);

// Or submit and walk away — the result comes to you.
const { task_id } = await vision.analyzeAsync({
  file: 'contract.pdf',
  preset: 'contract',
  webhookUrl: 'https://yourapp.com/hooks/vision',
});

Results stay retrievable for 7 days; after that the task returns 410 result_expired (metadata survives, the payload does not).

Verifying a delivery

Deliveries are signed. Verify over the raw bytes before parsing — a re-serialized body has different bytes and will not match.

import express from 'express';
import { verifyWebhook, WebhookSignatureError } from '@devrobotlabs/visionapi';

app.post('/hooks/vision', express.raw({ type: 'application/json' }), (req, res) => {
  let event;
  try {
    event = verifyWebhook(req.body, req.header('x-vision-signature'), process.env.VISION_WEBHOOK_SECRET);
  } catch (err) {
    if (err instanceof WebhookSignatureError) return res.status(400).end();
    throw err;
  }

  res.status(202).end();          // any 2xx is success — ack fast, work afterwards
  queue.push(event);              // event.event is 'task.completed' | 'task.failed'
});

verifyWebhook rejects a bad signature, a malformed header and a timestamp more than 5 minutes old, and accepts a delivery if any v1= part matches — which is what makes a secret rotation seamless. Get the secret from https://app.visionapi.io/dashboard/webhooks. Failed deliveries retry at +1 m, +5 m, +15 m and +40 m, then stop.

Errors

Every failure throws a subclass of VisionAPIError carrying the HTTP status, the stable code, and whatever details the endpoint attached. Branch on the class or on code — never on the message text, which is prose and changes.

import {
  InsufficientCreditsError,
  RateLimitError,
  SyncTimeoutError,
  UnsupportedTypeError,
  VisionAPIError,
} from '@devrobotlabs/visionapi';

try {
  await vision.analyze({ file: 'scan.pdf', preset: 'invoice' });
} catch (err) {
  if (err instanceof InsufficientCreditsError) {
    alertOps(`needs ${err.required}, has ${err.available}`);  // never retried — it cannot succeed
  } else if (err instanceof SyncTimeoutError) {
    await vision.analyzeAndWait({ file: 'scan.pdf', preset: 'invoice' });
  } else if (err instanceof UnsupportedTypeError) {
    quarantine('not an image or a PDF');
  } else if (err instanceof VisionAPIError) {
    log(err.code, err.status, err.requestId);
  }
}

Class	HTTP	Codes
`InvalidRequestError`	400	`invalid_request`
`AuthenticationError`	401	`invalid_api_key`, `unauthorized`
`InsufficientCreditsError`	402	`insufficient_credits` — with `.required` / `.available`
`PermissionError`	403	`forbidden`, `email_not_verified`
`NotFoundError`	404	`task_not_found`, `schema_not_found`
`ConflictError`	409	`conflict`
`ResultExpiredError`	410	`result_expired`
`PayloadTooLargeError`	413	`file_too_large`, `page_limit_exceeded`
`UnsupportedTypeError`	415	`unsupported_type`
`UnprocessableError`	422	`pdf_encrypted`, `invalid_page_selection`, `invalid_schema`, `schema_field_conflict`, `too_many_questions`
`RateLimitError`	429	`rate_limited` — with `.retryAfter`
`TooManyTasksError`	429	`too_many_tasks` — the per-plan async concurrency cap, with `.max`. Subclasses `RateLimitError`, but is not auto-retried: it clears when one of your tasks finishes
`InternalError`	500	`internal_error` — with `.requestId`
`ProviderError`	502	`provider_error`
`SyncTimeoutError`	504	`sync_timeout`

UsageError (bad arguments), ConnectionError / TimeoutError (the request never got a response) and TaskFailedError / TaskTimeoutError are thrown by the client itself.

Retries and idempotency

The client retries 429, 500, 502 and network failures — maxRetries: 3 by default, with the server's own Retry-After honored on 429 and exponential backoff with jitter elsewhere. Input errors and insufficient_credits are never retried, because they cannot succeed.

Every billable POST is sent with a generated Idempotency-Key, so a retried upload replays the first response instead of paying twice. Supply your own when the caller may retry — a job that re-runs, a queue that redelivers — because a fresh process generates a fresh key:

await vision.analyze({ file, preset: 'invoice' }, { idempotencyKey: `invoice-${invoiceId}` });

Reusing a key with a different payload is a 409 ConflictError, which is the mechanism working: it means the key already stands for something else.

Configuration

const vision = new VisionAPI({
  apiKey: process.env.VISION_API_KEY, // default: process.env.VISION_API_KEY
  baseUrl: 'https://api.visionapi.io', // default; override for a self-hosted deployment
  timeout: 120_000,                    // per request, ms
  maxRetries: 3,
  autoIdempotency: true,
  headers: { 'x-trace-id': traceId },  // sent on every request
  fetch: myInstrumentedFetch,          // swap the transport (tests, proxies, metrics)
});

Every method takes per-call { idempotencyKey, timeout, signal }; signal is a standard AbortSignal.

Account and usage

const { balance, buckets } = await vision.credits();
// buckets are spent in order: subscription → rollover → pack → welcome

for await (const record of vision.iterRequests({ limit: 100 })) {
  console.log(record.created_at, record.endpoint, record.preset, record.credits_used);
}

Usage history is metadata only — never the file, never the extracted values. Uploaded files are never retained: a synchronous request holds yours in memory for the length of the call, and an async request stages it only until the worker finishes with it.

Limits

Same for everyone:

Limit	Value
Max file size	20 MB
Max PDF pages per request	50
Sync request timeout	60 s

Per plan:

Limit	Free	Starter	Growth	Pro	Scale
Requests per minute, per key	10	60	120	300	600
Burst capacity	20	120	240	600	1,200
Concurrent async tasks	1	4	8	16	32
Active API keys per account	1	5	10	20	50
Saved schemas	3	10	25	100	unlimited
Max questions per `ask`	5	5	5	10	10

The rate-limit bucket is per API key, not per account — splitting a workload across keys splits the limit too. The concurrency cap is per account and does not split that way: over it, an async submission answers 429 too_many_tasks and is charged nothing. Higher limits on paid plans: https://visionapi.io/pricing.

Using it from a browser

Don't. A key in frontend code is a spending credential anyone can read. Put a thin endpoint in front of it instead:

// app/api/vision/analyze/route.ts — Next.js
import { VisionAPI } from '@devrobotlabs/visionapi';

const vision = new VisionAPI();

export async function POST(request: Request) {
  const form = await request.formData();
  const file = form.get('file') as File;

  // Your own authorization, your own quota, your own audit trail.
  await requireUser(request);

  const res = await vision.analyze({ file, preset: String(form.get('preset') ?? 'auto') });
  return Response.json(res);
}

Then call that endpoint from the browser — or use @devrobotlabs/visionapi-react or @devrobotlabs/visionapi-vue, which are built for exactly this shape.

Examples

Runnable scripts in examples/:

File	What it shows
`analyze.mjs`	The smallest useful call, and how to read the result
`custom-schema.mjs`	Custom fields, line-item injection, saved schemas
`detect-then-analyze.mjs`	Routing a mixed inbox before spending on extraction
`async-batch.mjs`	Queueing a folder of PDFs with bounded concurrency
`webhook-server.mjs`	A verified receiver, in ~40 lines
`ask.mjs`	Visual Q&A and the `verdict` field

export VISION_API_KEY=sk_live_…
node examples/analyze.mjs path/to/invoice.pdf

Development

npm install
npm run build      # tsc → dist/
npm test           # offline: fetch is stubbed, no key and no network needed
npm run typecheck

Contributing

Issues and pull requests are welcome at https://github.com/devrobotlabs/visionapi-node. For anything about the API itself — a preset, a limit, an error code — https://support.visionapi.io reaches the team faster.

Navigation Menu

Vision API — Node.js client

Install

Quick start

Reading a result

What you can send

Options

Custom fields

Picking a preset

Questions instead of fields

Long jobs: async and webhooks

Verifying a delivery

Errors

Retries and idempotency

Configuration

Account and usage

Limits

Using it from a browser

Examples

Development

Contributing

License

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Vision API — Node.js client

Install

Quick start

Reading a result

What you can send

Options

Custom fields

Picking a preset

Questions instead of fields

Long jobs: async and webhooks

Verifying a delivery

Errors

Retries and idempotency

Configuration

Account and usage

Limits

Using it from a browser

Examples

Development

Contributing

License