اتصال Cursor و Cline و n8n به API؛ راهنمای 1ai
با یک کلید 1ai و آدرس پایهٔ https://1ai.ir/v1 ابزارهای خود را تنظیم کنید. مراحل Cline، Continue و n8n، محدودیت‌های اتصال Cursor و روش عیب‌یابی و تعیین سقف مصرف را بخوانید.
برای اتصال Cursor و Cline و n8n به API در 1ai، یک کلید با پیشوند sk-1ai- بسازید، آدرس پایه را https://1ai.ir/v1 قرار دهید و شناسهٔ کامل مدل را وارد کنید. Cline، Continue و n8n مسیر تنظیم سازگار با OpenAI دارند؛ اتصال Cursor به پشتیبانی نسخهٔ نصب‌شده از آدرس سفارشی و مدل انتخابی وابسته است و همهٔ قابلیت‌های آن را پوشش نمی‌دهد.
این راهنما بر اساس بررسی منابع رسمی در اکتبر ۲۰۲۶ / آبان ۱۴۰۵ نوشته شده است. مراحل را ابتدا با یک پیام کوتاه انجام دهید؛ پس از دریافت پاسخ، سراغ فایل‌های پروژه یا اجرای خودکار بروید. وان ای آی (1ai) برای این اتصال یک کلید و اعتبار یکپارچه در اختیار شما می‌گذارد؛ حساب و محدودیت‌های خود ابزار خارجی همچنان جدا هستند.
برای اتصال Cursor و Cline و n8n به API چه چیزهایی لازم است؟
چهار مقدار را پیش از شروع آماده کنید. نام ظاهری مدل در ابزار ممکن است دلخواه باشد، اما مقدار ارسالی به API باید دقیق باشد.
| مورد | مقدار یا روش انتخاب |
|---|---|
| آدرس پایه یا Base URL | https://1ai.ir/v1 |
| کلید API | کلید شخصی شما با پیشوند sk-1ai- |
| شناسهٔ مدل یا Model ID | مقدار دقیق id در پاسخ مسیر GET /v1/models |
| مسیر تولید پاسخ متنی | POST /v1/chat/completions |
آدرس پایه را با مسیر کامل درخواست اشتباه نگیرید. در کادر Base URL فقط نشانی منتهی به /v1 را بنویسید؛ ابزار مسیر chat/completions را اضافه میکند. واردکردن مسیر کامل در این کادر ممکن است نشانی تکراری بسازد.
برای آشنایی با ساختار درخواست و پاسخ، راهنمای API سازگار با OpenAI را بخوانید. سازگاری در اینجا به مسیرها و قالب‌های پشتیبانی‌شده اشاره دارد؛ از آن نمی‌توان پشتیبانی همهٔ APIها، قابلیت‌ها و حالت‌های هر ابزار را نتیجه گرفت.
چطور در 1ai کلید بسازیم و مدل را پیدا کنیم؟
۱. وارد حساب 1ai شوید. ورود با شمارهٔ موبایل ایرانی و کد یک‌بارمصرف انجام میشود. سپس بخش توسعه‌دهندگان و مدیریت کلیدهای API را باز کنید؛ نقطهٔ شروع مستندات، صفحهٔ توسعه‌دهندگان است.
۲. یک کلید برای ابزار موردنظر بسازید. بهتر است نامی مانند cline-local یا n8n-test انتخاب کنید تا مصرف آن را با اتصال‌های دیگر اشتباه نگیرید. مقدار کلید را در محل امن نگه دارید و در مخزن کد، متن مقاله یا تصویر تنظیمات منتشر نکنید.
۳. برای همان کلید سقف مصرف ماهانه تعیین کنید. برای آزمایش اولیه، بودجه‌ای محدود و متناسب با نیاز خود بگذارید. از یک کلید مشترک برای آزمایش شخصی و گردشکار عملیاتی استفاده نکنید؛ کلیدهای جدا، پیگیری مصرف را ساده‌تر می‌کنند.
۴. فهرست مدل‌های قابل‌دسترسی را بگیرید. در ترمینال محلی، متغیر ONEAI_API_KEY را با روش امن محیط خود تنظیم کنید. نمونه‌های زیر فرض می‌کنند مقدار واقعی کلید قبلاً در این متغیر قرار گرفته است:
curl --fail-with-body https://1ai.ir/v1/models \
-H "Authorization: Bearer $ONEAI_API_KEY"در خروجی، مقدار id را کپی کنید. اسلاگ‌هایی مانند openai/gpt-6.1-sol و deepseek/deepseek-v4.1-flash نمونهٔ شناسه‌های کاتالوگ 1ai هستند؛ دسترس‌پذیری لحظه‌ای را با خروجی حساب خود بررسی کنید. پیشوند سازنده و علامت / را حذف نکنید و نام نمایشی را جای اسلاگ ننویسید.
۵. برای جداکردن مشکل حساب از مشکل ابزار، یک درخواست ساده بفرستید. در نمونهٔ زیر، اگر این شناسه در فهرست شما نبود، آن را با یک مدل متنی در دسترس جایگزین کنید:
curl --fail-with-body https://1ai.ir/v1/chat/completions \
-H "Authorization: Bearer $ONEAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "openai/gpt-6.1-sol",
"messages": [{"role": "user", "content": "فقط بنویس: اتصال برقرار است"}],
"stream": false
}'دریافت فهرست مدلها فقط دسترسی به آن مسیر را نشان می‌دهد. پاسخ موفق به پیام کوتاه، آزمون جداگانه‌ای برای تولید متن است؛ هنوز عملکرد فراخوانی ابزار یا پردازش تصویر را ثابت نمی‌کند.
اتصال Cline به API چگونه انجام میشود؟
در تنظیمات Cline، ارائهدهندهٔ OpenAI Compatible را انتخاب کنید؛ مستندات رسمی همین حالت را برای واردکردن Base URL، کلید و Model ID معرفی می‌کنند. تنظیمات پیشرفتهٔ مدل نیز در همین بخش قرار دارد. منبع رسمی تنظیمات Cline
۱. پنل Cline را باز کنید و وارد تنظیمات اتصال مدل شوید. برای این آموزش، حالت ورود به حساب ارائه‌دهنده یا ارائهدهندهٔ اختصاصی دیگری را انتخاب نکنید؛ مسیر موردنظر، OpenAI Compatible است.
۲. در Base URL بنویسید https://1ai.ir/v1. در API Key، کلید مخصوص همین اتصال را قرار دهید. در Model ID، همان شناسه‌ای را وارد کنید که در آزمون ترمینال پاسخ داده است.
۳. اگر تنظیمات مدل از شما ظرفیت متن یا حداکثر خروجی می‌خواهد، مقادیر تأییدشدهٔ مدل انتخابی را مبنا بگذارید. ظرفیت بزرگ‌تر را حدس نزنید؛ عددی که در ابزار وارد می‌کنید، ظرفیت واقعی مدل را افزایش نمی‌دهد.
۴. تنظیمات را ذخیره کنید و یک گفت‌وگوی تازه با این پیام بسازید:
فقط در یک جمله تأیید کن که پیام من را دریافت کرده‌ای.
فعلاً هیچ فایلی را تغییر نده و هیچ دستوری اجرا نکن.۵. پس از پاسخ موفق، یک فایل کوچک و غیرمحرمانه را موضوع درخواست قرار دهید. از مدل بخواهید ابتدا اشکال احتمالی و پیشنهاد تغییر را توضیح دهد. عملکرد گفت‌وگو و اجرای کار روی پروژه را جدا بررسی کنید.
برای مرور همین اتصال، راهنمای Cline در 1ai را کنار تنظیمات نگه دارید. در آزمون اول کل پروژه و تاریخچهٔ طولانی را وارد نکنید؛ اگر خطایی رخ دهد، با ورودی کوتاه تشخیص علت آسان‌تر است.
Continue را با چه تنظیماتی به 1ai وصل کنیم؟
Continue برای ارائهدهندهٔ سازگار از provider: openai و apiBase استفاده میکند. گزینهٔ useResponsesApi: false نیز مسیر Chat Completions را به‌جای Responses انتخاب میکند؛ این تفاوت برای API فعلی 1ai ضروری است. مستندات رسمی ارائهدهندهٔ OpenAI در Continue
۱. در Continue پیکربندی محلی را باز کنید. اگر از قبل تنظیماتی دارید، فقط بخش مدل موردنیاز را به آن اضافه کنید و پیکربندی‌های دیگر را جایگزین نکنید.
۲. برای یک پیکربندی نمونه، قالب زیر را در تنظیمات YAML وارد کنید. مقدار کلید نمونه عمداً قابل‌استفاده نیست؛ کلید واقعی را فقط در محیط خصوصی تنظیم کنید:
name: 1ai Local
version: 1.0.0
schema: v1
models:
- name: 1ai Chat
provider: openai
model: openai/gpt-6.1-sol
apiBase: https://1ai.ir/v1
apiKey: sk-1ai-REPLACE_WITH_YOUR_KEY
useResponsesApi: false
roles:
- chat۳. مقدار model را با شناسهٔ آزموده‌شدهٔ حساب خود تطبیق دهید. مقدار name فقط برچسب خوانا برای تشخیص این اتصال است؛ تغییر آن شناسهٔ مدل ارسالی را تغییر نمی‌دهد.
۴. پیکربندی را ذخیره کنید، مدل را در بخش گفت‌وگو انتخاب کنید و همان پیام کوتاه آزمایشی را بفرستید. تورفتگی YAML را با فاصله حفظ کنید؛ خطای خواندن پیکربندی را پیش از تغییر کلید یا مدل رفع کنید.
این نمونه عمداً نقش chat دارد. مرجع رسمی Continue نقش‌های دیگری را تعریف میکند و برای حالت Agent به قابلیت tool_use نیاز دارد؛ قابلیت‌ها را باید با مدل واقعی تطبیق داد. مرجع رسمی config.yaml
پس از آزمون گفت‌وگو، برای توسعهٔ پیکربندی از راهنمای Continue استفاده کنید. داشتن یک مدل متنی در تنظیمات، به‌تنهایی نشانهٔ آماده‌بودن تکمیل خودکار، پردازش تصویر یا همهٔ ابزارهای عامل نیست.
اتصال n8n به هوش مصنوعی را چطور آزمایش کنیم؟
برای شروع، گردش‌کاری بسازید که فقط متن بگیرد و متن برگرداند. در نود OpenAI Chat Model گزینهٔ Use Responses API را خاموش نگه دارید؛ مستندات n8n می‌گویند حالت خاموش از Chat Completions استفاده میکند. مستندات رسمی OpenAI Chat Model
۱. یک گردشکار آزمایشی با Chat Trigger و Basic LLM Chain آماده کنید و OpenAI Chat Model را به ورودی مدلِ زنجیره متصل کنید. این چیدمان را برای آزمون یک پاسخ ساده به کار ببرید؛ ارسال پیام به مشتری یا نوشتن در پایگاه داده را به آزمون اول اضافه نکنید.
۲. برای مدل، Credential از نوع OpenAI بسازید. API Key را با کلید مخصوص n8n و Base URL را با https://1ai.ir/v1 پر کنید. Organization ID را برای این اتصال خالی بگذارید. فیلد Base URL و آزمون مسیر /models در کد رسمی Credential تعریف شده‌اند. کد رسمی Credential در مخزن n8n
۳. Credential را ذخیره و انتخاب کنید. در Model، شناسهٔ کامل مدل را قرار دهید؛ اگر فهرست انتخاب آن را نشان نمی‌دهد، در نسخه‌ای که ورود دستی شناسه دارد از همان مقدار آزموده‌شده استفاده کنید.
۴. Use Responses API را خاموش کنید. برای متن ورودی زنجیره از پیام Chat Trigger استفاده کنید؛ در تنظیمات زنجیره، حالت دریافت متن از Chat Trigger را انتخاب کنید. سپس این پیام را بفرستید:
برای درخواست زیر یک پاسخ رسمی دو جمله‌ای بنویس.
اطلاعاتی دربارهٔ زمان تحویل یا موجودی کالا اختراع نکن.
درخواست مشتری: لطفاً بگویید وضعیت سفارش من چطور پیگیری میشود؟۵. اجرای گردشکار و خروجی زنجیره را بررسی کنید. موفقیت ذخیرهٔ Credential را با موفقیت پاسخ مدل یکی نگیرید. پیش از اتصال خروجی به مقصد واقعی، متن تولیدشده و مصرف کلید را ببینید.
برای اتصال n8n به هوش مصنوعی در کار واقعی، ورودی هر اجرا را محدود نگه دارید و تعداد تلاش مجدد را متناسب با بودجه انتخاب کنید. جزئیات مسیر اتصال را در راهنمای n8n مرور کنید. اگر بعدها عامل می‌سازید، فراخوانی ابزار را با یک کار کوچک آزمایش کنید؛ از موفقیت زنجیرهٔ متنی نمی‌توان عملکرد همهٔ ابزارها را نتیجه گرفت.
اتصال Cursor به آدرس سفارشی امروز چه محدودیت‌هایی دارد؟
در بررسی اکتبر ۲۰۲۶، مستندات رسمی Cursor کلید شخصی را برای مدل‌های گفت‌وگو معرفی می‌کنند و می‌گویند Tab completion همچنان از مدل‌های داخلی استفاده میکند. همان صفحه برای بخش OpenAI، مدل‌های استانداردِ غیر reasoning را ذکر میکند؛ بنابراین نباید وعده داد هر مدل 1ai در هر حالت Cursor کار میکند. راهنمای رسمی کلید شخصی Cursor
۱. وارد Cursor Settings و سپس Models شوید. بخش API Keys را باز کنید و کلید 1ai را در فیلد OpenAI API Key قرار دهید. کلید و گزینهٔ فعال‌بودن آن را ذخیره کنید؛ عنوان دکمه ممکن است با نسخه فرق کند.
۲. گزینهٔ Override OpenAI Base URL را فعال کنید و مقدار آن را https://1ai.ir/v1 بگذارید. پاسخ پشتیبانی در انجمن رسمی Cursor این مسیر تنظیم را تأیید میکند. پاسخ رسمی دربارهٔ تنظیم کلید و Base URL
۳. از بخش افزودن مدل سفارشی، شناسهٔ کامل مدل متنی خود را وارد کنید. مدل داخلی با نام مشابه را معادل آن فرض نکنید. شناسه‌ای که Cursor ارسال میکند باید با شناسهٔ قابل‌قبول در 1ai یکسان باشد؛ نام دلخواه به‌جای اسلاگ واقعی مشکل را حل نمی‌کند.
۴. یک گفت‌وگوی جدید باز کنید، مدل سفارشی را صریح انتخاب کنید و یک پیام کوتاه بفرستید. اسلاگ نمونهٔ این مقاله تضمین سازگاری با Cursor نیست؛ اگر محدودیت مدل یا مسیر درخواست مانع شد، اتصال را موفق حساب نکنید.
۵. هنگام بازگشت به مدل‌های اشتراک Cursor، Override را خاموش کنید. طبق توضیح پشتیبانی رسمی در سپتامبر ۲۰۲۶، آدرس جداگانه برای هر مدل هنوز محدودیت دارد و روشن‌بودن Override می‌تواند مسیریابی مدل‌های داخلی را نیز درگیر کند. توضیح رسمی محدودیت مسیریابی Cursor
راهنمای Cursor در 1ai نقطهٔ مراجعه برای این اتصال است. اگر نسخهٔ شما مدل سفارشی را رد میکند یا مسیر /responses می‌فرستد و امکان تغییر ندارد، برای این API از Cline یا Continue استفاده کنید. اعتبار 1ai هزینهٔ سرویس‌های مستقل Cursor را پوشش نمی‌دهد؛ شرایط حساب خارجی را جدا بررسی کنید.
وقتی اتصال خطا می‌دهد، چه چیزهایی را بررسی کنیم؟
عیب‌یابی اتصال Cursor و Cline و n8n به API را از ساده‌ترین درخواست شروع کنید. ابتدا همان کلید و مدل را در ترمینال آزمایش کنید؛ بعد فقط یک مقدار را در ابزار تغییر دهید. تغییر هم‌زمان کلید، آدرس و مدل، علت خطا را پنهان میکند.
| نشانه | بررسی پیشنهادی |
|---|---|
خطای احراز هویت یا 401 | کلید کامل، فاصلهٔ اضافی، فعال‌بودن کلید و ذخیره‌شدن آن در ابزار |
| خطای مدل پیدا نشد | مقایسهٔ شناسه با id در فهرست مدل‌های همان حساب |
404 یا مسیر نامعتبر | بررسی تکرارنشدن /v1 و ارسال‌نشدن درخواست به /responses |
| توقف به علت اعتبار یا بودجه | بررسی موجودی حساب و سقف ماهانهٔ همان کلید |
محدودیت درخواست یا 429 | خواندن پیام خطا، کاهش هم‌زمانی و فاصله‌دادن به تلاش‌ها |
| پاسخ متنی موفق، کار با ابزار ناموفق | بررسی قابلیت مدل و قالب فراخوانی ابزار در اتصال انتخابی |
| قطع پاسخ طولانی | آزمایش با متن کوتاه‌تر و بررسی محدودیت خروجی و زمان انتظار |
کد وضعیت به‌تنهایی تشخیص قطعی نیست؛ متن خطا را هم بخوانید. در گزارش پشتیبانی، نام ابزار، نسخه، مسیر درخواست، شناسهٔ مدل و زمان رخداد را بنویسید و کلید و دادهٔ محرمانه را حذف کنید. اگر ترمینال موفق است اما ابزار خطا می‌دهد، تمرکز بعدی را روی پیکربندی و مسیر ارسالی همان ابزار بگذارید.
سقف مصرف API را چطور کنترل کنیم؟
در اتصال Cursor و Cline و n8n به API، یک درخواست کاربر ممکن است به چند درخواست مدل تبدیل شود. بودجه را برای کل فرایند در نظر بگیرید؛ ارسال تاریخچهٔ بیشتر، خروجی طولانی و تکرار خودکار می‌تواند مصرف را بالا ببرد.
برای هر ابزار کلید جدا بسازید و سقف ماهانهٔ همان کلید را تنظیم کنید. سقف کلید را با ظرفیت متن مدل یا تعداد پیام ثابت اشتباه نگیرید. روش مدیریت کلید و بودجه را در راهنمای کلیدهای API و کنترل هزینه دنبال کنید.
پیش از خودکارسازی، چند اجرای کوچک را با متن واقعی اما غیرمحرمانه آزمایش کنید. مصرف ثبت‌شده را ببینید، سپس تعداد اجرای موردنیاز خود را برآورد کنید. برای گردشکار زمان‌بندی‌شده، تعداد اجرا در روز، طول ورودی و دفعات تلاش مجدد را مشخص کنید؛ یک اجرای موفق، برآورد کافی برای کل ماه نیست.
برای انتخاب کار مناسب نیز از یک درخواست محدود شروع کنید. کاربردهای هوش مصنوعی در برنامه‌نویسی برای تعریف مسئله کمک میکند؛ اگر فقط به بازنویسی متن نیاز دارید، ابزار نوشتن با هوش مصنوعی ممکن است نیاز به ساخت گردشکار را برطرف کند.
سوالات متداول
آیا همین کلید در Claude Code و Codex CLI کار میکند؟
خیر؛ Claude Code و Codex CLI با API فعلی 1ai کار نمیکنند. مسیرهای لازم برای این اتصالها، یعنی Anthropic Messages و OpenAI Responses، در API توصیفشدهٔ این راهنما پشتیبانی نمیشوند؛ از ابزار سازگار با Chat Completions استفاده کنید.
آیا Base URL باید به chat/completions ختم شود؟
در تنظیمات ارائهدهندهٔ ابزارهای این راهنما، آدرس پایه https://1ai.ir/v1 است. مسیر کامل https://1ai.ir/v1/chat/completions برای ارسال مستقیم درخواست HTTP استفاده میشود.
چرا نام مدل در فهرست ابزار دیده نمی‌شود؟
فهرست آمادهٔ ابزار را با کاتالوگ 1ai یکسان فرض نکنید. مقدار دقیق id را از مسیر مدلها بگیرید و در صورت پشتیبانی ابزار، دستی وارد کنید؛ در Cursor محدودیت پذیرش مدل سفارشی را هم بررسی کنید.
آیا وصل‌شدن Cursor یعنی Tab هم از اعتبار 1ai مصرف میکند؟
خیر؛ طبق راهنمای رسمی Cursor که در بخش اتصال معرفی شد، Tab از مدل‌های داخلی Cursor استفاده میکند. پاسخ‌گرفتن در یک گفت‌وگو، پشتیبانی تمام قابلیت‌های ویرایشگر را ثابت نمی‌کند.
آیا برای شروع باید یک گردشکار کامل بسازم؟
خیر؛ ابتدا فهرست مدلها و یک پاسخ متنی کوتاه را آزمایش کنید. سپس اتصال ابزار و در مرحلهٔ بعد اجرای کار واقعی را با سقف مصرف محدود بررسی کنید.
اکنون یک کلید با سقف مشخص بسازید، مدل را از فهرست حساب خود بردارید و اولین پیام کوتاه را با 1ai ارسال کنید. پس از پاسخ موفق، همان تنظیمات را در ابزار انتخابی خود قرار دهید.
