اتصال به API هوش مصنوعی از سرور ایران؛ هاست اشتراکی، سرور مجازی و رفع خطای timeout

چت‌بات سایتتان روی لپ‌تاپ درست جواب می‌دهد، ولی همین که روی هاست ایرانی می‌رود، درخواست به OpenAI یا با خطای unsupported_country_region_territory برمی‌گردد، یا آن‌قدر منتظر می‌ماند که قطع شود. علتش این است که سرویس‌دهنده‌های اصلی درخواست از ایران را نمی‌پذیرند و مسیرهای بین‌المللی از دیتاسنترهای داخل هم همیشه پایدار نیستند. برای اتصال به API هوش مصنوعی از سرور ایران، نشانی پایه را https://gisoo.pro/api/v1 بگذارید. این نشانی برای سرورهای داخل ایران ساخته شده و در بررسی ما از دیتاسنترهای چند شهر جواب داد. قالبش همان OpenAI است و با یک کلید به GPT، Claude، Gemini و DeepSeek می‌رسید.

ساخت کلید، تست اتصال با curl، یک نمونه کد PHP برای هاست اشتراکی و خواندن خطاهای رایج را در ادامه قدم‌به‌قدم می‌خوانید.

چرا سرور ایران مستقیم به OpenAI و گوگل نمی‌رسد

OpenAI، Google و Anthropic فهرست کشورهای پشتیبانی‌شده دارند و ایران در آن نیست. درخواستی که از IP ایران برسد رد می‌شود: OpenAI با کد unsupported_country_region_territory و API گوگل با پیام User location is not supported. حتی اگر حساب و کارت ارزی داشته باشید، سرور داخل ایران همین جواب را می‌گیرد.

مشکل دوم شبکه است. روی شبکهٔ بعضی دیتاسنترهای داخل، اتصال به برخی نشانی‌های خارجی گاهی قطع می‌شود؛ معمولاً درخواست‌های کوچک می‌رسند و درخواست بزرگ‌تر بی‌جواب می‌ماند. نشانی gisoo.pro مستقیم به سرور گیسو وصل می‌شود و گیسو درخواست را از آن‌جا به سرویس‌دهندهٔ مدل می‌رساند.

سه قدم تا اولین پاسخ

1. حساب و اعتبار. در گیسو با شمارهٔ موبایل وارد شوید و اعتبار را شارژ کنید؛ از ۵۰ هزار سکه شروع می‌شود و اشتراک ماهانه ندارد. پیش از اینکه مصرف از ۲ دلار بیشتر شود، یک بار احراز هویت لازم است.
2. پروژه و کلید. در اپ گیسو، بخش «وب‌سرویس و کلیدهای API»، پروژه‌ای به نام سایت یا سرویستان بسازید و کلیدش را بردارید. کلید با sk-gisoo-v1- شروع می‌شود. همان‌جا برایش سقف هزینه بگذارید.
3. نشانی پایه. در کد یا تنظیمات برنامه‌تان، نشانی پایه را https://gisoo.pro/api/v1 بگذارید و کلید را در سربرگ Authorization: Bearer بفرستید.

اگر کلید وب‌سرویس نِت اَرز (sk-ntz-v1-) دارید، همان کلید روی نشانی گیسو هم کار می‌کند؛ اعتبار و فهرست درخواست‌ها یکی است.

تست اتصال با curl، از روی خود سرور

این سه دستور را از ترمینال همان سروری بزنید که برنامه روی آن اجرا می‌شود، نه از کامپیوتر خودتان. اولی کلید نمی‌خواهد و فقط نشان می‌دهد سرور به گیسو می‌رسد:

# 1) Reachability: lists the models, no key needed
curl -sS https://gisoo.pro/api/v1/models | head -c 300

# 2) Key check: balance and limits of the key, no model is called
curl -sS https://gisoo.pro/api/v1/me \
  -H "Authorization: Bearer $GISOO_API_KEY"

# 3) A real request, with a time limit
curl -sS --max-time 120 https://gisoo.pro/api/v1/chat/completions \
  -H "Authorization: Bearer $GISOO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gemini-3.8-flash", "messages": [{"role": "user", "content": "Say hello in Persian."}]}'

اگر دستور اول جواب داد و سومی نه، مشکل از کلید، اعتبار یا خود درخواست است و متن خطا دلیلش را می‌گوید. اگر اولی هم جواب نداد، درخواست به گیسو نمی‌رسد و باید مسیر شبکهٔ سرور را دید.

نمونه کد PHP برای هاست اشتراکی

بیشتر هاست‌های اشتراکی PHP دارند و افزونهٔ cURL روی آن‌ها روشن است. این تابع یک پیام می‌فرستد، زمان انتظار را محدود می‌کند و خطای وب‌سرویس را خوانا برمی‌گرداند:

<?php
function gisoo_chat(string $prompt, string $model = 'gemini-3.8-flash'): string
{
    $ch = curl_init('https://gisoo.pro/api/v1/chat/completions');
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CONNECTTIMEOUT => 10,
        CURLOPT_TIMEOUT => 120,
        CURLOPT_HTTPHEADER => [
            'Authorization: Bearer ' . getenv('GISOO_API_KEY'),
            'Content-Type: application/json',
        ],
        CURLOPT_POSTFIELDS => json_encode([
            'model' => $model,
            'messages' => [['role' => 'user', 'content' => $prompt]],
        ], JSON_UNESCAPED_UNICODE),
    ]);

    $body = curl_exec($ch);
    if ($body === false) {
        $error = 'curl ' . curl_errno($ch) . ': ' . curl_error($ch);
        curl_close($ch);
        throw new RuntimeException($error);
    }
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    $data = json_decode($body, true);
    if ($status !== 200) {
        // e.g. 402 insufficient_credit, 403 ip_not_allowed, 429 rate_limit_exceeded
        throw new RuntimeException($status . ' ' . ($data['error']['code'] ?? '') . ': ' . ($data['error']['message'] ?? $body));
    }

    return $data['choices'][0]['message']['content'];
}

کلید را در متغیر محیطی یا فایل تنظیماتی بیرون از پوشهٔ عمومی سایت (public_html) نگه دارید و هرگز در کد JavaScript صفحه نگذارید؛ هر کسی صفحه را باز کند، کلید را می‌بیند. اگر جواب‌ها بلندند و کاربر منتظر می‌ماند، پاسخ جریانی (Streaming) را به کار ببرید تا متن تکه‌تکه برسد.

اگر جوابی نیامد، کد خطای curl را بخوانید

هر جوابی که از گیسو برسد، یک کد وضعیت HTTP و یک متن JSON با error.code دارد. اگر curl به‌جای این، خطای خودش را داد، یعنی درخواست در راه مانده و کد خطا می‌گوید کجا:

یک نشانهٔ دیگر هم کمک می‌کند. درخواست‌هایی که به گیسو می‌رسند و پذیرفته می‌شوند، در اپ گیسو، بخش «وب‌سرویس و کلیدهای API»، در فهرست درخواست‌ها با وضعیت و هزینه ثبت می‌شوند. اگر درخواستی آن‌جا نیست و curl هم هیچ کد وضعیت HTTPی نگرفته، درخواست به گیسو نرسیده است و باید مسیر سرور را دید؛ عوض کردن IP در فایل hosts این را حل نمی‌کند.

پیش از تماس با میزبان، این‌ها را آماده کنید

میزبان (هاستینگ یا دیتاسنتر) وقتی سریع‌تر کمک می‌کند که داده‌ای دقیق جلویش باشد. همان دستور curl را برای یک نشانی خارجی دیگر هم بزنید، مثلاً https://api.github.com. اگر آن هم جواب نداد، اینترنت بین‌المللی سرور مشکل دارد، نه فقط مسیر یک نشانی. بعد این‌ها را برای میزبان بفرستید:

• خروجی کامل curl -v به gisoo.pro، با ساعت دقیق اجرا؛
• کد خطای curl و مدتی که تا قطع شدن طول کشید؛
• IP خروجی سرور و اینکه درخواست‌های کوچک (مثل فهرست مدل‌ها) جواب می‌گیرند یا نه؛
• اینکه روی سرور پراکسی، تونل یا نرم‌افزار فیلترشکن نصب است یا نه.

خطاهایی که از خود گیسو می‌آید

فهرست کامل کدها و اینکه کدام را دوباره بفرستید در راهنمای خطاهای وب‌سرویس آمده است. درخواستی که پیش از تولید پاسخ خطا بدهد، هزینه‌ای ندارد.

IP مجاز، سقف هزینه و محدودیت‌ها

• فهرست IP مجاز: اختیاری است. اگر آن را برای کلید پر کنید، فقط همان IPها پذیرفته می‌شوند. روی هاست اشتراکی، IPی که درخواست با آن بیرون می‌رود ممکن است با IP سایتتان فرق داشته باشد؛ اگر ip_not_allowed گرفتید، IP خروجی را از میزبان بپرسید.
• سقف هزینه: برای هر کلید سقف هزینه و برای هر پروژه بودجهٔ ماهانه بگذارید. اگر کلید لو برود یا کدی در حلقه گیر کند، خرج از این عدد بالاتر نمی‌رود.
• محدودیت سرعت: پیش‌فرض هر کلید ۶۰ درخواست در دقیقه و هر حساب ۸ درخواست همزمان است. بدنهٔ هر درخواست تا ۲۰ مگابایت پذیرفته می‌شود.
• زمان انتظار: سرویس‌دهنده تا حدود ۹۰ ثانیه فرصت جواب دارد؛ زمان انتظار برنامهٔ خودتان را کمی بیشتر، مثلاً ۱۲۰ ثانیه، بگذارید. اگر PHP روی هاست زمان اجرای کوتاهی دارد (max_execution_time)، کار طولانی را به یک کار زمان‌بندی‌شده (Cron Job) بسپارید.

جزئیات هر کدام و تنظیم تلاش دوباره در کتابخانهٔ OpenAI در مدیریت هزینه و محدودیت‌ها آمده است.

یک قالب برای همهٔ مدل‌های گیسو

وب‌سرویس گیسو با کتابخانه‌های رسمی OpenAI سازگار است؛ در Python، Node.js یا هر زبان دیگری فقط نشانی پایه و کلید را عوض می‌کنید. شناسهٔ مدل‌ها را از GET /models بردارید. ساخت تصویر، تبدیل متن به گفتار، تبدیل گفتار به متن و ساخت ویدیو و موسیقی هم از همین نشانی است و قالب Messages API شرکت Anthropic هم روی آن کار می‌کند. نمونه‌کد Python و Node.js در شروع سریع API هوش مصنوعی گیسو هست. اگر سایتتان وردپرسی است، لازم نیست کد بنویسید: افزونه هوش مصنوعی وردپرس گیسو از اول به همین نشانی وصل است.

اولین قدم: سه دستور curl بالا را روی سرور بزنید. اگر هر سه جواب دادند، نشانی پایهٔ برنامه‌تان را عوض کنید و کار تمام است. ساخت پروژه و کلید API در گیسو