Download the PHP package visionapi/visionapi-php without Composer
On this page you can find all versions of the php package visionapi/visionapi-php. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download visionapi/visionapi-php
More information about visionapi/visionapi-php
Files in visionapi/visionapi-php
Package visionapi-php
Short Description Official PHP client for the Vision API — credit-based OCR and visual intelligence. Extract structured JSON from images and PDFs.
License MIT
Homepage https://visionapi.io
Informations about the package visionapi-php
Vision API — PHP client
Official PHP client for Vision API — send an image or a PDF, describe the fields you want in plain language, 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
Install
PHP 8.1+, with ext-curl and ext-json. No package dependencies.
Quick start
Requests are metered in credits, per image and per selected PDF page — see pricing for current rates. Failures cost nothing: the reservation is released in full on any non-2xx, so there is no compensating logic to write.
Server-side only. There is no publishable key and no test mode — an API key is a live spending credential. Keep it in the environment, never in a repository and never in anything a browser downloads.
Reading a result
Responses are plain arrays with the wire's keys, so everything you already know about arrays applies. Two rules explain almost every surprise:
1. Every scalar is wrapped. ['value' => …, 'confidence' => 'low'|'mid'|'high']. Read
$res['result']['total']['value'], not $res['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:
VisionApi\Result covers the common readings, so you rarely have to spell that out:
What you can send
Exactly one file source per call:
A Laravel upload is a stream: ['file' => fopen($request->file('doc')->getRealPath(), 'rb')].
JPEG, PNG, WebP, TIFF and PDF, up to 20 MB and 50 pages. The type is detected from magic bytes — the filename is ignored.
Options
| Key | Default | What it does |
|---|---|---|
preset |
— | A catalog name, or "auto" to let the API classify the file first (free). |
schema |
— | Custom fields, alone or on top of a preset. |
schema_name |
— | A schema saved in your dashboard. Excludes preset and schema. |
pages |
all | PDF page selection, e.g. "1-3,7". You pay for selected pages only. |
language_hint |
auto | ISO 639-1 code, e.g. "es". |
detail |
"standard" |
"high" renders pages at higher resolution. Same cost, slower. |
output |
"json" |
"text" returns raw OCR text instead of fields. |
include_raw_text |
false |
Adds full_text, the whole transcription, alongside result. |
min_confidence |
"low" |
Fields below the level come back null, with confidence preserved. |
Custom fields
A schema is a flat array: each key is a field name, each value describes what to extract. It is compiled before any credit moves, so a bad schema costs nothing.
Field names must match ^[a-z][a-z0-9_]{0,63}$. Types are string (default), number,
boolean, date, array and object. A custom name that collides with a preset field is
a 422 schema_field_conflict — rename it, or use the preset's own field.
Descriptions are the prompt. "The invoice number exactly as printed, without the #"
extracts better than "invoice number". Say what to do when the value is missing or
ambiguous if it matters.
Reuse a combination by saving it:
Picking a preset
28 presets ship with the API. Fetch the catalog rather than hardcoding field names from memory — presets are versioned, and the catalog is the source of truth:
Three ways to choose:
detect reads page 1 only, so an image and a 300-page PDF cost the same, and it is metered
in batches rather than per call: most calls report credits_used 0 and an occasional one
carries the charge. See pricing for the rate.
Questions instead of fields
Up to 5 questions about one file, priced exactly like an extraction. The questions themselves are free.
Long jobs: async and webhooks
Synchronous requests are killed at 60 seconds with a 504 sync_timeout. Anything that
might run longer — a long PDF, detail: "high", a batch — belongs on the queue.
Results stay retrievable for 7 days; after that getTask throws ResultExpiredException
(metadata survives, the payload does not).
Verifying a delivery
Deliveries are signed. Verify over the raw bytes before parsing — a re-serialized body has different bytes and will not match.
Webhook::verify rejects a bad signature, a malformed header and a timestamp more than 5
minutes old, and accepts a delivery if any v1= part matches — which is what makes a
secret rotation seamless. Get the secret from
https://app.visionapi.io/dashboard/webhooks. Failed deliveries retry at +1 m, +5 m,
+15 m and +40 m, then stop.
Errors
Every failure throws a subclass of VisionApi\Exception\ApiException carrying the HTTP
status, the stable errorCode, and whatever details the endpoint attached. Catch the
class you mean, or switch on errorCode — never on the message text, which is prose and
changes.
| Class | HTTP | Codes |
|---|---|---|
InvalidRequestException |
400 | invalid_request |
AuthenticationException |
401 | invalid_api_key, unauthorized |
InsufficientCreditsException |
402 | insufficient_credits — with required() / available() |
PermissionDeniedException |
403 | forbidden, email_not_verified |
NotFoundException |
404 | task_not_found, schema_not_found |
ConflictException |
409 | conflict |
ResultExpiredException |
410 | result_expired |
PayloadTooLargeException |
413 | file_too_large, page_limit_exceeded |
UnsupportedTypeException |
415 | unsupported_type |
UnprocessableException |
422 | pdf_encrypted, invalid_page_selection, invalid_schema, schema_field_conflict, too_many_questions |
RateLimitException |
429 | rate_limited — with retryAfter(); also too_many_tasks, the per-plan async concurrency cap, which clears when one of your own tasks finishes rather than on a timer |
InternalException |
500 | internal_error — with $requestId |
ProviderException |
502 | provider_error |
SyncTimeoutException |
504 | sync_timeout |
UsageException (bad arguments), ConnectionException / TimeoutException (the request
never got a response) and TaskFailedException / TaskTimeoutException come from the
client itself.
Retries and idempotency
The client retries 429, 500, 502 and network failures — three attempts by default, with the
server's own Retry-After honored on 429 and exponential backoff with jitter elsewhere.
Input errors and insufficient_credits are never retried, because they cannot succeed.
Every billable POST is sent with a generated Idempotency-Key, so a retried upload replays
the first response instead of paying twice. Supply your own when the caller may retry — a
queued job that re-runs, a webhook that redelivers — because a fresh process generates a
fresh key:
Reusing a key with a different payload throws ConflictException, which is the mechanism
working: it means the key already stands for something else.
Configuration
Every method takes per-call idempotency_key and timeout in its params array.
Laravel
Account and usage
Usage history is metadata only — never the file, never the extracted values. Uploaded files are never retained: a synchronous request holds yours in memory for the length of the call, and an async request stages it only until the worker finishes with it.
Limits
Same for everyone:
| Limit | Value |
|---|---|
| Max file size | 20 MB |
| Max PDF pages per request | 50 |
| Sync request timeout | 60 s |
Per plan:
| Limit | Free | Starter | Growth | Pro | Scale |
|---|---|---|---|---|---|
| Requests per minute, per key | 10 | 60 | 120 | 300 | 600 |
| Burst capacity | 20 | 120 | 240 | 600 | 1,200 |
| Concurrent async tasks | 1 | 4 | 8 | 16 | 32 |
| Active API keys per account | 1 | 5 | 10 | 20 | 50 |
| Saved schemas | 3 | 10 | 25 | 100 | unlimited |
Max questions per ask |
5 | 5 | 5 | 10 | 10 |
The rate-limit bucket is per API key, not per account — splitting a workload across
keys splits the limit too. The concurrency cap is per account and does not split that way:
over it, an async submission answers 429 too_many_tasks and is charged nothing.
Higher limits on paid plans: https://visionapi.io/pricing.
Examples
Runnable scripts in examples/:
| File | What it shows |
|---|---|
analyze.php |
The smallest useful call, and how to read the result |
custom_schema.php |
Custom fields, line-item injection, saved schemas |
detect_then_analyze.php |
Routing a mixed inbox before spending on extraction |
async_batch.php |
A folder of long PDFs, queued and collected |
webhook.php |
A verified receiver, framework-free |
ask.php |
Visual Q&A and the verdict field |
Development
Contributing
Issues and pull requests are welcome at https://github.com/devrobotlabs/visionapi-php. For anything about the API itself — a preset, a limit, an error code — https://support.visionapi.io reaches the team faster.
License
MIT © Vision API
All versions of visionapi-php with dependencies
ext-curl Version *
ext-json Version *