مهاجرت از OpenAI

گیسو همان قالب API شرکت OpenAI را دارد، پس مهاجرت یعنی عوض کردن دو مقدار: نشانی پایه (base URL) و کلید. کد، کتابخانه‌ها، پرامپت‌ها و منطق خطا همان می‌ماند. این صفحه تفاوت‌های ریز را فهرست می‌کند تا هیچ‌کدام غافلگیرتان نکند، و یک چک‌لیست برای جابه‌جایی بدون قطعی می‌دهد.

دو مقدار#

from openai import OpenAI

# before
# client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

# after: two values change, nothing else
client = OpenAI(
    base_url="https://gisoo.pro/api/v1",
    api_key=os.environ["GISOO_API_KEY"],
)

// before
// const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

// after
const client = new OpenAI({
  baseURL: "https://gisoo.pro/api/v1",
  apiKey: process.env.GISOO_API_KEY,
});

# If your code reads the standard variables, change only the environment:
OPENAI_BASE_URL=https://gisoo.pro/api/v1
OPENAI_API_KEY=sk-gisoo-v1-...

چه چیزهایی همان است#

• قالب درخواست و پاسخ /chat/completions، /responses، /embeddings، /images/generations، /audio/* و /models.
• پاسخ جریانی (SSE)، فراخوانی ابزار، خروجی JSON و ورودی تصویر.
• قالب خطا (error.type، error.code) و منطق تلاش دوبارهٔ SDKها.
• نام مدل‌های OpenAI؛ gpt-4o-mini در گیسو همان gpt-4o-mini است.

تفاوت‌ها#

endpointهایی که در گیسو نیستند#

این بخش‌های API شرکت OpenAI فعلاً در گیسو نیستند و درخواست به آن‌ها خطای 404 unknown_url می‌گیرد:

• بارگذاری فایل و Vector Store (/files، /uploads، /vector_stores): متن و تصویر را مستقیم در درخواست بفرستید؛ برای جست‌وجو در اسناد از امبدینگ استفاده کنید.
• Assistants و Threads: همان کار را با Chat Completions یا Responses API و نگه داشتن تاریخچه در برنامهٔ خودتان انجام دهید.
• Batch، Fine-tuning و Realtime (صدای زنده از WebSocket).
• ویرایش تصویر (/images/edits) و نسخهٔ دیگر تصویر (/images/variations).

از سرویس‌های مشابه#

• از سرویس دیگری که سازگار با OpenAI است (مثل OpenRouter یا یک درگاه دیگر): همان دو مقدار را عوض کنید. شناسهٔ مدل‌های OpenRouter را با پیشوند openrouter/ یا به شکل vendor/model بفرستید؛ مثلاً anthropic/claude-sonnet-4.5.
• از SDK اختصاصی Anthropic: گیسو endpoint سازگار با Anthropic هم دارد؛ سازگاری با Anthropic و Claude Code را ببینید. راه دیگر: Claude را با قالب OpenAI و SDK رسمی OpenAI صدا بزنید.
• از SDK اختصاصی Google (google-genai): این SDK با گیسو کار نمی‌کند؛ Gemini را با قالب OpenAI و شناسه‌ای مثل gemini-3.6-flash صدا بزنید.

چک‌لیست جابه‌جایی بدون قطعی#

1. کلید آزمایشی بسازید

   یک پروژهٔ «staging» با سقف هزینهٔ کم و کلید جدا.

2. نشانی و کلید را از متغیر محیطی بخوانید

   تا جابه‌جایی و برگشت فقط تغییر تنظیم باشد، نه کد.

3. با GET /me شروع کنید

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

4. چند درخواست واقعی را مقایسه کنید

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

5. کم‌کم ترافیک را بیاورید

   اول بخشی از کاربران، بعد همه. مصرف را با GET /usage دنبال کنید.

6. برای کلید تولید سقف بگذارید

   سقف هزینهٔ کلید و بودجهٔ ماهانهٔ پروژه را متناسب با مصرف واقعی تنظیم کنید.

پشتیبان در کنار گیسو#

اگر سرویس شما نباید حتی چند دقیقه از کار بیفتد، یک مسیر پشتیبان نگه دارید و فقط برای خطاهای موقت (۴۲۹ و ۵xx) سراغش بروید:

import os
from openai import OpenAI, APIStatusError, APIConnectionError

primary = OpenAI(base_url="https://gisoo.pro/api/v1", api_key=os.environ["GISOO_API_KEY"], max_retries=2)
backup = OpenAI(base_url=os.environ["BACKUP_BASE_URL"], api_key=os.environ["BACKUP_API_KEY"])

def chat(**kwargs):
    try:
        return primary.chat.completions.create(**kwargs)
    except (APIConnectionError, APIStatusError) as e:
        if isinstance(e, APIStatusError) and e.status_code < 500 and e.status_code != 429:
            raise                      # a 4xx is our bug, not an outage
        return backup.chat.completions.create(**kwargs)