پرش به محتوا

شروع سریع

از ساخت حساب تا اولین پاسخ مدل: شارژ اعتبار، ساخت کلید دسترسی (API Key) و فرستادن اولین درخواست با curl، پایتون یا Node.js به نشانی gisoo.pro/api/v1.

بازبینی: ۱۵ مهر ۱۴۰۵ ۷ دقیقه مطالعه

وب‌سرویس گیسو همان قالب API شرکت OpenAI را دارد. اگر پیش از این با SDK رسمی OpenAI کار کرده‌اید، چیز تازه‌ای لازم نیست یاد بگیرید: نشانی پایه (base URL) را https://gisoo.pro/api/v1 می‌گذارید، کلید گیسو را جای کلید OpenAI می‌دهید و همان کد اجرا می‌شود. این صفحه شما را از صفر تا اولین پاسخ مدل می‌برد.

پیش از شروع

  • یک حساب گیسو. اگر در نِت اَرز حساب دارید، با همان وارد شوید؛ حساب، اعتبار و کلیدها در هر دو یکی است.
  • اعتبار در حساب. شارژ از ۵۰٬۰۰۰ سکه شروع می‌شود و اشتراک ماهانه ندارد. تا ۲ دلار مصرف، احراز هویت لازم نیست؛ برای بیشتر از آن، یک بار هویتتان را در اپ تأیید کنید.
  • یک محیط اجرا: ترمینال با curl، یا پایتون ۳.۸ به بالا، یا Node.js ۱۸ به بالا، یا هر زبانی که درخواست HTTP بفرستد. سرور یا هاست داخل ایران هم کافی است و فیلترشکن نمی‌خواهد (آزمایش اتصال از سرور).

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

  1. وارد اپ گیسو شوید

    از gisoo.pro/app با شمارهٔ موبایل و کد پیامکی وارد شوید. شمارهٔ تازه همان‌جا حساب باز می‌کند.

  2. حساب را شارژ کنید

    در بخش اعتبار مبلغ را انتخاب کنید و در درگاه بانکی نِت اَرز بپردازید. اعتبار به دلار در حسابتان می‌نشیند و هزینهٔ هر درخواست از همین اعتبار کم می‌شود.

  3. یک کلید دسترسی (API Key) بسازید

    در بخش API یک پروژه و برایش یک کلید بسازید. کلید با sk-gisoo-v1- شروع می‌شود و فقط یک بار نشان داده می‌شود؛ همان لحظه جایی امن نگهش دارید.

  4. اولین درخواست را بفرستید

    کلید را در متغیر محیطی GISOO_API_KEY بگذارید و یکی از نمونه‌های پایین را اجرا کنید.

کلید را در متغیر محیطی بگذارید

کلید را مستقیم در کد ننویسید؛ کدی که در گیت یا دست همکار می‌رود، کلید را هم با خودش می‌برد. متغیر محیطی ساده‌ترین راه است:

Shell متغیر محیطی
# Linux / macOS
export GISOO_API_KEY="sk-gisoo-v1-..."

# Windows PowerShell
$env:GISOO_API_KEY = "sk-gisoo-v1-..."

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

این نمونه یک پیام به مدل gpt-4o-mini می‌فرستد؛ مدلی ارزان و سریع که برای آزمایش مناسب است. زبان را از زبانه‌ها انتخاب کنید؛ انتخابتان برای همهٔ نمونه‌های مستندات می‌ماند.

برای سرورها و کاربران داخل ایران، در این نمونه نشانی gisoo.pro را با ir.gisoo.pro جایگزین کنید؛ مسیر و کلید همان‌اند.

curl https://gisoo.pro/api/v1/chat/completions \
  -H "Authorization: Bearer $GISOO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "system", "content": "Answer in Persian, in two sentences."},
      {"role": "user", "content": "What is an API key?"}
    ]
  }'

پاسخ همان شکلی را دارد که از OpenAI می‌گیرید:

JSON پاسخ
{
  "id": "req_4b1f0c9a7e2d8f3a6c5b0e1d",
  "object": "chat.completion",
  "created": 1790000000,
  "model": "gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "…" },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 29, "completion_tokens": 64, "total_tokens": 93 }
}
  • choices[0].message.content متن پاسخ مدل است.
  • usage تعداد توکن ورودی و خروجی را می‌گوید؛ هزینهٔ درخواست از همین حساب می‌شود.
  • id شناسهٔ درخواست در گیسوست. همین مقدار در هدر X-Request-Id هم می‌آید و با GET /requests/{id} هزینهٔ دقیق همان درخواست را می‌دهد.
مدل دیگری امتحان کنید

فقط مقدار model را عوض کنید: openrouter/anthropic/claude-sonnet-4.5 برای Claude، gemini-3.6-flash برای Gemini یا deepseek-v4-flash برای DeepSeek. بقیهٔ کد همان می‌ماند. فهرست کامل را در مدل‌ها و انتخاب مدل ببینید.

اگر جواب نگرفتید

پاسخیعنی چهچه کنید
401 missing_api_keyکلید به درخواست نرسید.هدر Authorization: Bearer … را بفرستید و مطمئن شوید متغیر محیطی در همان ترمینال تنظیم شده است.
401 invalid_api_keyکلید درست نیست.کلید را دوباره و کامل کپی کنید؛ فاصله یا خط تازه در ابتدا و انتهایش نماند.
402 insufficient_creditاعتبار برای این درخواست کافی نیست.حساب را شارژ کنید یا max_tokens را کمتر بگذارید تا مبلغ کمتری کنار گذاشته شود.
403 kyc_requiredسقف مصرف پیش از احراز هویت پر شده است.احراز هویت را در اپ گیسو کامل کنید.
404 model_not_foundشناسهٔ مدل را پیدا نکردیم.شناسه را از GET /models یا صفحهٔ مدل‌ها بردارید.

فهرست کامل در صفحهٔ خطاها آمده است.

قدم بعدی

پاسخ پرسشتان را پیدا نکردید؟

شناسهٔ درخواست (هدر X-Request-Id) را با پرسشتان در تیکت بفرستید تا دقیق بررسی کنیم.

تیکت پشتیبانی