Ask questions about an image or PDF
vision_askAsk up to five plain-language questions about one image or PDF and get verdict-based answers (yes, no, uncertain, n/a) with confidence levels, turning visual judgment calls into decisions.
Instructions
Ask up to 5 plain-language questions about ONE image or PDF and get answers with a verdict.
Cost: 1 credit per image, and 1 per selected PDF page — half what extraction costs on a PDF, because the answer does not scale with the page. The questions themselves are free: asking five costs exactly what asking one costs. Failures cost NOTHING.
Reach for this over vision_analyze when the answer is a judgement rather than a field — "is this signed?", "does the delivery address match the billing address?", "is anyone wearing safety equipment?". Reach for vision_analyze when you want values you will store or compute with; asking for a total and then parsing the prose is slower, dearer and less reliable than extracting it.
Reading what comes back: branch on verdict, never on the prose.
"yes" / "no" — the images settle it.
"uncertain" — a yes/no question the images genuinely do not settle. Treat it as missing information, not as a "no".
"n-a" — the question was not a yes/no question; the answer is in the prose. Each verdict carries a confidence, shown as "(mid)" or "(low)"; no marker means high.
Answers are at document level, not per page. Long documents behave exactly as in vision_analyze — leave mode at "auto", or pass "async" up front past ~10 pages.
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 |
| 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. | |
| questions | Yes | Up to 5 questions about the file. The questions themselves are free — asking five costs the same as asking one. | |
| language_hint | No | ISO 639-1 code, e.g. "es". Auto-detected when omitted; only worth setting when detection is getting it wrong. |