مستندات هوشوانا
API هوشوانا با OpenAI و Anthropic سازگار است. اگر قبلاً با این SDKها کار کرده‌اید، فقط آدرس پایه و کلید را عوض کنید.
آدرس پایه‌ی API
Base URL
https://hooshvana.ir/api/v1شروع
- شروع سریعدر چند دقیقه در هوشوانا ثبت‌نام کنید، کلید API بسازید و اولین درخواست خود را با cURL، Python یا Node.js به مدل‌های هوش مصنوعی بفرستید.
- احراز هویت و کلیدهای APIنحوه‌ی ارسال کلید API هوشوانا با هدر Bearer یا x-api-key، نگهداری امن کلیدها در متغیر محیطی، چرخش و ابطال کلید و الگوی پراکسی سمت سرور.
- قوانین کلید و گروه مدلبا قوانین کلید و حساب، مدل‌ها، endpointها، سقف هزینه، محدودیت نرخ، IP و تاریخ انقضا را کنترل کنید و با گروه‌های مدل دسترسی را ساده مدیریت کنید.
مرجع API
- Chat Completionsمرجع کامل endpoint چت هوشوانا: پارامترها، استریم SSE، فراخوانی ابزار، ورودی تصویر، خروجی JSON و json_schema، شیء usage و اتصال پایگاه دانش.
- Responses APIاستفاده از Responses API در هوشوانا: ساختار درخواست با input و instructions، رویدادهای استریم، تفاوت با Chat Completions و تنظیم Codex CLI.
- Anthropic Messages APIفراخوانی مدل‌های Claude با API سازگار با Anthropic در هوشوانا: هدرها، cURL، SDK پایتون و TypeScript، استریم رویدادها و فراخوانی ابزار.
- Embeddingsساخت بردار embedding برای متن فارسی و انگلیسی در هوشوانا: درخواست، ارسال دستهای، کاهش ابعاد، محاسبه‌ی شباهت کسینوسی و نرمالسازی متن فارسی.
- تولید تصویرساخت تصویر از متن با مدلهایی مثل GPT Image 2 در هوشوانا: پارامترها، اندازهها، ذخیرهی خروجی base64 در فایل و نحوه‌ی محاسبه‌ی هزینه.
- تبدیل متن به گفتارتبدیل متن فارسی و انگلیسی به صدا با مدل‌های OpenAI و ElevenLabs در هوشوانا: انتخاب صدا، قالبهای خروجی، ذخیرهی استریم در فایل و هزینه‌ی هر نویسه.
- تبدیل گفتار به متنتبدیل فایل صوتی فارسی به متن با whisper-1 و gpt-transcribe در هوشوانا: آپلود multipart، زبان fa، قالبهای خروجی و زیرنویس، حد حجم و هزینه‌ی هر دقیقه.
- فهرست مدلهادریافت فهرست مدل‌های در دسترس هوشوانا با GET /models، ساختار پاسخ، قالب شناسهی مدل‌ها و راهنمای انتخاب مدل مناسب برای هر کاربرد و بودجه.
امکانات
- پایگاه دانشبا پایگاه دانش هوشوانا سایت، فایلها و پایگاه دادهی خود را به مدل‌های هوش مصنوعی وصل کنید تا پاسخها بر اساس اطلاعات خودتان و با ذکر منبع باشد.
- سرور MCP هوشواناسرور MCP هوشوانا را به Claude Code، Cursor و سایر کلاینتها وصل کنید تا دستیار شما در پایگاه دانش جستجو کند، مدل‌ها را ببیند و مصرف حساب را گزارش دهد.
- لاگ درخواستهاهر درخواست به API هوشوانا با مدل، توکن، هزینه و وضعیت ثبت میشود. با لاگها مصرف را پیگیری کنید، خطاها را بیابید و با شناسهی درخواست اشکالزدایی کنید.
خطاها و محدودیت‌ها
- خطاها و کدهای خطافهرست کامل کدهای خطای API هوشوانا با وضعیت HTTP، معنی و راهحل هر کدام، به همراه راهنمای تلاش دوباره و نمونهکد مدیریت خطا در Python و Node.js.
- محدودیت نرخ درخواستمحدودیت تعداد درخواست و توکن در دقیقه (RPM و TPM) در هوشوانا، هدرهای محدودیت، مدیریت خطای ۴۲۹ با backoff نمایی و راههای کم کردن برخورد با محدودیت.