اتصال Java به پیکو هوش

از Java 11 به بعد کلاس java.net.http.HttpClient در خود JDK هست و برای صدا زدن APIهای JSON کاملاً کافی است. این روش وابستگی ندارد، با Spring Boot و Quarkus و برنامه‌های ساده‌ی کنسولی کار می‌کند و رفتار آن کاملاً قابل پیش‌بینی است.

در پروژه‌های بزرگ‌تر می‌توانید بدنه را با Jackson بسازید و پاسخ را به کلاس‌های خودتان تبدیل کنید. در نمونه‌ی زیر برای کوتاه ماندن کد از text block (Java 15+) و پردازش ساده‌ی رشته استفاده شده است.

پیش‌نیازها

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

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

1. ۱درخواست چت با HttpClient

   کلید را از متغیر محیطی بخوانید.

   کپی

   import java.net.URI;
   import java.net.http.*;
   import java.time.Duration;
   
   public class Chat {
     public static void main(String[] args) throws Exception {
       String key = System.getenv("PICOAI_API_KEY");
       String body = """
         {"model":"gpt-6-sol",
          "messages":[{"role":"user","content":"سلام!"}]}
         """;
       HttpRequest req = HttpRequest.newBuilder(URI.create("https://api.picoai.ir/v1/chat/completions"))
           .timeout(Duration.ofSeconds(60))
           .header("Authorization", "Bearer " + key)
           .header("Content-Type", "application/json")
           .POST(HttpRequest.BodyPublishers.ofString(body))
           .build();
       HttpResponse<String> res = HttpClient.newHttpClient()
           .send(req, HttpResponse.BodyHandlers.ofString());
       System.out.println(res.statusCode() + " " + res.body());
     }
   }

2. ۲تجزیه‌ی پاسخ با Jackson

   برای استخراج متن پاسخ از ObjectMapper استفاده کنید.

   کپی

   ObjectMapper om = new ObjectMapper();
   JsonNode root = om.readTree(res.body());
   String text = root.path("choices").path(0).path("message").path("content").asText();

3. ۳تنظیم در Spring Boot

   یک RestClient یا WebClient با آدرس پایه بسازید و کلید را از application.properties بخوانید. آدرس پایه را با /v1 تنظیم کنید و مسیر نسبی chat/completions را بزنید.

   کپی

   @Bean
   RestClient picoClient(@Value("${picoai.key}") String key) {
     return RestClient.builder()
         .baseUrl("https://api.picoai.ir/v1")
         .defaultHeader("Authorization", "Bearer " + key)
         .build();
   }

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

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

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

نکته‌های کاربردی برای Java

• فقط یک نمونه HttpClient بسازید و دوباره استفاده کنید؛ ساختن آن برای هر درخواست هزینه دارد.
• برای استریم از BodyHandlers.ofLines استفاده کنید و خطوط data: را یکی‌یکی پردازش کنید.
• کلید را در Vault یا متغیر محیطی نگه دارید، نه در application.properties داخل مخزن.

عیب‌یابی

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

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