SDK PHP

composer require hinow-ai/hinow-ai

export HINOW_API_KEY="hi_sua_chave_aqui"

<?php

require 'vendor/autoload.php';

use Hinow\Hinow;

// With no arguments, the client reads the key from HINOW_API_KEY.
$client = new Hinow();

$answer = $client->chat->completions->create([
    'model' => 'hinow/himax',
    'messages' => [
        ['role' => 'system', 'content' => 'You answer in English.'],
        ['role' => 'user', 'content' => 'What is an API? Answer in one paragraph.'],
    ],
]);

echo $answer['choices'][0]['message']['content'], "\n";

// What it cost, in tokens.
$uso = $answer['usage'];
echo "\ninput: {$uso['prompt_tokens']} · output: {$uso['completion_tokens']}\n";

<?php

require 'vendor/autoload.php';

use Hinow\Hinow;

$client = new Hinow();

$stream = $client->chat->completions->createStream([
    'model' => 'hinow/hinova',
    'messages' => [
        ['role' => 'user', 'content' => 'Write three lines about the sea at dawn.'],
    ],
]);

foreach ($stream as $chunk) {
    // Note the "delta": each chunk carries the new fragment, not the whole answer.
    echo $chunk['choices'][0]['delta']['content'] ?? '';
    flush();
}

echo "\n";

<?php

require 'vendor/autoload.php';

use Hinow\Hinow;

$client = new Hinow();

// Answers on the spot: there is no job to follow.
$search = $client->tools->search('best beaches in northeast Brazil', 'search', [
    'country' => 'br',
    'lang' => 'pt-br',
]);

foreach ($search['results'] as $item) {
    echo "{$item['position']}. {$item['title']}\n";
    echo "   {$item['url']}\n";
}

printf("\n%d results · US$ %.3f\n", count($search['results']), $search['cost']);

<?php

require 'vendor/autoload.php';

use Hinow\Hinow;

$client = new Hinow();

// The crawl takes a while, so it runs as a job. This method waits for you.
$job = $client->tools->websiteContactsAndWait(['https://www.mongodb.com'], [
    'maxDepth' => 2,
    'maxLinksPerPage' => 10,
]);

printf(
    "status: %s · US$ %.3f%s\n\n",
    $job['status'],
    $job['cost'],
    !empty($job['cached']) ? ' (from cache)' : ''
);

// Each item carries the type, the value and the exact page it was found on.
foreach ($job['result']['items'] as $item) {
    $onde = $item['sourceUrl'];

    if ($item['type'] === 'email') {
        echo "e-mail    {$item['value']}\n          em {$onde}\n";
    } elseif ($item['type'] === 'phone') {
        echo "telefone  {$item['value']}\n          em {$onde}\n";
    } else {
        echo "{$item['platform']}  {$item['url']}\n";
    }
}

<?php

require 'vendor/autoload.php';

use Hinow\Hinow;

$client = new Hinow();

// Your real function: an array here, just for the example.
function getOrder(string $code): array
{
    $orders = [
        'A-1001' => ['status' => 'delivered', 'delivered' => '2026-08-02'],
        'A-1002' => ['status' => 'in transit', 'estimated' => '2026-08-12'],
    ];

    return $orders[$code] ?? ['error' => 'order not found'];
}

// 1. The assistant: model, instructions and the functions it may call.
$assistant = $client->beta->assistants->create([
    'model' => 'hinow/himax',
    'name' => 'Support',
    'instructions' => 'You answer questions about orders. Check the tool before stating any status.',
    'tools' => [[
        'type' => 'function',
        'function' => [
            'name' => 'get_order',
            'description' => 'Look up an order by its code.',
            'parameters' => [
                'type' => 'object',
                'properties' => [
                    'code' => ['type' => 'string', 'description' => 'Order code, e.g. A-1001'],
                ],
                'required' => ['code'],
            ],
        ],
    ]],
]);

// 2. The conversation and the question.
$thread = $client->beta->threads->create();
$client->beta->threads->messages->create($thread['id'], 'Has order A-1002 arrived?');

// 3. Run it and wait.
$run = $client->beta->threads->runs->createAndPoll($thread['id'], $assistant['id']);

// 4. While the model asks for functions, run them and hand the result back.
while ($run['status'] === 'requires_action') {
    $outputs = [];

    foreach ($run['required_action']['submit_tool_outputs']['tool_calls'] as $call) {
        $args = json_decode($call['function']['arguments'], true);
        echo "-> the model called {$call['function']['name']}({$args['code']})\n";

        $outputs[] = [
            'tool_call_id' => $call['id'],
            'output' => json_encode(getOrder($args['code'])),
        ];
    }

    $client->beta->threads->runs->submitToolOutputs($thread['id'], $run['id'], $outputs);
    $run = $client->beta->threads->runs->poll($thread['id'], $run['id']);
}

// 5. The final answer is the last message on the thread.
$messages = $client->beta->threads->messages->list($thread['id'], ['order' => 'desc', 'limit' => 1]);
echo "\n", $messages['data'][0]['content'][0]['text']['value'], "\n";

$client->beta->assistants->delete($assistant['id']);

<?php

require 'vendor/autoload.php';

use Hinow\Hinow;

$client = new Hinow();

// 1. Upload the document.
$file = $client->files->create('returns-policy.txt', 'assistants');
echo "file: {$file['id']} ({$file['bytes']} bytes)\n";

// 2. Create the store and attach the file to it.
$base = $client->vectorStores->create(['name' => 'Support base']);
$client->vectorStores->files->create($base['id'], $file['id']);
echo "store: {$base['id']}\n";

// 3. Indexing is asynchronous. Searching before it finishes returns nothing
//    resultado, sem error nenhum — por isso vale esperar.
do {
    sleep(2);
    $state = $client->vectorStores->files->retrieve($base['id'], $file['id']);
    echo "indexing: {$state['status']}\n";
} while ($state['status'] === 'in_progress');

// 4. Search by meaning, not by exact word.
$hits = $client->rag->search('How many days do I have to return an item?', [
    'rag_id' => $base['id'],
    'top_k' => 3,
]);

echo "\n";
foreach ($hits['results'] as $achado) {
    printf("%.2f  %s\n", $achado['score'], $achado['source']);
    echo '      ', str_replace("\n", ' ', mb_substr($achado['text'], 0, 120)), "…\n";
}

<?php

require 'vendor/autoload.php';

use Hinow\Hinow;
use Hinow\AuthenticationException;
use Hinow\NotFoundException;
use Hinow\RateLimitException;
use Hinow\InvalidRequestException;
use Hinow\ConnectionException;
use Hinow\ApiException;

$client = new Hinow();

try {
    $client->chat->completions->create([
        'model' => 'himax',  // the hinow/ prefix is missing
        'messages' => [['role' => 'user', 'content' => 'Olá']],
    ]);
} catch (AuthenticationException $e) {
    echo "Invalid or expired key. Check HINOW_API_KEY.\n";
} catch (NotFoundException $e) {
    echo "Not found: {$e->getMessage()}\n";
} catch (InvalidRequestException $e) {
    echo "Invalid request: {$e->getMessage()}\n";
} catch (RateLimitException $e) {
    echo "Rate limited. The SDK already retried; wait a moment.\n";
} catch (ConnectionException $e) {
    // Nothing reached the API, so nothing was charged.
    echo "Sem answer da API: {$e->getMessage()}\n";
} catch (ApiException $e) {
    // Safety net: any other error the API reported.
    echo "Error {$e->status}: {$e->getMessage()}\n";
}

<?php

require 'vendor/autoload.php';

use Hinow\Hinow;

$client = new Hinow();

// Account credit, in US dollars.
$balance = $client->getBalance();
printf("balance: US$ %.2f\n\n", $balance['balance']);

// One specific model. The id is namespaced: hinow/himax, not himax.
$model = $client->models->retrieve('hinow/himax');
echo "{$model['name']} ({$model['id']})\n";
echo 'categories: ', implode(', ', $model['category']), "\n";

use Hinow\Hinow;

$client = new Hinow(
    apiKey: getenv('HINOW_API_KEY'),   // ou deixe em branco e use a variável
    baseUrl: 'https://api.hinow.ai',   // ou HINOW_BASE_URL
    timeout: 120,                      // segundos
    maxRetries: 2,                     // repete 429 e 5xx
);