اتصال C# و .NET به پیکو هوش

کتابخانه‌ی رسمی OpenAI برای .NET با بسته‌ی NuGet به نام OpenAI منتشر می‌شود و کلاینت آن گزینه‌ی Endpoint دارد. با تغییر Endpoint به آدرس پیکو هوش، برنامه‌ی ASP.NET Core، سرویس Worker یا ابزار کنسولی شما به همه‌ی مدل‌های کاتالوگ دسترسی پیدا می‌کند.

اگر ترجیح می‌دهید وابستگی نداشته باشید، HttpClient همراه .NET با System.Text.Json کاملاً کافی است.

پیش‌نیازها

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

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

1. ۱نصب بسته

   بسته‌ی رسمی را اضافه کنید.

   کپی

   dotnet add package OpenAI

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

   OpenAIClientOptions.Endpoint را روی آدرس پایه بگذارید و ChatClient را با نام مدل بگیرید.

   کپی

   using System.ClientModel;
   using OpenAI;
   using OpenAI.Chat;
   
   var options = new OpenAIClientOptions { Endpoint = new Uri("https://api.picoai.ir/v1") };
   var client = new OpenAIClient(
       new ApiKeyCredential(Environment.GetEnvironmentVariable("PICOAI_API_KEY")!),
       options);
   
   ChatClient chat = client.GetChatClient("gpt-6-sol");
   ChatCompletion res = chat.CompleteChat("سلام!");
   Console.WriteLine(res.Content[0].Text);

3. ۳بدون وابستگی با HttpClient

   برای دیدن دقیق درخواست و پاسخ، این روش شفاف‌تر است.

   کپی

   using var http = new HttpClient { BaseAddress = new Uri("https://api.picoai.ir/v1/") };
   http.DefaultRequestHeaders.Authorization =
       new("Bearer", Environment.GetEnvironmentVariable("PICOAI_API_KEY"));
   
   var res = await http.PostAsJsonAsync("chat/completions", new {
       model = "gpt-6-sol",
       messages = new[] { new { role = "user", content = "سلام" } }
   });
   Console.WriteLine(await res.Content.ReadAsStringAsync());

4. ۴ثبت در DI

   در ASP.NET Core کلاینت را Singleton ثبت کنید تا در سرویس‌ها تزریق شود.

   کپی

   builder.Services.AddSingleton(_ => new OpenAIClient(
       new ApiKeyCredential(builder.Configuration["PicoAi:Key"]!),
       new OpenAIClientOptions { Endpoint = new Uri("https://api.picoai.ir/v1") }));

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

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

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

نکته‌های کاربردی برای C# و .NET

• کلید را با User Secrets در توسعه و با Key Vault یا متغیر محیطی در تولید نگه دارید.
• برای IHttpClientFactory، مدت‌زمان Timeout پیش‌فرض ۱۰۰ ثانیه است؛ برای پاسخ‌های طولانی استریم را ترجیح دهید.
• نام کلاس‌ها بین نسخه‌های بسته ممکن است تغییر کند؛ نسخه‌ی NuGet را ثابت نگه دارید.

عیب‌یابی

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

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