Official Vue 3 composables for Vision API — let a user pick an image or a PDF and get structured JSON back with a confidence level on every value.
- Website — https://visionapi.io
- Documentation — https://docs.visionapi.io
- API keys — https://app.visionapi.io/dashboard/keys
- Preset catalog — https://visionapi.io/presets
- Playground — https://visionapi.io/playground
- Support — https://support.visionapi.io · https://visionapi.io/contact-us
There is no publishable key and no test mode. A Vision API key is a live spending
credential — anyone who reads it out of your bundle can spend your credits. So these
composables do not talk to api.visionapi.io. They talk to your endpoint, which
holds the key and calls the API server-side with
@devrobotlab/visionapi.
In Nuxt that endpoint is a file in server/api/, and it is also where your own
authorization, quota and audit trail belong:
// server/api/vision/analyze.post.ts — Nuxt
import { VisionAPI, VisionAPIError } from '@devrobotlab/visionapi';
const vision = new VisionAPI(); // reads VISION_API_KEY, server-side only
export default defineEventHandler(async (event) => {
const user = await requireUser(event); // your auth
const form = await readMultipartFormData(event);
const file = form?.find((part) => part.name === 'file');
if (!file) throw createError({ statusCode: 400 });
try {
return await vision.analyze({
file: { data: file.data, filename: file.filename ?? 'upload' },
preset: String(form?.find((p) => p.name === 'preset')?.data ?? 'auto'),
});
} catch (error) {
if (error instanceof VisionAPIError) {
// Forwarding the envelope is what lets the composables branch on error.code.
throw createError({
statusCode: error.status,
data: { error: { code: error.code, message: error.message, details: error.details } },
});
}
throw error;
}
});The composables expect POST {baseUrl}/analyze, /ask, /detect, and
GET {baseUrl}/tasks/:id and /presets. Full proxies for Nuxt and Express are in
examples/.
npm install @devrobotlab/visionapi-vueVue 3.4+. No dependencies of its own.
// main.ts
import { createVisionAPI } from '@devrobotlab/visionapi-vue';
app.use(createVisionAPI({ baseUrl: '/api/vision' }));The plugin is optional — every composable takes the same options directly.
<script setup lang="ts">
import { useAnalyze, unwrap } from '@devrobotlab/visionapi-vue';
const { analyze, data, isLoading, error, progress } = useAnalyze();
function onPick(event: Event) {
const file = (event.target as HTMLInputElement).files?.[0];
// The promise rejects on failure too; `error` is set either way.
if (file) analyze(file, { preset: 'receipt' }).catch(() => {});
}
</script>
<template>
<input type="file" accept="image/*,application/pdf" @change="onPick" />
<progress v-if="isLoading" :value="progress" max="1" />
<p v-if="error" role="alert">{{ error.userMessage }}</p>
<dl v-if="data">
<template v-for="(value, field) in unwrap(data.result, { dropNull: true })" :key="field">
<dt>{{ field }}</dt>
<dd>{{ value }}</dd>
</template>
</dl>
</template>Extract structured data from one file.
const { analyze, data, isLoading, error, progress, cancel, reset } = useAnalyze();
await analyze(file, {
preset: 'invoice', // a catalog name, or 'auto' to classify first (free)
pages: '1-3', // PDF page selection; you pay for selected pages only
min_confidence: 'mid', // weaker values come back null, confidence preserved
schema: { machine_serial: 'Serial number of the machine being invoiced' },
});Everything returned is a ref, so it works in a template without .value and in script
with it. progress runs 0→1 during the upload, which is worth showing on a phone sending a
15 MB scan. cancel() aborts the request in flight; reset() clears the last result.
Unmounting cancels automatically — the composable hooks onScopeDispose, so navigating away
mid-upload leaves nothing behind.
Up to 5 questions about one file, priced exactly like an extraction. The questions themselves are free.
<script setup lang="ts">
const { ask, data } = useAsk();
await ask(file, ['Is the signature present?', 'Is the date after 2026-01-01?']);
</script>
<template>
<li v-for="answer in data?.answers" :key="answer.question">
{{ answer.question }} → <strong>{{ answer.verdict }}</strong>: {{ answer.answer }}
</li>
</template>verdict is 'yes', 'no', 'uncertain' (the image does not settle it — a real answer,
not a failure) or 'n/a' (it wasn't a yes/no question). Branch on it instead of parsing the
prose.
Ask what a file is before committing to an extraction. It is metered in batches whatever the page count, and far cheaper than an extraction (see pricing) — cheap enough to run on every upload:
const { detect } = useDetect();
const guess = await detect(file);
guess.recommended; // exactly what preset: 'auto' would have run
guess.fallback; // true = "shape unknown", not a match
guess.detections; // the ranking, best first, with reasons"This looks like a receipt — extract it?" is a much better experience than paying to extract a 40-page PDF nobody looked at.
Poll an async task until it settles. Long PDFs and detail: 'high' need this: a synchronous
request is killed at 60 seconds.
const taskId = ref<string | null>(null);
const { task, isPolling, isDone, stop } = useTask(taskId, {
pollInterval: 2000,
onSettled: (task) => toast(task.status === 'completed' ? 'Done' : 'Failed'),
});
async function submit(file: File) {
const form = new FormData();
form.set('file', file);
const { task_id } = await $fetch('/api/vision/analyze-async', { method: 'POST', body: form });
taskId.value = task_id; // polling starts here
}taskId is reactive — a ref, a getter or a plain string. Polling stops on its own when the
task finishes, when maxWait elapses, and on unmount. A transient failure mid-poll does not
throw the result away; only a terminal one (404, 410, 401, 403) stops it and lands on
error.
The catalog, for a picker. Fetching beats hardcoding: presets are versioned, new ones appear, and the catalog carries the description you want next to each option.
<script setup lang="ts">
const { presets, isLoading } = usePresets();
const preset = ref('auto');
</script>
<template>
<select v-model="preset" :disabled="isLoading">
<option value="auto">Detect automatically</option>
<option v-for="p in presets" :key="p.name" :value="p.name" :title="p.description">
{{ p.title }} ({{ p.field_count }} fields)
</option>
</select>
</template>Two rules explain almost every surprise:
1. Every scalar is wrapped. { value, confidence }, where confidence is 'low',
'mid' or 'high'. Read data.result.total.value, not data.result.total.
2. A preset response contains every field of that preset — including the ones the
document does not carry, which come back as { value: null, confidence: 'low' }. A key
being present does not mean a value was found.
Line-item arrays are the one shape worth looking at twice: the array itself is not wrapped, each cell inside each row is.
The helpers cover the common readings:
import { unwrap, value, rows, belowConfidence, atLeast } from '@devrobotlab/visionapi-vue';
unwrap(data.value.result, { dropNull: true }) // { invoice_id: 'A-10422', total: 1284.5, … }
value(data.value.result, 'total', 0) // 1284.5, or 0 when absent
rows(data.value.result, 'line_item') // Row[] — [] when the invoice has no lines
belowConfidence(data.value.result, 'high') // fields to highlight for reviewunwrap() is also the right shape to seed a form — extract, prefill with v-model, let the
user correct the weak fields, save:
<script setup lang="ts">
const form = ref<Record<string, unknown>>({});
const weak = computed(() => new Set(belowConfidence(data.value?.result, 'high')));
watch(data, (res) => {
if (res) form.value = unwrap(res.result, { dropNull: true });
});
</script>
<template>
<input v-model="form.total" :aria-invalid="weak.has('total')" />
</template>Every failure is a VisionError with the HTTP status, the stable code, and whatever
details your endpoint forwarded. Branch on code — never on the message text.
<template>
<UpgradePrompt v-if="error?.isInsufficientCredits" />
<p v-else-if="error?.isTooLarge">Try a smaller file — the limit is 20 MB.</p>
<p v-else-if="error" role="alert">{{ error.userMessage }}</p>
</template>error.userMessage is a plain sentence for each common code, so you get a decent UI without
writing a switch. The convenience flags are isInsufficientCredits, isUnsupportedType,
isTooLarge and isTimeout; anything else is error.code.
For this to work your proxy must forward the API's error envelope, as the example above
does. If it swallows it, the composables still produce a structured http_<status> error.
app.use(createVisionAPI({
baseUrl: '/api/vision', // your endpoint, not the API
headers: () => ({ authorization: `Bearer ${session.token}` }), // read at request time
credentials: 'same-origin',
}));Pass headers as a function when the value changes — a rotating session token read at
install time would go stale. Every composable also takes the same options directly:
const { analyze } = useAnalyze({ baseUrl: '/api/vision-admin' });fetch can be swapped for a mock, which is how this package's own tests run.
Add the plugin client-side and put the proxy in server/api/:
// plugins/vision.client.ts
import { createVisionAPI } from '@devrobotlab/visionapi-vue';
export default defineNuxtPlugin((nuxtApp) => {
nuxtApp.vueApp.use(createVisionAPI({ baseUrl: '/api/vision' }));
});The composables are client-side by nature — they start on a user picking a file — and
nothing runs during SSR: useAnalyze fires only when you call analyze, and useTask(null)
polls nothing. usePresets does fetch on setup, so wrap it in <ClientOnly> or call
reload() from onMounted if you would rather it never ran on the server.
| Limit | Default | What it means for your UI |
|---|---|---|
| Max file size | 20 MB | Validate before upload; a 413 wastes the round trip. |
| Max PDF pages per request | 50 | Offer a page range for long documents. |
| Sync request timeout | 60 s | Anything longer needs the async + useTask path. |
Max questions per ask |
5–10 | Per plan; the composable rejects one over the limit before sending. |
| Requests per minute, per key | 10–600 | Per plan. Shared across your whole app — the key is per account. |
| Concurrent async tasks | 1–32 | Per plan, per account. Over it: 429 too_many_tasks. |
Extractions are metered per image and per selected PDF page — a document page costs
twice an image on analyze, the same as an image on ask — and detect far more
cheaply. See pricing for current rates and the full
per-plan matrix. Failures cost nothing, so a rejected upload never charges the user.
In examples/:
| File | What it shows |
|---|---|
ReceiptScanner.vue |
Upload → extract → editable form, with confidence highlights |
DetectThenAnalyze.vue |
Confirm the document type before spending credits |
AsyncUpload.vue |
A long PDF through the queue with useTask |
nuxt-server-route.ts |
The Nuxt proxy, with auth and error forwarding |
npm install
npm run build
npm test # offline: fetch is stubbed, composables run in a real effect scope
npm run typecheckIssues and pull requests are welcome at https://github.com/devrobotlabs/visionapi-vue. For anything about the API itself — a preset, a limit, an error code — https://support.visionapi.io reaches the team faster.
MIT © Vision API