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

بخش بزرگی از وب فارسی روی PHP و لاراول ساخته شده است. برای صدا زدن API لازم نیست کتابخانه‌ی خاصی داشته باشید؛ افزونه‌ی cURL که همراه PHP است یا Guzzle کافی است. اگر بسته‌ی جامعه‌ی openai-php/client را می‌پسندید، آن هم با تغییر آدرس پایه کار می‌کند.

در محیط‌های اشتراکی (هاست cPanel) فراموش نکنید که extension=curl فعال باشد و timeout اسکریپت برای پاسخ‌های طولانی بالا برده شود.

پیش‌نیازها

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

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

1. ۱درخواست ساده با cURL داخلی

   بدون هیچ وابستگی؛ فقط افزونه‌ی curl.

   کپی

   <?php
   $apiKey = getenv("PICOAI_API_KEY") ?: "YOUR_API_KEY";
   $payload = json_encode([
       "model" => "gpt-6-sol",
       "messages" => [["role" => "user", "content" => "سلام!"]],
   ], JSON_UNESCAPED_UNICODE);
   
   $ch = curl_init("https://api.picoai.ir/v1/chat/completions");
   curl_setopt_array($ch, [
       CURLOPT_POST => true,
       CURLOPT_RETURNTRANSFER => true,
       CURLOPT_TIMEOUT => 60,
       CURLOPT_HTTPHEADER => [
           "Authorization: Bearer " . $apiKey,
           "Content-Type: application/json",
       ],
       CURLOPT_POSTFIELDS => $payload,
   ]);
   $body = curl_exec($ch);
   $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
   curl_close($ch);
   
   $data = json_decode($body, true);
   echo $status === 200 ? $data["choices"][0]["message"]["content"] : ($data["error"] ?? "خطا");

2. ۲استفاده از Guzzle

   در لاراول Guzzle نصب است. پایه‌ی آدرس را یک بار در کلاینت بدهید.

   کپی

   use GuzzleHttp\Client;
   
   $client = new Client([
       "base_uri" => "https://api.picoai.ir/v1/",
       "headers" => ["Authorization" => "Bearer " . env("PICOAI_API_KEY")],
       "timeout" => 60,
   ]);
   $res = $client->post("chat/completions", [
       "json" => ["model" => "gpt-6-sol", "messages" => [["role" => "user", "content" => "سلام"]]],
   ]);
   $data = json_decode((string) $res->getBody(), true);

3. ۳بسته‌ی openai-php/client (اختیاری)

   این بسته‌ی جامعه با withBaseUri می‌تواند آدرس را بپذیرد؛ آدرس را بدون https:// بدهید. نسخه‌ی بسته را از مستندات آن بررسی کنید.

   کپی

   // composer require openai-php/client
   $client = OpenAI::factory()
       ->withApiKey(getenv("PICOAI_API_KEY"))
       ->withBaseUri("api.picoai.ir/v1")
       ->make();
   
   $res = $client->chat()->create([
       "model" => "gpt-6-sol",
       "messages" => [["role" => "user", "content" => "سلام"]],
   ]);
   echo $res->choices[0]->message->content;

4. ۴ذخیره‌ی کلید در لاراول

   کلید را در فایل .env قرار دهید و از config() بخوانید تا وارد گیت نشود.

   کپی

   PICOAI_API_KEY=YOUR_API_KEY

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

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

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

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

• JSON_UNESCAPED_UNICODE باعث می‌شود متن فارسی در بدنه خوانا بماند و حجم درخواست کمتر شود.
• برای کارهای طولانی از صف (Queue) استفاده کنید تا کاربر منتظر پاسخ مدل نماند.
• پاسخ‌های پرتکرار را کش کنید؛ هم سرعت بیشتر می‌شود و هم هزینه کمتر.

عیب‌یابی

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

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