در شروع آموزش API ChatGPT باید بدانی که اشتراک ChatGPT Plus فقط برای چت کردن در سایت و اپ ChatGPT است. چیزی که معمولاً به آن «API ChatGPT» یا «API چت جی پی تی» میگویند، در واقع API مدلهای GPT شرکت OpenAI است و ChatGPT اسم اپ چت آن است. اگر میخواهی مدلهای GPT را داخل ربات، سایت، اسکریپت یا ابزاری مثل n8n به کار ببری، کلید API لازم داری. استفاده از API ChatGPT در خود OpenAI جدا از اشتراک ChatGPT حساب میشود و برای شارژش باید روش پرداخت بینالمللی ثبت کنی. در این آموزش API ChatGPT مسیر دیگری را قدمبهقدم جلو میبریم: ساخت سرویس هوش مصنوعی در چابکان، شارژ اعتبار بدون کارت اعتباری خارجی، ساخت کلید و فرستادن اولین پیام با curl، پایتون و Node.js.
کدهای این مقاله را با SDK رسمی OpenAI (نسخهٔ 3.28.0 پایتون روی Python 3.13 و نسخهٔ 7.32.0 Node.js روی Node.js 22) و PowerShell 7 اجرا کردیم: یک بار با یک سرور آزمایشی که پاسخ درگاه را شبیهسازی میکرد، و یک بار با خود درگاه چابکان و یک کلید عمداً اشتباه تا پیام خطاها را ببینیم. پس پاسخ واقعی مدل را با کلید واقعی در این تست نگرفتیم، ولی مسیر درخواست، هدرها و خطاها همان است که در ادامه میبینی.

ChatGPT Plus یا API: کدام به کارت میآید؟
اگر برای ساختن ربات اشتراک Plus خریدهای و در حسابت کلید API پیدا نمیکنی، دلیلش این است که طبق راهنمای صورتحساب OpenAI، ChatGPT و API دو سیستم پرداخت جدا دارند و مصرف API جزو اشتراک ChatGPT نیست.
| مقایسه | ChatGPT Plus | API |
|---|---|---|
| برای چه کاری است؟ | چت کردن خودت در سایت و اپ ChatGPT | فرستادن درخواست از برنامه، ربات یا ابزار |
| نحوهٔ پرداخت | اشتراک ماهانه با مبلغ ثابت | به اندازهٔ مصرف (توکن) |
| کلید API میدهد؟ | نه | بله، کار اصلیاش همین است |
| مناسب | نوشتن، ترجمه و سؤالهای روزمره | ربات تلگرام، n8n، سایت، ابزارهای کدنویسی |
توکن تکهٔ کوچکی از متن است. هر چه متن سؤال و جواب بلندتر باشد، توکن بیشتری مصرف میشود.
اگر فقط خودت میخواهی با ChatGPT چت کنی، API به کارت نمیآید. اگر میخواهی یک برنامه به جای تو با مدل حرف بزند، API لازم داری.
API ChatGPT در چابکان چطور کار میکند؟
سرویس هوش مصنوعی چابکان یک درگاه API سازگار با OpenAI است. چابکان کلید یا حساب OpenAI به تو نمیدهد. کلید، اعتبار و گزارش مصرف در پنل چابکان است و درخواستها از درگاه چابکان به مدلها میرسد. فقط ساختار درخواست و پاسخ همان API OpenAI است. برنامه همان ساختار درخواست و پاسخ OpenAI را میفرستد و فقط آدرس پایه (Base URL) و کلید عوض میشود. کتابخانهٔ رسمی OpenAI در پایتون و Node.js بدون تغییر کار میکند. هر اتصالی سه مقدار لازم دارد:
- Base URL:
https://ai.chabokan.net/v1 - کلید API: کلیدی که در پنل میسازی و با
sk-chbk-شروع میشود. - شناسهٔ مدل (Model ID): شناسهٔ فنی مدل، مثل
openai/gpt-4o-mini، نه اسم نمایشی آن.
مدلهای OpenAI با پیشوند openai/ در دسترساند و با همان کلید میتوانی مدلهای خانوادههای دیگر مثل Claude، Gemini یا DeepSeek را هم صدا بزنی. فقط شناسهٔ مدل عوض میشود. توضیح کامل این سه مقدار در راهنمای آمادهسازی و تست اتصال آمده است.
قدم ۱: ساخت سرویس هوش مصنوعی و شارژ اعتبار
- وارد پنل چابکان شو و از منوی محصولات «هوش مصنوعی» را باز کن.
- «ایجاد سرویس هوش مصنوعی» را بزن، یک اسم مشخص بگذار، پلن و دورهٔ پرداخت را انتخاب کن، کیف پول را انتخاب کن و ساخت سرویس را تأیید کن.
- صبر کن وضعیت سرویس «فعال» شود.
- در صفحهٔ سرویس زبانهٔ «اعتبار و شارژ» را باز کن، مبلغ اعتبار را وارد کن، کیف پول را انتخاب کن و تأیید کن. اعتبار هوش مصنوعی از همین کیف پول شارژ میشود و خود کیف پول را با درگاه پرداخت داخلی و ریالی شارژ میکنی.
هزینهٔ پلن و اعتبار مصرف مدل دو چیز جدا هستند. ساخت سرویس یا کلید بهتنهایی برای گرفتن جواب کافی نیست و تا اعتبار مصرف بیشتر از صفر نباشد، مدل جواب نمیدهد.
قدم ۲: ساخت کلید API
- زبانهٔ «کلیدهای API» را باز کن و «ایجاد کلید» را بزن.
- یک اسم گویا بگذار که بگوید کلید مال کجاست، مثلاً
telegram-bot-prodبرای ربات تلگرام هوش مصنوعی یاlaptop-test. - اگر خواستی، تاریخ انقضا و سقف مصرف ماهانه هم تعیین کن. برای کلیدی که در یک برنامهٔ واقعی میگذاری، سقف ماهانه را حتماً پر کن. سقف را با همان واحدی که فرم نشان میدهد وارد کن.
- کلید را بساز و همان لحظه کپی کن. کلید کامل فقط یک بار نشان داده میشود. اگر گمش کردی، کلید قبلی را لغو کن و کلید تازه بساز.
کلید را در Git، اسکرینشات، تیکت یا پیام گروهی نگذار. دستورهای این مقاله را در ترمینال میزنی: در ویندوز PowerShell، در مک برنامهٔ Terminal و در لینوکس هر ترمینالی. برای تست، آن را فقط در ترمینال در یک متغیر محیطی بگذار:
export CHABOKAN_AI_API_KEY="sk-chbk-your-key"
در PowerShell ویندوز:
$env:CHABOKAN_AI_API_KEY = "sk-chbk-your-key"
این متغیر با بستن ترمینال پاک میشود. همهٔ مثالهای بعدی کلید را از همین متغیر میخوانند تا هیچوقت داخل کد نوشته نشود.
قدم ۳: انتخاب مدل GPT
زبانهٔ «مدلهای قابل استفاده» را در پنل باز کن و شناسهٔ مدل را دقیقاً از همانجا کپی کن. اینکه کدام مدلها برایت باز است به پلن سرویس بستگی دارد. فهرست کامل مدلهای OpenAI و شناسههایشان در صفحهٔ API مدلهای OpenAI در چابکان آمده است. چند نمونه:
openai/gpt-4o-mini: مدل کوچکی که در پلن پایه هم هست و مستندات چابکان در مثالهایش آورده است. برای شروع و کارهای روزمره مثل خلاصه کردن، دستهبندی متن یا جواب یک ربات ساده مناسب است.openai/gpt-5.4-mini: یک مدل کوچک از نسل GPT-5.openai/gpt-5.5: یک نمونه از مدلهای بزرگتر برای استدلال و کدنویسی. در فهرست، مدلهای بزرگتر و تازهتری هم هست.- شناسههای
-latestمثلopenai/gpt-mini-latestبه نسخهٔ فعلی همان رده اشاره میکنند و ممکن است بیخبر عوض شوند. اگر میخواهی رفتار برنامه ثابت بماند، شناسهٔ نسخهدار را بگذار.
فهرست مدلها زود به زود عوض میشود. پس اسمهای این مقاله را فقط مثال بدان و شناسه را همیشه از پنل یا /v1/models بردار.
فهرست مدلهای باز برای کلیدت را با API هم میتوانی بگیری. شناسهها در فیلد id هر مورد هستند:
curl --fail-with-body https://ai.chabokan.net/v1/models \
-H "Authorization: Bearer $CHABOKAN_AI_API_KEY"
این دستور برای macOS، لینوکس و WSL است. در PowerShell ویندوز:
(Invoke-RestMethod -Uri "https://ai.chabokan.net/v1/models" -Headers @{ Authorization = "Bearer $env:CHABOKAN_AI_API_KEY" }).data.id
برای مقایسهٔ بیشتر، راهنمای انتخاب مدل را ببین.
قبل از نوشتن هر کدی، در صفحهٔ سرویس بخش «چت با مدل» را باز کن و با مدلی که انتخاب کردی یک پیام کوتاه بفرست. این اولین تست بدون کد است: اگر جواب گرفتی، سرویس و اعتبار درست کار میکنند و اگر تست بعدی خطا داد، مشکل از کلید، آدرس یا شناسهٔ مدل در درخواست است.
قدم ۴: اولین پیام با curl
تست بعدی یک درخواست 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": "user", "content": "Reply with: connected"}
]
}'
در جواب موفق، بخشی به اسم choices میبینی و متن پاسخ مدل داخل message.content است. این دستور برای macOS، لینوکس و WSL است. در PowerShell ویندوز همین درخواست را اینطور بفرست:
$body = @{ model = "openai/gpt-4o-mini"; messages = @(@{ role = "user"; content = "Reply with: connected" }) } | ConvertTo-Json -Depth 5
Invoke-RestMethod -Method Post -Uri "https://ai.chabokan.net/v1/chat/completions" -Headers @{ Authorization = "Bearer $env:CHABOKAN_AI_API_KEY" } -ContentType "application/json" -Body $body
جواب را به شکل یک شیء میبینی و متن پاسخ در choices است. بعد از اولین جواب، زبانهٔ «گزارش درخواستها» را در پنل باز کن تا همین درخواست و مصرفش را ببینی.
اگر جواب نگرفتی، اول خطا را در جدول «خطاهای رایج» پایین همین مقاله پیدا کن. با کلید اشتباه، درگاه این را برگرداند:
{"error": {"message": "Malformed API key.", "type": "invalid_api_key", "code": "invalid_api_key"}}

قدم ۵: همان درخواست با پایتون و Node.js
برای مثال پایتون Python 3.10 یا جدیدتر و برای مثال Node Node.js 22 یا جدیدتر لازم است. نسخه را با python3 --version و node --version ببین.
پایتون
کتابخانهٔ رسمی OpenAI را داخل یک محیط مجازی نصب کن:
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
python -m pip install openai
در ویندوز اگر python3 نبود، python بنویس. محیط مجازی لازم است، چون در نسخههای جدید Debian و Ubuntu نصب سراسری با pip خطای externally-managed-environment میدهد.
فایل chat.py:
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": "Answer in one short sentence."},
{"role": "user", "content": "What is an API?"},
],
)
print(response.choices[0].message.content)
با python chat.py اجرایش کن (محیط مجازی باید فعال باشد). تنها فرق این کد با نمونههای خود OpenAI، خط base_url و پیشوند openai/ در اسم مدل است. اگر متغیر کلید را در همان ترمینال نگذاشته باشی، پایتون خطای KeyError: 'CHABOKAN_AI_API_KEY' میدهد.
Node.js
npm install openai
فایل chat.mjs:
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: "Answer in one short sentence." },
{ role: "user", content: "What is an API?" },
],
});
console.log(response.choices[0].message.content);
با node chat.mjs اجرایش کن. پسوند .mjs برای این است که import و await بدون تنظیم اضافه کار کنند.
ابزارهایی که فقط OPENAI_API_KEY میخوانند
بعضی ابزارها و کتابخانهها جای جدایی برای Base URL ندارند و فقط متغیرهای استاندارد OpenAI را میخوانند. SDK رسمی پایتون و Node.js هم اگر در کد کلید و آدرس ندهی، سراغ همین دو متغیر میروند:
export OPENAI_API_KEY="sk-chbk-your-key"
export OPENAI_BASE_URL="https://ai.chabokan.net/v1"
در تست ما هر دو SDK فقط با همین دو متغیر و بدون هیچ تنظیمی در کد به درگاه وصل شدند. برای زبانهای دیگر مثل Go، Java، .NET یا PHP، نمونه کدهای زبانهای مختلف را ببین. پاسخ جریانی (streaming)، ابزارخوانی و Responses API هم در مثالهای پیشرفتهٔ API آمدهاند. قبل از استفاده از این قابلیتها، آنها را با همان مدلی که انتخاب کردهای تست کن، چون هر مدلی همهشان را پشتیبانی نمیکند.
با کلید API چه کارهایی میشود کرد؟
کلید و Base URL را که داشته باشی، در بیشتر ابزارهای سازگار با OpenAI همان دو مقدار را وارد میکنی:
- ابزارهای کدنویسی در VS Code: Cline، Roo Code و Continue با Base URL چابکان کار میکنند. تنظیمشان در راهنماهای Cline، Roo Code و Continue آمده است.
- اتوماسیون با n8n: در n8n یا نود OpenAI Chat Model را با یک Credential که Base URL آن
https://ai.chabokan.net/v1است تنظیم میکنی، یا نود HTTP Request را با آدرس کاملhttps://ai.chabokan.net/v1/chat/completionsمیسازی. مستند چابکان روش HTTP Request را «مطمئنترین روش مستقل از نسخه» میداند. هر دو روش قدمبهقدم در ساخت دستیار هوش مصنوعی با n8n و راهنمای n8n آمدهاند. اگر n8n نداری، n8n آماده را راه بینداز. - ربات یا سایت خودت: کد پایتون یا Node.js بالا همان تکهای است که ربات یا چتبات تو برای گرفتن جواب از مدل صدا میزند. ساخت ربات تلگرام هوش مصنوعی با پایتون قدمبهقدم همین کد را به ربات تبدیل میکند و برای روشن نگه داشتن ربات، هاست ربات تلگرام را داری. برای سایت، وقتی کد کار کرد، برای آنلاین کردنش آنلاین کردن پروژه ChatGPT یا Claude را بخوان.
- ایجنت همیشه روشن: اگر میخواهی یک ایجنت هوش مصنوعی روی سرور اجرا شود، اجرای AI Agent روی سرور را ببین.
امنیت کلید و کنترل هزینه
هر درخواست به اندازهٔ توکنهایی که مصرف میکند از اعتبار کم میکند. کلیدی که لو برود، از اعتبار تو خرج میکند. این چند کار جلویش را میگیرد:
- کلید فقط سمت سرور. کلید را هیچوقت در JavaScript سایت (کدی که در مرورگر اجرا میشود) یا داخل اپ موبایل نگذار. هر کسی میتواند آن را از کد صفحه بیرون بکشد. مرورگر یا اپ باید درخواست را به سرور خودت بفرستد و سرور با کلید مدل را صدا بزند.
- فایل
.envبیرون از Git. اگر کلید را در فایل.envگذاشتهای، اسم این فایل را در.gitignoreبنویس. - یک کلید برای هر محیط. برای لپتاپ، سرور تست و سرور اصلی کلید جدا بساز تا اگر یکی لو رفت، فقط همان را لغو کنی و بقیه کار کنند.
- سقف ماهانه و تاریخ انقضا. وقتی سقف پر شود، درگاه خطای 402 میدهد و خرج بیشتری نمیشود.
- اطلاعات حساس در پیام نه. متن درخواستها از درگاه به سازندهٔ مدل میرسد. اطلاعات حساس مشتری یا رمزها را بیدلیل داخل پیام نفرست و در لاگ ننویس.
- گزارش درخواستها. در پنل ببین کدام کلید و کدام مدل بیشتر مصرف کرده است. اگر مصرف عجیبی دیدی، کلید را همان لحظه لغو کن و کلید تازه بساز.
راهنمای کاملتر برای تیمها در استفاده در محیط واقعی آمده است.
خطاهای رایج
| پیام | علت | راه حل |
|---|---|---|
401 Malformed API key یا Invalid API key |
کلید ناقص یا اشتباه کپی شده است، یا کلید OpenAI را به جای کلید چابکان گذاشتهای | کلید sk-chbk- را دوباره کپی کن یا کلید تازه بساز |
401 Missing API key |
کلید به درخواست نرسیده است | متغیر را در همان ترمینالی بگذار که برنامه را از آن اجرا میکنی |
Incorrect API key provided: sk-chbk-... |
base_url را نگذاشتهای و درخواست به سرور خود OpenAI رفته است |
base_url را روی https://ai.chabokan.net/v1 بگذار |
KeyError: 'CHABOKAN_AI_API_KEY' |
متغیر محیطی در این ترمینال تعریف نشده است | دستور export را در همان ترمینال دوباره بزن |
404 Unknown path |
آدرس دو بار /v1 گرفته است، مثلاً /v1/v1/chat/completions |
Base URL را دقیقاً https://ai.chabokan.net/v1 بگذار |
404 با صفحهٔ Not Found |
/v1 از آخر Base URL جا افتاده است |
/v1 را به آخر آدرس اضافه کن |
404 model not found |
شناسهٔ مدل غلط است یا در پلن تو نیست | شناسه را از «مدلهای قابل استفاده» عیناً کپی کن |
402 AI credit exhausted |
اعتبار مصرف تمام شده است | از زبانهٔ «اعتبار و شارژ» شارژ کن |
402 Monthly usage cap reached |
کلید به سقف ماهانهاش رسیده است | سقف را بیشتر کن یا تا دورهٔ بعد صبر کن |
API key is disabled یا API key has expired |
کلید لغو شده یا تاریخ انقضایش گذشته است | کلید تازه بساز |
429 |
تعداد درخواست در دقیقه از حد پلن بیشتر شده است | درخواستهای همزمان را کم کن و با فاصله دوباره بفرست |
شش ردیف اول را خودمان در تست دیدیم. بقیه از جدول عیبیابی چابکان است. اگر خطای 5xx گرفتی، مقدار هدر X-Request-Id پاسخ را نگه دار و برای پشتیبانی بفرست.
جمعبندی: شروع کار با API مدلهای GPT
خلاصهٔ این آموزش API ChatGPT: برای شروع کار در چابکان سه چیز لازم داری: یک سرویس هوش مصنوعی، اعتبار مصرف و یک کلید. هر سه را از یک پنل میگیری و اعتبار را بدون کارت اعتباری خارجی و با پرداخت ریالی شارژ میکنی. اعتبار هدیهٔ ۱۰۰ هزار تومانی را هم میتوانی برای مصرف هوش مصنوعی خرج کنی و اولین درخواستها را با آن تست کنی. فهرست مدلها و شناسههایشان در صفحهٔ خرید API مدلهای OpenAI در چابکان هست و بقیهٔ خانوادهها در هوش مصنوعی ابری چابکان.
اگر میخواهی بدانی پشت ChatGPT چه میگذرد، شیوه کارکرد ChatGPT و مدل زبانی بزرگ (LLM) چیست؟ را بخوان.
سوالات متداول آموزش API ChatGPT
با گرفتن API به خود سایت ChatGPT هم دسترسی پیدا میکنم؟
نه. API برای وصل کردن مدل به برنامه است و حساب ChatGPT به تو نمیدهد. برای امتحان سریع یک مدل، بخش «چت با مدل» در صفحهٔ سرویس هست. اگر میخواهی خودت در محیطی شبیه ChatGPT چت کنی، میتوانی یک رابط چت مثل Open WebUI را به همین کلید وصل کنی. راهش در راهنمای Open WebUI آمده است.
این همان API رسمی OpenAI است؟
نه. تو به درگاه چابکان وصل میشوی که مدلهای OpenAI را با همان قالب API در دسترس میگذارد. کلید، صورتحساب و پشتیبانی با چابکان است. به همین دلیل کلید OpenAI اینجا کار نمیکند.
کلید API OpenAI خودم را در چابکان میتوانم استفاده کنم؟
نه. درگاه چابکان فقط کلیدهایی را قبول میکند که در پنل خودش ساخته شدهاند و با sk-chbk- شروع میشوند. وقتی یک کلید با قالب OpenAI را تست کردیم، درگاه خطای Malformed API key داد. برعکسش هم صادق است: کلید چابکان روی سرور OpenAI کار نمیکند.
کدام مدل GPT را انتخاب کنم؟
برای شروع یک مدل کوچک مثل openai/gpt-4o-mini (که در پلن پایه هم هست) یا openai/gpt-5.4-mini کافی است. اگر جوابها برای کارت کافی نبود، همان کد را با یک مدل بزرگتر امتحان کن، مثلاً openai/gpt-5.5 یا یکی دیگر از مدلهای بزرگتر فهرست. فقط شناسهٔ مدل عوض میشود و بقیهٔ کد همان میماند.
هزینه چطور حساب میشود؟
هر درخواست به اندازهٔ توکنهای ورودی و خروجی از اعتبار مصرف کم میشود و تعرفهٔ هر مدل در صفحهٔ همان خانوادهٔ مدل آمده است. هزینهٔ پلن سرویس از اعتبار مصرف جداست. با سقف ماهانه روی هر کلید، خرج آن کلید از عددی که خودت گذاشتهای بالاتر نمیرود.
با همین کلید میشود از مدلهای غیر OpenAI هم استفاده کرد؟
بله. همان کد و همان Base URL کار میکند و فقط شناسهٔ مدل عوض میشود، مثلاً یک مدل از مدلهای Gemini یا مدلهای DeepSeek. شناسهٔ دقیق را از پنل کپی کن، چون هر خانواده پیشوند خودش را دارد.