راهنمای اتصال api رایگان برای n8n با کایا ای آی

ابزار متن‌باز n8n یکی از قدرتمندترین پلتفرم‌های خودکارسازی فرایندها (Workflow Automation) است، اما پیاده‌سازی گره‌های هوش مصنوعی (AI Nodes) در آن برای کاربران داخل ایران چالش‌های مشخصی دارد. تحریم‌های ارائه‌دهندگان بین‌المللی نظیر OpenAI و Anthropic، مسدودسازی نشانی‌های IP ایران، و دشواری‌های پرداخت ارزی مانع اتصال مستقیم این سرویس‌ها به پایپ‌لاین‌های n8n می‌شوند. کایا ای آی (Kaya AI) به عنوان یک درگاه (Gateway) واسط، دسترسی به بیش از ۴۰۰ مدل زبانی گوناگون را با ساختاری کاملاً سازگار با OpenAI فراهم کرده است. با ثبت‌نام در کایا ای آی و دریافت ۱۰۰ اعتبار اولیه هدیه، می‌توانید یک api رایگان برای n8n در اختیار داشته باشید، اتوماسیون‌های خود را بدون نیاز به کارت‌های اعتباری بین‌المللی تست کنید و در صورت نیاز به توسعه، هزینه توکن‌ها را به‌صورت ریالی و Pay-as-you-go بپردازید.

پیش‌نیازهای اتصال کایا ای آی به n8n

پیش از راه‌اندازی گره‌ها در محیط n8n، باید مقدمات دسترسی به کلید احراز هویت را آماده کنید:

1. حساب کاربری فعال: ورود به کایا ای آی از طریق شماره موبایل و کد یک‌بارمصرف (OTP) انجام می‌شود. بلافاصله پس از ثبت‌نام، ۱۰۰ اعتبار هدیه جهت تست سناریوها به حساب شما منظور می‌شود.
2. ساخت کلید API: از منوی داشبورد کاربری، یک کلید API جدید ایجاد کرده و مقدار توکن رشته‌ای تولیدشده را کپی کنید. این کلید برای تایید هویت تمام درخواست‌های ارسالی از سمت n8n الزامی است.
3. محیط اجرای n8n: این راهنما با نسخه‌های خودمیزبان (Self-hosted via Docker/npm) و همچنین سرویس ابری n8n سازگار است. پیشنهاد می‌شود برای دسترسی به گره‌های هوش مصنوعی پیشرفته، از نسخه ۱.۰.۰ به بالا استفاده کنید.

روش اول: ارسال درخواست با گره HTTP Request

عمومی‌ترین روش برای فراخوانی API در n8n که با تمام نگارش‌های قدیمی و جدید سازگاری کامل دارد، استفاده از گره HTTP Request است. در این شیوه، ساختار کامل Payload و هدرها به‌صورت صریح تعیین می‌شوند.

پیکربندی گره HTTP Request

یک گره HTTP Request به محیط کاری اضافه کنید و پارامترهای زیر را مقداردهی نمایید:

• Method: مقدار را روی POST قرار دهید.
• URL: نشانی مستقیم اندپوینت چت را وارد کنید: https://kayaai.ir/api/v1/chat/completions
• Authentication: گزینه None را انتخاب کنید، زیرا توکن را از طریق هدر ارسال خواهیم کرد.
• Send Headers: فعال شود. دو هدر زیر را اضافه کنید:
  • Authorization: با مقدار Bearer YOUR_KAYA_API_KEY (کلید اختصاصی خود را جایگزین کنید)
  • Content-Type: با مقدار application/json
• Send Body: فعال شود. مقدار Body Content Type را روی JSON بگذارید.

1{
2  "model": "deepseek/deepseek-chat",
3  "messages": [
4    {
5      "role": "system",
6      "content": "شما یک دستیار تحلیل داده در پایپ‌لاین اتوماسیون هستید."
7    },
8    {
9      "role": "user",
10      "content": "متن ورودی مرحله قبل: {{ $json.my_input_text }}"
11    }
12  ],
13  "temperature": 0.3,
14  "max_tokens": 1000
15}

پاسخ بازگشتی از این اندپوینت، ساختاری استاندارد شامل شناسه، متادیتا و فیلد choices[0].message.content دارد که در گره‌های بعدی n8n با دستور {{ $json.choices[0].message.content }} قابل استخراج و پردازش خواهد بود. برای بررسی پارامترهای پیشرفته‌تر به مستندات API کایا ای آی مراجعه کنید.

روش دوم: استفاده از گره اختصاصی OpenAI با تغییر Base URL

پلتفرم n8n گره‌های پیش‌فرضی به نام OpenAI و همچنین گره‌های مبتنی بر چارچوب LangChain مانند OpenAI Chat Model دارد. از آنجا که کایا ای آی کاملاً با پروتکل OpenAI هماهنگ است، بدون نیاز به کدنویسی اضافی می‌توانید این گره‌ها را مستقیماً به کایا متصل کنید.

تنظیم Credentials برای کایا ای آی

1. در محیط n8n وارد بخش Credentials شوید و روی Add Credential کلیک کنید.
2. نوع Credential را OpenAI API انتخاب نمایید.
3. در فیلد API Key، کلید ایجادشده در پنل کایا ای آی را وارد کنید.
4. بخش Ignore SSL Issues را در حالت پیش‌فرض (خاموش) نگه دارید.
5. بخش کلیدی ماجرا فیلد Base URL است. به‌صورت پیش‌فرض آدرس رسمی OpenAI در این فیلد قرار دارد؛ آن را پاک کرده و آدرس زیر را وارد نمایید: https://kayaai.ir/api/v1
6. نام اتصال را مشخص کرده و ذخیره نمایید.

Base URL: https://kayaai.ir/api/v1
API Key:  kay-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

اکنون هر زمان از گره OpenAI یا گره‌های ترکیبی AI Agent و Information Extractor در n8n استفاده کنید، تنها کافی است مدل مدنظرتان را به‌صورت دستی تایپ کنید (مثلاً gpt-4o-mini یا مدل‌های سایر ارائه‌دهندگان نظیر google/gemini-2.0-flash یا deepseek/deepseek-chat). فهرست تمامی شناسه‌های مدل در کاتالوگ مدل‌های کایا ای آی در دسترس است.

مقایسه دو شیوه اتصال در n8n

سناریوهای کاربردی اتوماسیون

سناریو ۱: خلاصه‌سازی خودکار ایمیل‌های دریافتی

در این گردش‌کار، یک ایمیل جدید از طریق گره Gmail Trigger یا Email Read (IMAP) دریافت شده و پس از استخراج متن اصلی، توسط هوش مصنوعی خلاصه‌سازی و به کانال اعلان‌ها ارسال می‌شود.

[Email Trigger] ➔ [Code: پاکسازی HTML] ➔ [HTTP Request: کایا ای آی] ➔ [Telegram / Slack Node]

تنظیمات بدنه JSON در گره HTTP Request:

1{
2  "model": "google/gemini-2.0-flash",
3  "messages": [
4    {
5      "role": "system",
6      "content": "شما دستیار اتوماسیون ایمیل هستید. متن داده‌شده را در ۳ الی ۵ نکته کلیدی به زبان فارسی و با لحن رسمی خلاصه کنید. اگر اقدامی (Action Item) برای مخاطب الزامی است، آن را جداگانه بنویسید."
7    },
8    {
9      "role": "user",
10      "content": "موضوع ایمیل: {{ $json.subject }}\nمتن ایمیل: {{ $json.textPlain }}"
11    }
12  ],
13  "temperature": 0.2
14}

سناریو ۲: تریاژ و دسته‌بندی تیکت‌های پشتیبانی (JSON خروجی ساختاریافته)

در سناریوهای سازمانی، خروجی چت‌بات باید در قالب JSON خالص باشد تا گره‌های شرطی (If Node یا Switch Node) بتوانند پیام را به تیم متناسب (فنی، مالی، عمومی) هدایت کنند.

[Webhook: فرم پیام] ➔ [HTTP Request: کایا ای آی] ➔ [JSON Parse] ➔ [Switch: بر اساس دپارتمان]

تنظیمات بدنه JSON برای دسته‌بندی دقیق:

1{
2  "model": "deepseek/deepseek-chat",
3  "messages": [
4    {
5      "role": "system",
6      "content": "پیام مشتری را تحلیل کن و یک خروجی JSON معتبر با کلیدهای 'category' (فقط یکی از مقادیر: 'technical'، 'billing'، 'general') و 'priority' ('high'، 'medium'، 'low') و 'sentiment' تولید کن. هیچ متن توضیحی اضافه ارسال نکن."
7    },
8    {
9      "role": "user",
10      "content": "{{ $json.body.customer_message }}"
11    }
12  ],
13  "response_format": {
14    "type": "json_object"
15  },
16  "temperature": 0.1
17}

خروجی مرحله فوق را در مرحله بعد با متد استاندارد JSON پارس کرده و پایپ‌لاین را شاخه‌بندی کنید:

// کد داخل گره Code در n8n برای استخراج ساختار
const rawResponse = $input.first().json.choices[0].message.content;
return JSON.parse(rawResponse);

انتخاب مدل مناسب برای اتوماسیون‌های n8n

انتخاب مدل برای گردش‌کارهای خودکار ارتباط مستقیمی با سرعت پاسخ‌دهی (Latency) و مصرف اعتبار دارد:

• مدل‌های سریع و مقرون‌به‌صرفه: برای وظایف با حجم تکرار بالا نظیر خلاصه‌سازی کوتاه، ترجمه سریع، تغییر فرمت داده‌ها، برچسب‌گذاری (Tagging) و استخراج ابرداده، مدل‌هایی مانند google/gemini-2.0-flash یا deepseek/deepseek-chat ایده‌آل هستند. این مدل‌ها به دلیل زمان تاخیر بسیار پایین، از ایجاد گلوگاه زمانی (Bottleneck) در صف اتوماسیون n8n جلوگیری می‌کنند.
• مدل‌های استدلال‌گر و پرچم‌دار: زمانی که فرآیند شما نیازمند تصمیم‌گیری‌های پیچیده، تولید کدهای تحلیلی در پایپ‌لاین یا بازنویسی مستندات حساس سازمانی است، مدل‌های قدرتمندی نظیر خانواده gpt-4o یا مدل‌های anthropic/claude-3-5-sonnet کیفیت استنتاج بالاتری ارائه می‌دهند.

جدول هزینه‌ها و نرخ مصرف توکن مدل‌های مختلف در بخش قیمت‌گذاری کایا ای آی شفاف‌سازی شده است. کارمزد سرویس در تمامی درخواست‌ها ۲٪ است.

مدیریت خطاها، محدودیت نرخ و سقف مصرف

اتوماسیون‌ها در معرض قطعی‌های شبکه‌ای، خطاهای محدودیت نرخ (Rate Limit) و تغییرات ناگهانی حجم ترافیک قرار دارند. برای ایجاد یک پایپ‌لاین پایدار به این نکات توجه کنید:

1. فعال‌سازی Retry On Fail: در تنظیمات پیشرفته (Settings) هر گره در n8n، گزینه‌های Retry On Fail و Max Tries را فعال کنید. مقدار تلاش مجدد را روی ۳ و فاصله میان تلاش‌ها را روی ۳۰۰۰ میلی‌ثانیه بگذارید تا خطاهای موقت شبکه یا خطای کد ۴۲۹ بدون شکست ورک‌فلو پشت سر گذاشته شوند.
2. بررسی کدهای وضعیت HTTP: در گره HTTP Request می‌توانید خطاهای کلاینت را بررسی کنید. در صورتی که اعتبار شما به اتمام برسد، پاسخ خطای ۴۰۲ یا ۴۰۳ دریافت خواهید کرد.
3. تعیین سقف مصرف (Spend Caps): اگر در n8n تریگرهای دوره‌ای یا وب‌هوک‌های عمومی دارید، برای جلوگیری از سوءاستفاده احتمالی یا لوپ‌های بی‌پایان محاسباتی، می‌توانید روی هر کلید API در پنل کاربری کایا ای آی محدودیت سقف مصرف تعیین کنید. با رسیدن به این سقف، درخواست‌های بعدی مسدود می‌شوند و از مصرف ناخواسته مانده‌حساب ریالی شما جلوگیری به عمل می‌آید.