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

cURL ساده‌ترین راه برای آزمایش یک کلید، دیدن پاسخ خام و عیب‌یابی است. چون API فقط HTTP و JSON است، هر چیزی که بتواند درخواست POST بفرستد می‌تواند از آن استفاده کند و نمونه‌های این صفحه را به هر زبان دیگری هم می‌توان ترجمه کرد.

پیش از اتصال ابزارهای پیچیده‌تر مثل Cursor یا LangChain، یک بار با cURL مطمئن شوید که کلید، مدل و موجودی کیف پول درست است؛ بیشتر خطاهای اتصال همین‌جا آشکار می‌شوند.

پیش‌نیازها

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

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

1. ۱گرفتن فهرست مدل‌ها

   این درخواست کلید را اعتبارسنجی می‌کند و شناسه‌ی دقیق مدل‌ها را نشان می‌دهد.

   کپی

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

2. ۲درخواست چت

   بدنه JSON است و هدر Content-Type را فراموش نکنید.

   کپی

   curl https://api.picoai.ir/v1/chat/completions \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "model": "gpt-6-sol",
       "messages": [{"role": "user", "content": "سلام!"}]
     }'

3. ۳استریم

   با فلگ -N بافر cURL را خاموش کنید تا رویدادهای SSE لحظه‌ای دیده شوند.

   کپی

   curl -N https://api.picoai.ir/v1/chat/completions \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"model":"gpt-6-sol","stream":true,"messages":[{"role":"user","content":"عدد ۱ تا ۵ را بنویس"}]}'

4. ۴نقطه‌ی Anthropic

   برای قالب پیام‌های Anthropic از /v1/messages با همان کلید استفاده کنید.

   کپی

   curl https://api.picoai.ir/v1/messages \
     -H "x-api-key: YOUR_API_KEY" \
     -H "anthropic-version: 2023-06-01" \
     -H "Content-Type: application/json" \
     -d '{"model":"claude-sonnet-5-5","max_tokens":256,"messages":[{"role":"user","content":"سلام"}]}'

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

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

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

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

• برای خوانایی خروجی آن را به jq بدهید: curl ... | jq ".choices[0].message.content".
• کلید را در متغیر محیطی بگذارید و با $PICOAI_API_KEY در هدر استفاده کنید تا در تاریخچه‌ی شل نماند.
• برای دیدن هدرها و کد وضعیت از فلگ -i استفاده کنید؛ بدنه‌ی خطا همیشه JSON با فیلد error است.

عیب‌یابی

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

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