n8n و پیکو هوش؛ نود OpenAI و HTTP Request برای اتوماسیون
در n8n با تغییر Base URL در Credential نود OpenAI یا با نود HTTP Request، مدل‌های پیکو هوش را در اتوماسیون‌ها استفاده کنید؛ با نمونه‌ی JSON کامل.
پیکو هوش·انتشار: ·به‌روزرسانی: ·۵ دقیقه مطالعه
خلاصه: در n8n دو راه برای استفاده از پیکو هوش دارید: (۱) Credential از نوع OpenAI را با Base URL سفارشی بسازید و در نودهای OpenAI/AI Agent استفاده کنید، (۲) از نود HTTP Request استفاده کنید که کنترل کامل می‌دهد و مستقل از نسخه کار می‌کند. روش دوم مطمئن‌ترین است.
روش ۱: Credential با Base URL
۱. در n8n به Credentials بروید و Create credential بزنید. ۲. نوع OpenAI API را انتخاب کنید. ۳. فیلد API Key را با YOUR_API_KEY پر کنید. ۴. فیلد Base URL را (در صورت وجود) روی https://api.picoai.ir/v1 بگذارید. توجه: صفحه‌ی رسمی Credential اوپن‌ای‌آی در مستندات n8n فقط API Key و Organization ID را شرح می‌دهد و فیلد Base URL را مستند نکرده است؛ در بسیاری از نسخه‌ها این فیلد در رابط (گاهی زیر Advanced) دیده می‌شود، اما اگر در نسخه‌ی شما نبود از روش ۲ استفاده کنید. ۵. ذخیره و تست کنید.
سپس در نود OpenAI Chat Model (برای AI Agent و زنجیره‌ها) همین Credential را انتخاب کنید و در Model نام دلخواه را بنویسید (حالت Expression یا Custom). مستندات رسمی می‌گوید این نود فهرست مدل‌ها را به‌صورت پویا از OpenAI می‌خواند و به‌طور پیش‌فرض از Chat Completions استفاده می‌کند (گزینه‌ی Responses API پیش‌فرض خاموش است)؛ آن را روشن نکنید، چون پیکو هوش فقط مسیر /v1/chat/completions را دارد و سازگاری Responses API تأیید نشده است. نودهایی که به اندپوینت‌های دیگر OpenAI (مثل Assistants) متکی‌اند با پیکو هوش کار نمی‌کنند؛ فقط چت پشتیبانی می‌شود. اگر نود چت نام مدل را فقط از فهرست ثابت OpenAI می‌پذیرد، از روش ۲ استفاده کنید.
روش ۲: نود HTTP Request
تنظیمات نود:
Method: POST
URL: https://api.picoai.ir/v1/chat/completions
Authentication: Generic Credential Type و سپس Header Auth با Name برابر Authorization و Value برابر Bearer YOUR_API_KEY
Claude Code را با متغیرهای ANTHROPIC_BASE_URL و کلید پیکو هوش روی اندپوینت سازگار با Anthropic (/v1/messages) اجرا کنید؛ مرحله‌به‌مرحله و با عیب‌یابی.
·
خبرنامه
آموزش‌ها و تغییرات جدید را به‌موقع بگیرید
فقط مطالب مفید دربارهی API هوش مصنوعی؛ بدون هرزنامه.
Specify Body: Using JSON
بدنه‌ی JSON:
{
"model": "claude-haiku-5-5",
"messages": [
{"role": "system", "content": "فقط به فارسی و در یک جمله پاسخ بده."},
{"role": "user", "content": "{{ $json.text }}"}
],
"max_tokens": 200,
"temperature": 0.2
}
پاسخ در {{ $json.choices[0].message.content }} قرار دارد. برای استفاده در نود بعدی (مثلاً ایمیل یا Slack) از همین عبارت استفاده کنید.
نمونه‌ی ورک‌فلو: خلاصه‌ی خودکار ایمیل
Trigger: Gmail Trigger یا Webhook
HTTP Request: درخواست خلاصه‌سازی به پیکو هوش
IF: بررسی طول پاسخ
Slack / Email: ارسال خلاصه
پرامپت پیشنهادی: «متن زیر را در سه بولت فارسی خلاصه کن: {{ $json.body }}». چون ایمیل‌ها می‌توانند طولانی باشند، با نود Code متن را به ۴۰۰۰ نویسه محدود کنید تا هزینه‌ی ورودی کنترل شود.
مدیریت خطا و Retry
در تنظیمات نود HTTP Request:
Retry On Fail: روشن، تعداد تلاش ۳، فاصله ۲۰۰۰ میلی‌ثانیه (برای خطاهای 429 و 503)
On Error: «Continue (using error output)» تا بتوانید شاخه‌ی خطا بسازید
خطای 402 یعنی موجودی ناکافی؛ این را با شاخه‌ی خطا به خودتان اطلاع دهید. توضیح همه‌ی کدها: کدهای خطا و استراتژی Retry.
هزینه
هر اجرای ورک‌فلو که روی تعداد زیادی آیتم حلقه بزند، به‌تعداد آیتم‌ها درخواست پولی می‌فرستد. قبل از اجرای انبوه روی ۳ تا ۵ آیتم تست کنید، max_tokens بگذارید و از مدل اقتصادی استفاده کنید. فرمول در تخمین هزینه؛ قیمت‌ها در pricing.
عیب‌یابی
علامت
علت
راه‌حل
401
هدر Authorization
Bearer با فاصله و کلید درست
400
JSON نامعتبر (نقل‌قول داخل متن)
از JSON.stringify در Expression استفاده کنید
404
URL
/v1/chat/completions کامل
نود OpenAI مدل را نمی‌پذیرد
فهرست ثابت مدل
HTTP Request
429
حلقه‌ی پرسرعت
Wait نود یا Batching
پاسخ خالی
مسیر JSON
choices[0].message.content
الگوی دسته‌ای: پردازش فهرستی از آیتم‌ها
وقتی چند صد آیتم دارید (مثلاً دسته‌بندی نظرات)، از نود Loop Over Items با اندازه‌ی دسته‌ی ۵ و یک نود Wait یک‌ثانیه‌ای بین دسته‌ها استفاده کنید. این کار از خطای 429 جلوگیری می‌کند و پیش‌بینی هزینه را ساده می‌کند. در پرامپت از مدل بخواهید خروجی فقط JSON باشد، مثلاً {"category": "...", "sentiment": "..."}، و در نود Code آن را پارس کنید. اگر پارس شکست خورد، مسیر خطا را به یک شاخه‌ی بازبینی دستی بفرستید.
ذخیره‌ی نتیجه
بعد از نود HTTP Request می‌توانید نتیجه را در Google Sheets، Airtable، پایگاه داده یا Webhook دیگر ذخیره کنید. توصیه می‌شود شناسه‌ی آیتم، مدل استفاده‌شده و usage.total_tokens را هم ذخیره کنید تا بعداً بتوانید هزینه را ردیابی و بین مدل‌ها مقایسه کنید.
امنیت
کلید را در Credential نگه دارید، نه مستقیم در بدنه‌ی نود.
خروجی ورک‌فلو را (Export) بدون حذف Credential منتشر نکنید؛ فایل Export معمولاً کلید را ندارد، اما نام Credential را دارد.
اگر ورک‌فلو با Webhook عمومی شروع می‌شود، احراز هویت یا secret برای آن بگذارید، وگرنه دیگران می‌توانند هزینه‌ی شما را مصرف کنند.
متن ورودی کاربران ممکن است شامل دستورهای تزریقی باشد (prompt injection)؛ خروجی مدل را قبل از اجرای عملیات حساس (حذف، پرداخت) بازبینی کنید.
n8n خودمیزبان یا ابری
رفتار نودها در هر دو یکسان است. در نسخه‌ی خودمیزبان مطمئن شوید سرور به api.picoai.ir دسترسی شبکه دارد و timeout نود HTTP Request (در Options) و timeout اجرای ورک‌فلو برای پاسخ‌های طولانی کافی باشد. برای پاسخ‌های بسیار بلند، max_tokens و timeout نود را با هم تنظیم کنید.
سوالات متداول
کدام روش بهتر است؟
HTTP Request انعطاف و پایداری بیشتری دارد؛ نود OpenAI برای ساخت سریع با AI Agent راحتتر است.
آیا استریم در n8n ممکن است؟
نود HTTP Request پاسخ کامل را برمیگرداند؛ استریم معمولاً در n8n کاربرد ندارد.