اتصال OpenAI Node.js SDK به پیکو هوش

بسته‌ی openai در npm کلاینت رسمی OpenAI برای Node.js، Bun و Deno است و تایپ‌های TypeScript کامل دارد. با تغییر baseURL همین کلاینت به دروازه‌ی پیکو هوش وصل می‌شود و بقیه‌ی کد، از جمله استریم و تایپ‌ها، تغییری نمی‌کند.

این روش برای بک‌اند Express، Fastify، Next.js API Route و اسکریپت‌های خودکارسازی مناسب است. توجه کنید که کلید API نباید هرگز در کد سمت مرورگر قرار بگیرد؛ درخواست‌ها را از سرور خودتان ارسال کنید.

پیش‌نیازها

• یک حساب پیکو هوش و یک کلید API از داشبورد (کلید فقط یک‌بار کامل نمایش داده می‌شود).
• شناسه‌ی دقیق مدل از کاتالوگ؛ در مثال‌ها از gpt-6-sol و claude-sonnet-5-5 استفاده شده است.
• کمی موجودی در کیف پول تومانی یا اعتبار؛ تعرفه را در صفحه‌ی قیمت‌ها ببینید.

راه‌اندازی گام‌به‌گام

1. ۱نصب بسته

   Node.js نسخه‌ی ۱۸ یا بالاتر توصیه می‌شود.

   کپی

   npm install openai

2. ۲ساخت کلاینت

   گزینه‌ی baseURL و apiKey را هنگام ساخت بدهید. در ESM از import استفاده کنید.

   کپی

   import OpenAI from "openai";
   
   const client = new OpenAI({
     baseURL: "https://api.picoai.ir/v1",
     apiKey: process.env.PICOAI_API_KEY ?? "YOUR_API_KEY",
   });
   
   const res = await client.chat.completions.create({
     model: "gpt-6-sol",
     messages: [{ role: "user", content: "سلام! خودت را معرفی کن." }],
   });
   console.log(res.choices[0].message.content);

3. ۳استریم با for await

   با stream: true می‌توانید تکه‌ها را مستقیم به کلاینت وب منتقل کنید.

   کپی

   const stream = await client.chat.completions.create({
     model: "claude-sonnet-5-5",
     messages: [{ role: "user", content: "یک شعر کوتاه بنویس." }],
     stream: true,
   });
   for await (const chunk of stream) {
     process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
   }

4. ۴استفاده در Next.js Route Handler

   کلید را در متغیر محیطی سرور نگه دارید و از مسیر API خودتان صدا بزنید تا به مرورگر نرسد.

   کپی

   import OpenAI from "openai";
   
   const client = new OpenAI({ baseURL: "https://api.picoai.ir/v1", apiKey: process.env.PICOAI_API_KEY });
   
   export async function POST(req: Request) {
     const { messages } = await req.json();
     const res = await client.chat.completions.create({ model: "gpt-6-sol", messages });
     return Response.json(res.choices[0].message);
   }

تست سریع اتصال

پیش از نوشتن منطق برنامه، یک بار فهرست مدل‌ها را بگیرید. اگر پاسخ ۲۰۰ و فهرستی از شناسه‌ها برگشت، کلید، شبکه و آدرس درست است و هر مشکل بعدی مربوط به تنظیمات OpenAI Node.js SDK خواهد بود.

curl https://api.picoai.ir/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

نکته‌های کاربردی برای OpenAI Node.js SDK

• برای TypeScript نیازی به تایپ اضافه نیست؛ نوع پارامترها از خود بسته می‌آید.
• اگر پشت پراکسی سازمانی هستید، گزینه‌ی httpAgent (یا fetch سفارشی) را تنظیم کنید.
• در محیط Edge یا Cloudflare Workers هم همین کلاینت کار می‌کند چون فقط از fetch استفاده می‌کند.

عیب‌یابی

هزینه و صورتحساب

هر درخواست قبل از اجرا مقداری از موجودی را رزرو می‌کند و پس از پاسخ موفق بر پایه‌ی توکن‌های واقعی تسویه می‌شود؛ مابه‌التفاوت برمی‌گردد و درخواست ناموفق چیزی کم نمی‌کند. جدول قیمت هر مدل در صفحه‌ی قیمت‌ها منتشر شده و مصرف هر درخواست در داشبورد قابل مشاهده است. اگر قبلاً از سرویس دیگری استفاده می‌کردید، راهنمای مهاجرت و صفحه‌ی مقایسه را ببینید.