Identify what a file is, without extracting it
vision_detectIdentify a file type to choose the right extraction preset, providing ranked, confidence-scored suggestions before you commit credits.
Instructions
Identify what a file IS without paying to extract it: the presets that could handle it, ranked, each with a confidence and a one-line reason.
Cost: 1 credit per 5 calls, whatever the file — detection only ever reads page 1, so a 300-page PDF costs the same as a photo. Four calls in five report 0 credits used.
recommended is exactly what preset:"auto" would run on this file, so you can probe first and
trust the answer.
Reach for this when the TYPE is the decision: routing a mixed inbox to different handlers, or refusing to spend two credits a page on a 40-page PDF sight unseen. Do NOT reach for it as a step before every vision_analyze call — if you want the data and do not care which preset produced it, preset:"auto" classifies the same way, for free, in the same request. Using detect first and then analyze is two calls where one would do.
If fallback is true, nothing matched confidently and the recommendation is the generic
preset. That is an honest "unknown", and it is worth surfacing to the user rather than
extracting against a shape nobody has confirmed.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| 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. |