پرش به محتوا

شروع سریع

از ساخت حساب تا اولین پاسخ مدل: شارژ اعتبار، ساخت کلید دسترسی (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 می‌فرستد؛ مدلی ارزان و سریع که برای آزمایش مناسب است. زبان را از زبانه‌ها انتخاب کنید؛ انتخابتان برای همهٔ نمونه‌های مستندات می‌ماند.

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) را با پرسشتان در تیکت بفرستید تا دقیق بررسی کنیم.

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