Extract structured data from an image or PDF
vision_analyzeExtract structured data from one image or PDF using a preset or custom schema. Missing fields and confidence levels are reported, and failed calls cost nothing.
Instructions
Extract structured data from ONE image or PDF (JPEG, PNG, WebP, TIFF, PDF — detected by magic bytes, the extension is ignored).
Cost: 1 credit per image, 2 per selected PDF page. Failures cost NOTHING — every non-2xx releases the reservation in full, so a failed call is safe to fix and repeat, and there is no cleanup to do.
Choose ONE way to say what you want:
preset — a catalogue name, or "auto" to have the API classify the file first, for free. "auto" is the right default when you do not already know the document type. Do not call vision_list_presets just to guess a preset; the classifier is better at it and free.
schema — your own fields, {"field_name": "what to extract"}. The description IS the prompt: "the invoice number exactly as printed, without the #" extracts better than "invoice number". A schema can be passed alongside a preset to add fields to it.
schema_name — a schema saved in the account's dashboard. Not combinable with the others.
Reading what comes back:
Fields the document did not carry are NOT printed as values — they are listed at the end under "Not found". A preset always defines every one of its fields, so an absent value means "this document does not have it", never "the call failed".
A "(mid)" or "(low)" after a value is its confidence; no marker means high. Decide deliberately what to do with a low-confidence number rather than treating it as fact.
Never hardcode a preset's field names from memory. Call vision_get_preset first if the names are going into code.
Long documents: leave mode at "auto". The server kills a synchronous request at 60 seconds; this tool then re-submits it to the queue and polls, and you are charged exactly once because the timed-out attempt refunded itself. Pass mode:"async" up front for anything over ~10 pages.
One file per call. To process a folder, call this once per file — and if you get too_many_tasks, wait for your own in-flight tasks rather than sleeping.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | auto (default) — try synchronously, and if the server times out at 60 s, resubmit to the queue and poll. The timed-out attempt refunds itself, so this costs one charge, not two. sync — fail rather than fall back. async — go straight to the queue. Pass this up front for anything over roughly 10 pages. | auto |
| pages | No | PDF page selection, e.g. "1-3,7". You are charged for selected pages only, so this is the cheap way to sample a long document. | |
| detail | No | "high" renders pages at higher resolution for dense or low-quality scans. Same credit cost, slower. | |
| format | No | markdown (default) — compact, readable, absent fields summarised rather than repeated. compact_json — the same information as data, with _not_found and _low_confidence arrays, for when you will parse it. json — the API response verbatim; use it when you are writing HTTP code against the contract. | markdown |
| output | No | "text" returns the raw transcription and nothing else. Cannot be combined with a preset or a schema. | |
| preset | No | A catalogue name, or "auto" to have the API classify the file first, for free. "auto" is the right default when you do not already know the document type. | |
| schema | No | Your own fields, as {"field_name": "what to extract"}. The description IS the prompt — "the invoice number exactly as printed, without the #" extracts better than "invoice number". Can be passed alongside a preset to add fields to it. | |
| file_url | No | Public HTTPS URL the API fetches itself. Private and internal addresses are refused by the server. | |
| file_path | No | Absolute or relative path to a file on the user's disk. Must be inside a directory this server was given access to — the error names them if it is not. | |
| max_chars | No | Ceiling on transcription text in the response. Raise it only if you truly need more than 20 000 characters. | |
| schema_name | No | A schema saved in the account dashboard. Not combinable with preset or schema. | |
| language_hint | No | ISO 639-1 code, e.g. "es". Auto-detected when omitted; only worth setting when detection is getting it wrong. | |
| min_confidence | No | Values below this level come back null with their confidence preserved. Default low, which filters nothing. | |
| include_raw_text | No | Also return the full transcription alongside the fields. Expensive in context — leave it off unless you need the prose. |