Perception
Classify
client.documents.classify(params, options?) labels a document, or each page, with your classes. It takes the shared parameters, except that source can't be a parse_result, and:
| Parameter | Type | Required | Description |
|---|---|---|---|
classes | Array<{ id, label, description?, criteria?, subclasses? }> | Yes | Your labels. See classes. |
granularity | "document" | "page" | No | Score the whole file once, or once per page. Default: "document". |
page_ranges | Array<{ start, end }> | No | Pages to read and classify. Not for workbooks. Default: all pages. |
unknown_policy | "allow" | "force_best" | No | "allow" (default) may mark a unit unknown; "force_best" commits an ambiguous unit to one of your classes. |
output | { max_alternatives?, include_reason? } | No | How many labels, and whether each has a reason. See output. |
parse_mode | "low" | "medium" | "high" | No | How hard the parse behind the classification works. Default: "low". |
Each object option takes these keys:
classes
One entry per label, each an object:
| Key | Type | Default | Description |
|---|---|---|---|
classes[].id | string | Required | The label's id, returned on the results. |
classes[].label | string | Required | The label's name. |
classes[].description | string | "" | What belongs in the class. |
classes[].criteria | Array<string> | None | Extra rules to apply when scoring this class. |
classes[].subclasses | Array<{ id, label, description?, criteria? }> | None | Finer labels under this class, each with subclasses[].id and subclasses[].label (both required), and an optional subclasses[].description and subclasses[].criteria. |
output
| Key | Type | Default | Description |
|---|---|---|---|
output.max_alternatives | number | 3 | The ranked labels to return per unit, from 1 to 10. |
output.include_reason | boolean | true | Add a short reason to each label. |
const job = await client.documents.classify({
source: { type: "url", url: "https://example.com/invoice.pdf", file_name: "invoice.pdf" },
classes: [
{ id: "invoice", label: "Invoice", description: "A supplier invoice" },
{ id: "contract", label: "Contract", description: "A signed agreement between two parties" },
],
granularity: "page",
});
const done = await client.jobs.wait(job.job_id);Class ids must be unique and can't contain /, and other, blank_page, unreadable_content and __ndi_unclassified are reserved. See Classify.