README

Official PHP client for the Gisoo AI API. Gisoo is an OpenAI-compatible gateway to many chat, image, speech, video and music models, paid in a single balance and reachable from Iranian servers without a VPN.

PHP 8.1+, one runtime dependency (Guzzle).
Chat Completions with streaming (a PHP generator), Responses API, embeddings, images, text to speech, transcription and translation, music, video jobs, model list, balance and usage.
Typed exceptions for authentication, insufficient balance (402), rate limit (429), invalid request, server and connection errors.
Laravel 10, 11 and 12: auto-discovered service provider, config/gisoo.php and a Gisoo facade.

Full API documentation: https://gisoo.pro/docs - OpenAPI spec: https://gisoo.pro/api/v1/openapi.json

Install

composer require gisoo/gisoo-php

Quick start (plain PHP)

use Gisoo\Gisoo;

$gisoo = Gisoo::client(getenv('GISOO_API_KEY')); // sk-gisoo-v1-...

$reply = $gisoo->chat()->create([
    'model' => 'MODEL_ID', // pick one from $gisoo->models()
    'messages' => [
        ['role' => 'user', 'content' => 'Say hello in Persian.'],
    ],
]);

echo $reply['choices'][0]['message']['content'];

List models (type, capabilities and pricing) and check your balance. Both calls are free:

$models = $gisoo->models(['type' => 'chat']);
$account = $gisoo->me();

Streaming

foreach ($gisoo->chat()->streamText(['model' => 'MODEL_ID', 'messages' => $messages]) as $piece) {
    echo $piece;
    flush();
}

// or the raw chunks (tool calls, finish_reason, usage):
foreach ($gisoo->chat()->stream(['model' => 'MODEL_ID', 'messages' => $messages]) as $chunk) {
    // $chunk['choices'][0]['delta']
}

Other endpoints

$gisoo->embeddings()->create(['model' => 'EMBEDDING_MODEL', 'input' => 'text']);
$gisoo->images()->generate(['model' => 'IMAGE_MODEL', 'prompt' => 'a red fox']);       // data[].b64_json
file_put_contents('hello.mp3', $gisoo->audio()->speech(['model' => 'TTS_MODEL', 'input' => 'Hello', 'voice' => 'VOICE']));
$gisoo->audio()->transcribe('/path/audio.mp3', ['model' => 'STT_MODEL', 'language' => 'fa']);
$gisoo->audio()->music(['model' => 'MUSIC_MODEL', 'prompt' => 'calm piano']);

$job = $gisoo->videos()->create(['model' => 'VIDEO_MODEL', 'prompt' => 'waves at sunset']);
$status = $gisoo->videos()->retrieve($job['id']);   // poll until finished
file_put_contents('clip.mp4', $gisoo->videos()->content($job['id']));

Every method takes the parameters documented in the OpenAPI spec as an array and returns the decoded JSON as an array.

Laravel

The package is auto-discovered. Add to .env:

GISOO_API_KEY=sk-gisoo-v1-...
# Optional, see "Servers in Iran" below:
# GISOO_BASE_URL=https://ir.gisoo.pro/api/v1

Optionally publish the config: php artisan vendor:publish --tag=gisoo-config.

use Gisoo\Laravel\Facades\Gisoo;

$text = Gisoo::chat()->create([
    'model' => 'MODEL_ID',
    'messages' => [['role' => 'user', 'content' => 'Hello']],
])['choices'][0]['message']['content'];

return response()->stream(function () {
    foreach (Gisoo::chat()->streamText(['model' => 'MODEL_ID', 'messages' => [['role' => 'user', 'content' => 'Tell a story']]]) as $piece) {
        echo $piece;
        ob_flush();
        flush();
    }
}, 200, ['Content-Type' => 'text/plain; charset=utf-8', 'X-Accel-Buffering' => 'no']);

You can also type-hint Gisoo\Gisoo in a constructor and let the container inject it.

Servers in Iran

Hosts inside Iran that cannot reach gisoo.pro should use the dedicated address. Set it per client or with GISOO_BASE_URL:

$gisoo = Gisoo::client($key, ['base_url' => Gisoo::IRAN_BASE_URL]); // https://ir.gisoo.pro/api/v1

Guide: https://gisoo.pro/docs/iran-servers

Options and errors

Gisoo::client($key, [
    'base_url' => 'https://gisoo.pro/api/v1',
    'timeout' => 120,          // seconds
    'connect_timeout' => 15,
    'headers' => ['X-Trace' => 'abc'],
]);

use Gisoo\Exceptions\{AuthenticationException, InsufficientBalanceException, RateLimitException, GisooException};

try {
    $gisoo->chat()->create($params);
} catch (InsufficientBalanceException $e) {   // 402: top up your balance
} catch (RateLimitException $e) {              // 429: wait $e->retryAfter seconds
} catch (AuthenticationException $e) {         // 401/403: check the key
} catch (GisooException $e) {                  // anything else; see $e->status, $e->errorCode, $e->body
}

Tests

composer install
vendor/bin/phpunit            # HTTP is mocked, nothing is billed
GISOO_LIVE=1 vendor/bin/phpunit --filter testLiveModels   # optional free GET /models
vendor/bin/phpstan analyse

فارسی

این بسته، کلاینت رسمی PHP و پکیج لاراول برای API هوش مصنوعی گیسو است. API گیسو با OpenAI سازگار است.

composer require gisoo/gisoo-php

در لاراول فقط کلید را در .env بگذارید و از Facade با نام Gisoo یا تزریق Gisoo\Gisoo استفاده کنید:

GISOO_API_KEY=sk-gisoo-v1-...

اگر سرور شما در ایران است و به gisoo.pro وصل نمی‌شود، نشانی پایه را روی https://ir.gisoo.pro/api/v1 بگذارید (GISOO_BASE_URL). راهنما: https://gisoo.pro/docs/iran-servers

مستندات کامل: https://gisoo.pro/docs

License

MIT

gisoo / gisoo-php

Package info

Security

Statistics