پرش به مطلب اصلی

اتصال مستقیم با SDKها و API

این صفحه مسیر سریع cURL، Python و Node.js را نشان می‌دهد. برای مثال‌های بیشتر این دو راهنما را ببینید:

API سازگار با OpenAI چیست؟​

API سازگار با OpenAI یعنی برنامه می‌تواند همان ساختار رایج درخواست، پیام و پاسخ OpenAI را با یک base_url متفاوت استفاده کند. در نتیجه برای اتصال بسیاری از backendها و اسکریپت‌ها به چابکان لازم نیست کلاینت HTTP تازه‌ای طراحی کنید؛ کتابخانه رسمی OpenAI را نصب می‌کنید و آدرس آن را روی درگاه چابکان قرار می‌دهید.

این روش برای ساخت چت‌بات، خلاصه‌ساز، تولید محتوا، دستیار داخلی، پردازش دسته‌ای متن و سرویس‌های backend مناسب است. تفاوت آن با ابزارهایی مانند Claude Code یا Cline این است که در اینجا خود شما منطق برنامه، تاریخچه گفتگو، ابزارخوانی، ذخیره‌سازی و رابط کاربری را کنترل می‌کنید.

مسیر هر درخواست به‌صورت خلاصه چنین است:

برنامه شما → SDK رسمی OpenAI → API چابکان → مدل انتخابی → پاسخ استاندارد

ابتدا کلید را در environment قرار دهید:

export CHABOKAN_AI_API_KEY="sk-chbk-کلید-واقعی-شما"

دریافت فهرست مدل‌ها​

curl --fail-with-body https://ai.chabokan.net/v1/models \
  -H "Authorization: Bearer $CHABOKAN_AI_API_KEY"

شناسه یکی از مدل‌های مجاز را از فیلد id بردارید.

cURL​

curl --fail-with-body https://ai.chabokan.net/v1/chat/completions \
  -H "Authorization: Bearer $CHABOKAN_AI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [
      {"role": "system", "content": "پاسخ را کوتاه و فارسی بنویس."},
      {"role": "user", "content": "API چیست؟"}
    ]
  }'

Python​

نصب​

python -m pip install openai

کد​

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["CHABOKAN_AI_API_KEY"],
    base_url="https://ai.chabokan.net/v1",
)

response = client.chat.completions.create(
    model="openai/gpt-4o-mini",
    messages=[
        {"role": "system", "content": "پاسخ را کوتاه و فارسی بنویس."},
        {"role": "user", "content": "API چیست؟"},
    ],
)

print(response.choices[0].message.content)

Node.js و TypeScript​

نصب​

npm install openai

کد​

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.CHABOKAN_AI_API_KEY,
  baseURL: "https://ai.chabokan.net/v1",
});

const response = await client.chat.completions.create({
  model: "openai/gpt-4o-mini",
  messages: [
    { role: "system", content: "پاسخ را کوتاه و فارسی بنویس." },
    { role: "user", content: "API چیست؟" },
  ],
});

console.log(response.choices[0].message.content);

پاسخ جریانی یا Streaming​

درخواست streaming نیز پشتیبانی می‌شود:

stream = client.chat.completions.create(
    model="openai/gpt-4o-mini",
    messages=[{"role": "user", "content": "یک داستان خیلی کوتاه بنویس."}],
    stream=True,
)

for chunk in stream:
    text = chunk.choices[0].delta.content
    if text:
        print(text, end="", flush=True)

نمونه streaming در Node.js و مدیریت chunkهای بدون متن در مثال‌های پیشرفته API آمده است.

استفاده از مدل‌های Gemini​

برای استفاده از یک مدل Gemini لازم نیست Google GenAI SDK را به چابکان متصل کنید. همان OpenAI SDK بالا را نگه دارید و فقط model را برابر شناسه دقیق یک مدل Google از پنل قرار دهید:

response = client.chat.completions.create(
    model="google/شناسه-مدل-gemini",
    messages=[{"role": "user", "content": "این متن را خلاصه کن."}],
)

درگاه چابکان فعلاً endpoint بومی Gemini مانند generateContent را ارائه نمی‌دهد؛ بنابراین Gemini CLI و Google GenAI SDK را نمی‌توان مستقیماً با Base URL چابکان تنظیم کرد. برای مدل‌های Gemini از OpenAI SDK، Cline، Roo Code، Continue یا OpenCode استفاده کنید.

نکته‌های مهم برای محیط production​

  • API Key را فقط سمت سرور نگه دارید؛ آن را در JavaScript مرورگر یا اپ موبایل منتشر نکنید.
  • timeout و retry محدود تعریف کنید.
  • مقدار X-Request-Id پاسخ را برای عیب‌یابی ثبت کنید، اما متن حساس درخواست را بی‌دلیل log نکنید.
  • برای هر محیط توسعه، staging و production کلید جدا بسازید.
  • روی کلید production تاریخ انقضا یا سقف مصرف ماهانه مناسب قرار دهید.

منبع SDKها و قرارداد Chat Completions: SDKهای رسمی OpenAI، API Reference