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

composer require visionapi/visionapi-php

PHP 8.1+, with ext-curl and ext-json. No package dependencies.

Quick start

use VisionApi\Client;

$vision = new Client(); // reads $_ENV['VISION_API_KEY']

$res = $vision->analyze(['file' => 'invoice.pdf', 'preset' => 'invoice']);

echo $res['result']['invoice_id']['value'];  // 'A-10422'
echo $res['result']['total']['value'];       // 1284.5, or null if the invoice has no total
echo $res['credits_used'], $res['credits_remaining'];

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:

[
  'invoice_id' => ['value' => 'A-10422', 'confidence' => 'high'],
  'carrier'    => ['value' => null,      'confidence' => 'low'],
  'line_item'  => [
    ['description' => ['value' => 'Widget', 'confidence' => 'high'],
     'quantity'    => ['value' => 2,        'confidence' => 'high'],
     'amount'      => ['value' => 25.0,     'confidence' => 'mid']],
  ],
]

VisionApi\Result covers the common readings, so you rarely have to spell that out:

use VisionApi\Result;

Result::unwrap($res['result']);
// ['invoice_id' => 'A-10422', 'carrier' => null, 'line_item' => [['description' => 'Widget', …]]]

Result::unwrap($res['result'], dropNull: true);   // only what was actually found
Result::value($res['result'], 'total', 0);        // 1284.5, or 0 when absent
Result::rows($res['result'], 'line_item');        // [] when the invoice has no lines
Result::present($res['result']);                  // ['invoice_id', 'total', 'line_item']
Result::missing($res['result']);                  // ['carrier', …]
Result::belowConfidence($res['result'], 'high');  // fields to route to a human

What you can send

Exactly one file source per call:

$vision->analyze(['file' => 'invoice.pdf', 'preset' => 'invoice']);           // a path
$vision->analyze(['file' => fopen('invoice.pdf', 'rb'), …]);                  // an open stream
$vision->analyze(['file' => $bytes, …]);                                      // raw bytes
$vision->analyze(['file' => ['scan.png', $bytes], …]);                        // bytes + a name
$vision->analyze(['file_url' => 'https://example.com/invoice.pdf', …]);       // a public URL
$vision->analyze(['file_base64' => $encoded, …]);                             // "data:" prefix optional

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.

$res = $vision->analyze([
    'file' => 'invoice.pdf',
    'preset' => 'invoice',
    'schema' => [
        // Plain form — the string is the description, type defaults to string.
        'machine_serial' => 'Serial number of the machine being invoiced, without the "SN:" prefix',

        // Typed form.
        'total_net' => ['type' => 'number', 'description' => 'Total before tax'],
        'signed_on' => ['type' => 'date', 'description' => 'Date the contract was signed'],

        // Reserved key: injects fields into every row of the preset's line-item array.
        'line_item' => ['lot_number' => 'The lot number printed on the line, if present'],
    ],
]);

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:

$vision->createSchema('our-invoices', 'invoice', ['machine_serial' => '…']);
$vision->analyze(['file' => 'invoice.pdf', 'schema_name' => 'our-invoices']);

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:

foreach ($vision->presets() as $preset) {          // no API key required
    echo "{$preset['name']} ({$preset['kind']}) — {$preset['field_count']} fields\n";
}

$invoice = $vision->preset('invoice');
array_column($invoice['fields'], 'name');

Three ways to choose:

// 1. You know what it is.
$vision->analyze(['file' => 'receipt.jpg', 'preset' => 'receipt']);

// 2. You don't, and you want the data anyway. Classification is free.
$res = $vision->analyze(['file' => 'unknown.pdf', 'preset' => 'auto']);
$res['detection']['preset'];        // what ran
$res['detection']['fallback'];      // true = "shape unknown", not a match
$res['detection']['alternatives'];  // the rest of the ranking, best first

// 3. The *type* is the decision — routing a mixed inbox, or refusing to spend
//    on a 40-page PDF until you know what it is. Far cheaper than extracting.
$guess = $vision->detect(['file' => 'unknown.pdf']);
if (!$guess['fallback']) {
    $vision->analyze(['file' => 'unknown.pdf', 'preset' => $guess['recommended']]);
}

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.

$res = $vision->ask([
    'file' => 'photo.jpg',
    'questions' => ['Is there a dog in the image?', 'How many people are visible?'],
]);

foreach ($res['answers'] as $answer) {
    match ($answer['verdict']) {
        'yes', 'no' => handle($answer['verdict']),
        'uncertain' => flagForReview($answer),  // the image does not settle it — a real answer
        'n/a'       => print($answer['answer']), // it wasn't a yes/no question
    };
}

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.

// Submit, then poll. waitForTask handles the loop and the failure case.
$task = $vision->analyzeAndWait([
    'file' => 'contract-80-pages.pdf',
    'preset' => 'contract',
    'pages' => '1-50',
    'poll_interval' => 2.0,
    'max_wait' => 900.0,
    'on_poll' => fn (array $t) => Log::info($t['status']),
]);

// Or submit and walk away — the result comes to you.
$ref = $vision->analyzeAsync([
    'file' => 'contract.pdf',
    'preset' => 'contract',
    'webhook_url' => 'https://yourapp.com/hooks/vision',
]);

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.

use VisionApi\Webhook;
use VisionApi\Exception\WebhookSignatureException;

// Laravel
public function __invoke(Request $request)
{
    try {
        $event = Webhook::verify(
            $request->getContent(),                       // the raw body, untouched
            $request->header('X-Vision-Signature'),
            config('services.vision.webhook_secret')
        );
    } catch (WebhookSignatureException) {
        return response()->noContent(400);                // never parse an unverified body
    }

    ProcessVisionResult::dispatch($event);                // ack fast, work afterwards
    return response()->noContent(202);                    // any 2xx is success
}

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.

use VisionApi\Exception\{ApiException, InsufficientCreditsException, SyncTimeoutException, UnsupportedTypeException};

try {
    $res = $vision->analyze(['file' => 'scan.pdf', 'preset' => 'invoice']);
} catch (InsufficientCreditsException $e) {
    alertOps("needs {$e->required()}, has {$e->available()}");  // never retried — it cannot succeed
} catch (SyncTimeoutException) {
    $task = $vision->analyzeAndWait(['file' => 'scan.pdf', 'preset' => 'invoice']);
} catch (UnsupportedTypeException) {
    quarantine('not an image or a PDF');
} catch (ApiException $e) {
    Log::error("vision {$e->errorCode} ({$e->status}) request_id={$e->requestId}");
}

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:

$vision->analyze(['file' => $path, 'preset' => 'invoice', 'idempotency_key' => "invoice-{$invoice->id}"]);

Reusing a key with a different payload throws ConflictException, which is the mechanism working: it means the key already stands for something else.

Configuration

$vision = new Client([
    'api_key' => $_ENV['VISION_API_KEY'],   // default: $_ENV['VISION_API_KEY']
    'base_url' => 'https://api.visionapi.io', // default; override for a self-hosted deployment
    'timeout' => 120.0,                      // per request, seconds
    'max_retries' => 3,
    'auto_idempotency' => true,
    'headers' => ['X-Trace-Id' => $traceId], // sent on every request
    'transport' => $myTransport,             // swap the HTTP layer (tests, proxies, metrics)
]);

Every method takes per-call idempotency_key and timeout in its params array.

Laravel

// config/services.php
'vision' => [
    'key' => env('VISION_API_KEY'),
    'webhook_secret' => env('VISION_WEBHOOK_SECRET'),
],

// AppServiceProvider::register()
$this->app->singleton(Client::class, fn () => new Client(['api_key' => config('services.vision.key')]));

Account and usage

$credits = $vision->credits();
// $credits['buckets'] are spent in order: subscription → rollover → pack → welcome

foreach ($vision->eachRequest(limit: 100) as $record) {
    echo "{$record['created_at']} {$record['endpoint']} {$record['preset']} {$record['credits_used']}\n";
}

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

export VISION_API_KEY=sk_live_…
php examples/analyze.php invoice.pdf

Development

composer install
composer test      # offline: the transport is stubbed, no key and no network needed
composer analyse   # phpstan level 6
composer lint

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.

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
.github/workflows		.github/workflows
examples		examples
src		src
tests		tests
.gitignore		.gitignore
.php-cs-fixer.dist.php		.php-cs-fixer.dist.php
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
composer.json		composer.json
phpunit.xml		phpunit.xml

Navigation Menu

Repository files navigation

Vision API — PHP client

Install

Quick start

Reading a result

What you can send

Options

Custom fields

Picking a preset

Questions instead of fields

Long jobs: async and webhooks

Verifying a delivery

Errors

Retries and idempotency

Configuration

Laravel

Account and usage

Limits

Examples

Development

Contributing

License

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

Vision API — PHP client

Install

Quick start

Reading a result

What you can send

Options

Custom fields

Picking a preset

Questions instead of fields

Long jobs: async and webhooks

Verifying a delivery

Errors

Retries and idempotency

Configuration

Laravel

Account and usage

Limits

Examples

Development

Contributing

License

About

Topics

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages