PHPackages                             jazz-max/yandex-ai-laravel - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. jazz-max/yandex-ai-laravel

ActiveLibrary[Utility & Helpers](/categories/utility)

jazz-max/yandex-ai-laravel
==========================

Laravel SDK for Yandex AI Studio — Responses API, Vision OCR, Embeddings

v1.2.0(1mo ago)08MITPHPPHP ^8.2

Since Apr 12Pushed 1mo agoCompare

[ Source](https://github.com/jazz-max/yandex-ai-laravel)[ Packagist](https://packagist.org/packages/jazz-max/yandex-ai-laravel)[ RSS](/packages/jazz-max-yandex-ai-laravel/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (4)Versions (6)Used By (0)

Yandex AI Laravel SDK
=====================

[](#yandex-ai-laravel-sdk)

Laravel SDK for [Yandex AI Studio](https://aistudio.yandex.ru/) — text generation (Responses API), Vision OCR, and Embeddings.

Installation
------------

[](#installation)

```
composer require jazz-max/yandex-ai-laravel
```

Publish config:

```
php artisan vendor:publish --tag=yandex-ai-config
```

Add to `.env`:

```
YANDEX_AI_API_KEY=your-api-key
YANDEX_AI_FOLDER_ID=your-folder-id
```

Quick Start
-----------

[](#quick-start)

```
use JazzMax\YandexAi\Facades\YandexAi;

// Text generation
$response = YandexAi::responses()->create([
    'model'        => 'yandexgpt-5-lite',
    'instructions' => 'You are a helpful assistant.',
    'input'        => 'Hello!',
]);
echo $response->text;

// OCR
$result = YandexAi::vision()->recognizeText(
    file_get_contents('photo.jpg')
);
echo $result->text();

// Embeddings
$vector = YandexAi::embeddings()->embedQuery('search query');
```

API Clients
-----------

[](#api-clients)

### Responses API

[](#responses-api)

```
$client = YandexAi::responses();
```

MethodDescription`create(array $params)`Text generation`stream(array $params, Closure $onDelta)`Streaming generation`continue(string $prevId, array $input)`Multi-turn dialog`submitToolOutput(string $prevId, string $callId, string $output)`Function calling follow-up`createBackground(array $params)`Background async task`retrieve(string $id)`Get background task status`poll(string $id, int $timeout)`Poll until complete`formatModel(string $model)`Add `gpt://folder_id/` prefix`supportsReasoning(string $model)`Check Pro model`calculateCostRub(...)`Cost in RUB### Vision OCR

[](#vision-ocr)

```
$client = YandexAi::vision();
```

MethodDescription`recognizeText(string $data, OcrModel $model)`Sync image OCR`recognizeDocument(string $pdfData, OcrModel $model)`Async PDF OCRAvailable models (`OcrModel` enum):

- `Page` — general text
- `PageColumnSort` — multi-column layouts
- `Handwritten` — handwriting (ru/en only)
- `Table` — table extraction (ru/en only)
- `Markdown` / `MathMarkdown` — structured output
- `Passport` — Russian passport fields
- `DriverLicenseFront` / `DriverLicenseBack` — driver license
- `VehicleRegistrationFront` / `VehicleRegistrationBack` — vehicle registration
- `LicensePlates` — license plate numbers

### Embeddings

[](#embeddings)

```
$client = YandexAi::embeddings();
```

MethodDescription`embedDocument(string $text)`Document vector (for indexing)`embedQuery(string $text)`Query vector (for searching)`cosineSimilarity(array $a, array $b)`Vector similarityFunction Calling
----------------

[](#function-calling)

```
use JazzMax\YandexAi\Tools\FunctionTool;

$tools = [
    FunctionTool::make('get_weather', 'Get weather for a city.', [
        'type'       => 'object',
        'properties' => [
            'city' => ['type' => 'string', 'description' => 'City name'],
        ],
        'required' => ['city'],
    ]),
];

$response = YandexAi::responses()->create([
    'model' => 'yandexgpt-5-lite',
    'input' => 'Weather in Moscow?',
    'tools' => $tools,
]);

if ($response->hasFunctionCall()) {
    $call = $response->functionCall;

    // Check if function call was extracted from text (fallback parser)
    if ($response->isFallbackFunctionCall) {
        // Model returned tool call as text — consider shortening tool descriptions
    }

    // Execute function, then submit result:
    $final = YandexAi::responses()->submitToolOutput(
        $response->id, $call['id'], '{"temp": 15}'
    );
}
```

> **Note:** Yandex models sometimes return function calls as plain text instead of proper `function_call` items. The SDK includes a fallback parser that automatically extracts them. Check `$response->isFallbackFunctionCall` to detect this. Disable via `YANDEX_AI_FUNCTION_CALL_FALLBACK=false`.

Known Gotchas
-------------

[](#known-gotchas)

See [docs/GOTCHAS.md](docs/GOTCHAS.md) for production-tested pitfalls:

1. **Tool descriptions must be short** (< 15 words, English) or models write calls as text
2. **Never use empty `properties`** — always include a dummy property
3. **Auth header is `Api-Key`**, not `Bearer`
4. **Models require URI format**: `gpt://folder_id/model`
5. **Only `gemma-3-27b-it` supports images**, and only via base64
6. **Prices are RUB per 1000 tokens**, not USD per 1M
7. **Cached tokens cost 50%** of prompt price
8. **Async OCR returns JSON Lines**, not JSON array
9. **`handwritten`/`table` models only support ru/en**

Configuration
-------------

[](#configuration)

All options in `config/yandex-ai.php`:

KeyDefaultDescription`api_key`—API key`folder_id`—Cloud folder ID`base_url``https://ai.api.cloud.yandex.net/v1`API base URL`ocr_base_url``https://ocr.api.cloud.yandex.net/ocr/v1`OCR API URL`timeout``120`HTTP timeout (seconds)`proxy``null`HTTP proxy URL`default_model``yandexgpt-5-lite`Default generation model`pricing`—RUB per 1000 tokens per model`ocr_pricing`—RUB per image per OCR modelExamples
--------

[](#examples)

See [examples/](examples/) directory:

- `simple_request.php` — basic generation
- `dialog.php` — multi-turn conversation
- `streaming.php` — streaming output
- `function_calling.php` — tool use
- `reasoning.php` — Pro model reasoning
- `vision_with_gpt.php` — image analysis
- `vision_ocr.php` — OCR recognition
- `vision_ocr_async.php` — async PDF OCR
- `embeddings.php` — semantic search
- `background.php` — background tasks

Claude Code Skill
-----------------

[](#claude-code-skill)

If you use [Claude Code](https://claude.ai/code), install the companion skill ([jazz-max/yandex-ai-laravel-skill](https://github.com/jazz-max/yandex-ai-laravel-skill)) for expert guidance on this SDK:

```
npx skills add jazz-max/yandex-ai-laravel-skill
```

The skill provides full API reference, code examples, and knows all Yandex API gotchas.

Example prompts that activate the skill:

> Add YandexGPT text generation to my Laravel app with streaming support

> Build a document recognition feature using Yandex Vision OCR for passports and driver licenses

> Implement semantic search with Yandex Embeddings and cosine similarity

> Set up function calling with Yandex AI Studio in my Laravel project

> Подключи Yandex AI Studio к моему Laravel-проекту и сделай artisan-команду для генерации текста через YandexGPT

> Добавь распознавание документов через Yandex Vision OCR с поддержкой паспортов и водительских удостоверений

> Реализуй семантический поиск по базе статей с помощью Yandex Embeddings

License
-------

[](#license)

MIT

###  Health Score

39

—

LowBetter than 84% of packages

Maintenance89

Actively maintained with recent releases

Popularity4

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity50

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

5

Last Release

56d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/ad66a890dfb8f97a8a07b8f1d6586cef7115393756a61e5e9ccbfb6492c857ba?d=identicon)[jazz-max](/maintainers/jazz-max)

---

Top Contributors

[![jazz-max](https://avatars.githubusercontent.com/u/42142940?v=4)](https://github.com/jazz-max "jazz-max (12 commits)")

---

Tags

laravelaiyandexOCRvisiongptembeddingsyandexgpt

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/jazz-max-yandex-ai-laravel/health.svg)

```
[![Health](https://phpackages.com/badges/jazz-max-yandex-ai-laravel/health.svg)](https://phpackages.com/packages/jazz-max-yandex-ai-laravel)
```

###  Alternatives

[venturedrake/laravel-crm

A free open source CRM built as a package for laravel projects

39910.0k](/packages/venturedrake-laravel-crm)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)