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

Postman ابزار گرافیکی آزمایش APIهاست و برای کسی که هنوز آماده‌ی نوشتن کد نیست بهترین نقطه‌ی شروع است. در چند دقیقه می‌توانید یک Environment با آدرس پایه و کلید بسازید، فهرست مدل‌ها را بگیرید و اولین درخواست چت را بفرستید.

متغیرهای محیطی باعث می‌شود کلید در درخواست‌ها تکرار نشود و بتوانید برای تست و تولید دو محیط جدا داشته باشید.

پیش‌نیازها

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

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

1. ۱ساخت Environment

   یک Environment جدید بسازید و دو متغیر تعریف کنید. نوع متغیر کلید را Secret بگذارید.

   کپی

   base_url = https://api.picoai.ir/v1
   api_key  = YOUR_API_KEY

2. ۲درخواست فهرست مدل‌ها

   یک درخواست GET بسازید و در تب Authorization نوع Bearer Token را انتخاب کنید.

   کپی

   GET {{base_url}}/models
   Authorization: Bearer {{api_key}}

3. ۳درخواست چت

   درخواست POST با بدنه‌ی raw و نوع JSON.

   کپی

   POST {{base_url}}/chat/completions
   Authorization: Bearer {{api_key}}
   Content-Type: application/json
   
   {
     "model": "gpt-6-sol",
     "messages": [{"role": "user", "content": "سلام!"}]
   }

4. ۴تست خودکار (اختیاری)

   در تب Tests یک بررسی ساده بنویسید تا پس از هر اجرا وضعیت را ببینید.

   کپی

   pm.test("status is 200", () => pm.response.to.have.status(200));
   pm.test("has content", () => {
     const j = pm.response.json();
     pm.expect(j.choices[0].message.content).to.be.a("string");
   });

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

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

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

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

• کلید را در Collection عمومی یا Workspace اشتراکی ننویسید؛ از متغیر Secret و Environment محلی استفاده کنید.
• برای استریم از تب Console در Postman برای دیدن رویدادها استفاده کنید؛ رابط نمایش Postman همیشه رویدادهای SSE را زنده نشان نمی‌دهد.
• درخواست‌ها را به Collection تبدیل و با تیم به‌اشتراک بگذارید (بدون کلید).

عیب‌یابی

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

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