@doc-cheap/ai-sdk

doc.cheap tools for the AI SDK: a model that has them can read a photo or scan of a passport, national ID card or driving licence and get back the printed fields – name, date of birth, document number, expiry, the machine-readable zone – as structured JSON.

One recognised document costs one credit, $0.01. Registering gives 100 free documents every month. An unreadable image, an empty frame or an unsupported document type costs nothing, and every answer says whether it was billed.

Installation · Usage · API key · Tools · Errors · Resources · Version history

Installation

npm install @doc-cheap/ai-sdk ai zod

ai (version 6 or 7) and zod (3.25.76 or later, or 4) are peer dependencies: the package uses the copies your project already has. It needs Node.js 20 or later.

Usage

import { generateText, isStepCount } from "ai";
import { docCheapTools } from "@doc-cheap/ai-sdk";

const { text } = await generateText({
  model: "openai/gpt-5-mini",
  tools: docCheapTools(),
  stopWhen: isStepCount(3),
  prompt:
    "Read the passport at https://example.com/passport.jpg and tell me " +
    "the holder's name and when the passport expires.",
});

console.log(text);

docCheapTools() returns all five tools. To give the model only some of them, build each one on its own:

import { getUsage, scanDocument } from "@doc-cheap/ai-sdk";

const tools = { scanDocument: scanDocument(), getUsage: getUsage() };

Every builder takes the same options:

| Option | Default | Meaning | | --- | --- | --- | | apiKey | DOC_CHEAP_API_KEY, then sk_sandbox_public | The key sent as a Bearer token. | | baseUrl | DOC_CHEAP_API_BASE, then https://api.doc.cheap | The API's address. | | fetch | the runtime's own | The fetch the API calls go through. |

The environment is read when a tool runs, not when it is built, so a .env file loaded after the import still applies.

API key

Set DOC_CHEAP_API_KEY to a live key (sk_live_…) from the doc.cheap cabinet.

Without a key the tools use the public sandbox key sk_sandbox_public, so they work before you have an account. The sandbox gives 10 free recognised documents per address in all, and at most 10 requests per address an hour, whatever their answer. Nothing made under a sandbox key is stored.

Tools

| Tool | API call | What it does | | --- | --- | --- | | scanDocument | POST /v1/scans | Recognises a passport, ID card or driving licence. | | getScan | GET /v1/scans/{id} | Reads back a stored result. Never charges. | | deleteScan | DELETE /v1/scans/{id} | Deletes a stored result for good. | | listScans | GET /v1/scans | Lists stored results, newest first, a page at a time. | | getUsage | GET /v1/usage | This month's free credits, the paid credits and the scan counters. |

scanDocument

| Input | Type | Meaning | | --- | --- | --- | | imageUrl | string | An https: URL of a JPEG or PNG on a public address. The package downloads it itself, 25 MiB at most. | | imageBase64 | string | The image as base64, or a data: URL. Give this or imageUrl, not both. | | expectCountry | string | Optional. The country you expect, a three-letter code such as GRC. | | returnPortrait | boolean | Optional. Whether to return the holder's photo crop (default true). | | retainHours | number | Optional. How many hours the result can be read back, 0 to 8760. Empty uses the account's setting. | | reference | string | Optional. Your own reference, up to 128 characters, echoed back. | | idempotencyKey | string | Optional. Sending the same key again returns the first answer instead of charging a second scan. |

The result is the scan as the API returns it: meta (id, status, whether it was billed, confidence), the document, the holder, every field read off the page, the machine-readable zone and the image crops. Your code gets the whole result. The copy the model sees has each image crop replaced by a short note of its size, because a model cannot look at base64 text and it would fill the context window.

Image URLs. Only https: URLs on public internet addresses are fetched. A URL that points at a private, loopback or link-local address is refused, and so is a redirect to one; each redirect is checked again, and the address is checked once more at the moment of connecting.

Stored results. A result is stored only when the scan was made with a live key under a non-zero retention window, and only until that window ends. Under a sandbox key nothing is stored, so getScan and deleteScan answer "not found" and listScans is empty.

Errors

A failed call throws a DocCheapError. The AI SDK hands the message to the model as the tool's error result, so the model can react to it. The error has status – the HTTP status, or null when no answer came back – and code, the API's own error code.

• 401 / 403 – the API key was refused.
• 429 – the rate limit or the sandbox allowance was reached: try later. The key itself is fine.
• 404 – the scan does not exist, or was never stored.
• invalid_input – the arguments were wrong, for example both imageUrl and imageBase64, or an image that is not JPEG or PNG.
• image_refused – the image URL could not be fetched or is not allowed.
• network_error – doc.cheap could not be reached.

Every request carries the header User-Agent: doc-cheap-ai-sdk/<version>, so the API can tell calls made through this package from other callers. Nothing else about your application is sent.

Resources

• Using doc.cheap with the AI SDK
• doc.cheap documentation
• Your first recognition
• API reference
• Handling errors

Version history

See CHANGELOG.md.

License

MIT