API هوش مصنوعی بدون فیلترشکن

API هوش مصنوعی گیسو برای سرورها، هاست‌ها و برنامه‌هایی ساخته شده که در ایران اجرا می‌شوند. برنامهٔ شما فقط به یک نشانی وصل می‌شود، https://ir.gisoo.pro/api/v1، و گیسو درخواست را به سرویس‌دهندهٔ مدل (شرکتی که مدل روی سرورش اجرا می‌شود، مثل OpenAI، Google یا OpenRouter) می‌رساند و پاسخ را برمی‌گرداند. پس روی سرور شما فیلترشکن، پراکسی یا تونل لازم نیست و برای پرداخت هم کارت ارزی نمی‌خواهید.

این صفحه می‌گوید این اتصال چطور کار می‌کند، کدام نشانی را بگذارید، اتصال را از سرور خودتان چطور بیازمایید و اگر وصل نشد، مشکل کجاست.

چرا از ایران کار می‌کند

1. برنامهٔ شما درخواست را به ir.gisoo.pro می‌فرستد

   با همان قالب API شرکت OpenAI (یا Anthropic، برای Claude Code). کلید شما همراه درخواست است.

2. گیسو کلید، اعتبار و محدودیت‌ها را بررسی می‌کند

   اگر چیزی کم باشد، همین‌جا با یک خطای روشن برمی‌گردد و هزینه‌ای کم نمی‌شود.

3. گیسو درخواست را به سرویس‌دهندهٔ مدل می‌رساند

   اتصال به OpenAI، Google، OpenRouter و DeepSeek از سرورهای گیسو انجام می‌شود، نه از سرور شما.

4. پاسخ به برنامهٔ شما برمی‌گردد

   عادی یا جریانی (stream)، با همان قالبی که SDK شما انتظار دارد. هزینهٔ واقعی از اعتبار دلاری حسابتان کم می‌شود.

در بررسی خودمان در مهر ۱۴۰۵، نشانی گیسو از دیتاسنترهایی در تهران، اصفهان، شیراز و قم پاسخ درست داد. شبکه‌ها اما دست ما نیستند و ممکن است روزی یک مسیر تغییر کند؛ برای همین در ادامه آمده است که اتصال را چطور خودتان بیازمایید و اگر قطع شد، چه اطلاعاتی برای ما بفرستید.

نشانی درست برای سرور داخل ایران

• اگر کلیدتان را از نِت اَرز گرفته‌اید، همان کلید و همان اعتبار روی ir.gisoo.pro کار می‌کند؛ حساب در هر دو یکی است.
• برای سرورهای دیتاسنترهای ایرانی و کاربران داخل ایران، نشانی ویژهٔ ایران https://ir.gisoo.pro/api/v1 را پیشنهاد می‌کنیم. نشانی اصلی گیسو gisoo.pro می‌ماند؛ کلید، اعتبار، مدل‌ها و مسیرها در هر دو یکسان‌اند.
• IP را جایی ثبت نکنید و در کد ننویسید؛ همیشه با نام دامنه وصل شوید تا اگر نشانی سرور عوض شد، برنامه‌تان از کار نیفتد.

آزمایش اتصال از سرور شما

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

# 1) Is the address reachable from this server? No key, no cost.
curl -sS -o /dev/null -w "HTTP %{http_code} in %{time_total}s\n" https://ir.gisoo.pro/api/v1/models

# 2) Does a bigger request (about 5 KB) get through? Expect HTTP 401: no key was sent,
#    so nothing is charged, but the whole body reached Gisoo.
printf '{"model":"connectivity-test","messages":[{"role":"user","content":"%s"}]}' "$(head -c 5000 /dev/zero | tr '\0' 'a')" \
  | curl -sS -o /dev/null -w "HTTP %{http_code}\n" -X POST https://ir.gisoo.pro/api/v1/chat/completions \
      -H "Content-Type: application/json" --data-binary @-

# 3) Is your key right, and how much credit is left?
curl -sS https://ir.gisoo.pro/api/v1/me -H "Authorization: Bearer $GISOO_API_KEY"

• دستور اول باید HTTP 200 بدهد. یعنی سرور شما ir.gisoo.pro را پیدا می‌کند و به آن می‌رسد.
• دستور دوم باید HTTP 401 بدهد. ۴۰۱ این‌جا خبر خوب است: درخواست پنج‌کیلوبایتی کامل به گیسو رسید و چون کلیدی همراهش نبود، رد شد.
• دستور سوم موجودی و محدودیت‌های کلیدتان را برمی‌گرداند. اگر این هم درست بود، هر SDK و ابزاری روی این سرور کار می‌کند.

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

در هاست‌های سی‌پنل و دایرک‌ادمین که ترمینال ندارند، این فایل را در پوشهٔ سایت بگذارید، یک بار در مرورگر باز کنید و بعد پاکش کنید. کلید لازم ندارد:

<?php
// gisoo-check.php — upload, open once in the browser, then delete it.
$ch = curl_init('https://ir.gisoo.pro/api/v1/me');
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 30]);
$body = curl_exec($ch);

if (curl_errno($ch)) {
    echo 'cURL error ' . curl_errno($ch) . ': ' . curl_error($ch);   // the table below says what it means
} else {
    echo 'HTTP ' . curl_getinfo($ch, CURLINFO_HTTP_CODE);             // 401 = reached Gisoo (no key was sent)
}

اگر HTTP 401 دیدید، هاست شما به گیسو می‌رسد و افزونهٔ وردپرس یا هر کد PHP دیگری روی آن کار می‌کند.

اگر وصل نشد

کد خطای curl (یا cURL در PHP) می‌گوید اتصال در کدام قدم قطع شده است. هر درخواستی که به سرور گیسو برسد، یک پاسخ HTTP می‌گیرد، حتی وقتی رد شود؛ پس خطایی که هیچ پاسخی همراهش نیست، یعنی درخواست در مسیر شبکه یا روی خود سرور شما مانده است.

اگر باز وصل نشد، در تیکت این‌ها را بفرستید: خروجی کامل curl -sv https://ir.gisoo.pro/api/v1/models -o /dev/null، نام هاست یا دیتاسنتر و این‌که درخواست کوچک جواب می‌گیرد یا نه. کلید را در تیکت ننویسید.

تنظیم‌های پیشنهادی برای سرور ایران

• زمان انتظار کلاینت: گیسو برای پاسخ سرویس‌دهنده تا حدود ۹۰ ثانیه صبر می‌کند. زمان انتظار برنامهٔ خودتان را بیشتر از آن بگذارید (مثلاً ۱۲۰ ثانیه) تا درخواست را زودتر از گیسو رها نکند.
• پاسخ جریانی: برای متن‌های بلند stream: true بفرستید تا خروجی همان لحظه که ساخته می‌شود برسد. اگر پشت nginx خودتان پراکسی می‌کنید، بافر را برای همان مسیر خاموش کنید (proxy_buffering off).
• تلاش دوباره: فقط برای ۴۲۹، خطاهای ۵xx و قطع اتصال، با فاصلهٔ رو به افزایش. خطای ۴xx دیگر با تکرار درست نمی‌شود.
• کلید: در متغیر محیطی یا فایل تنظیم بیرون از پوشهٔ عمومی سایت. برای هر سرور یک کلید با سقف هزینه بسازید و اگر IP سرور ثابت است، آن را در فهرست IP مجاز همان کلید بگذارید.

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://ir.gisoo.pro/api/v1",
    api_key=os.environ["GISOO_API_KEY"],
    timeout=120,      # longer than Gisoo's own wait for the model provider
    max_retries=3,    # 429, 5xx and dropped connections only
)

چه چیزهایی از همین نشانی کار می‌کند

همهٔ بخش‌های وب‌سرویس از همین نشانی می‌آیند: گفت‌وگو با مدل‌های GPT، Claude، Gemini، DeepSeek و بقیه، امبدینگ، ساخت تصویر، گفتار و متن، ویدیو، موسیقی، Messages API برای Claude Code و سرور MCP. برای هر ابزار رایج هم راهنمای اتصال جدا داریم.

پرسش‌های پرتکرار

قدم بعدی