مستندات API
احراز هویت و کلیدهای API
هر درخواست به API هوشی با یک کلید شخصی که با hk- شروع می‌شود احراز می‌شود. کلید را در هر هدری که SDK رسمی پروایدرت استفاده می‌کند بفرست؛ هوشی همه را می‌شناسد.
ساخت کلید
- وارد کنسول توسعه‌دهندگان شو (با همان حساب هوشی).
- در بخش «کلیدهای API» روی «ساخت کلید» بزن، یک نام توصیفی (مثلاً «سرور production») بده و در صورت نیاز محدودیت‌ها را تنظیم کن.
- کلید کامل (مثل
hk-Xq3…) فقط یک‌بار نمایش داده می‌شود؛ هوشی فقط هش آن را نگه می‌دارد و بعداً فقط چهار حرف آخرش را می‌بینی. اگر گمش کردی، کلید را حذف و یک کلید تازه بساز.
هر حساب می‌تواند تا ۲۵ کلید فعال داشته باشد؛ برای هر محیط یا هر سرویس یک کلید جدا بساز تا مصرف و دسترسی‌ها قابل‌ردیابی باشند.
هدرهای پذیرفته‌شده
هوشی کلید را به ترتیب زیر جست‌وجو می‌کند و اولین مورد پیدا‌شده را استفاده می‌کند. همهٔ این روش‌ها روی هر دو API (یکپارچه و بومی) کار می‌کنند؛ بنابراین SDKهای رسمی بدون هیچ تغییری جز base_url و کلید کار می‌کنند.
| اولویت | روش ارسال | SDK / ابزار معمول |
|---|---|---|
| ۱ | Authorization: Bearer hk-... | OpenAI SDK، LangChain، Vercel AI SDK، cURL، Claude Code با ANTHROPIC_AUTH_TOKEN |
| ۲ | x-api-key: hk-... | Anthropic SDK (پایتون / TypeScript)، Claude Code با ANTHROPIC_API_KEY |
| ۳ | x-goog-api-key: hk-... | Google GenAI SDK |
| ۴ | xi-api-key: hk-... | ElevenLabs SDK |
| ۵ | x-key: hk-... | Black Forest Labs (FLUX) |
| ۶ | ?key=hk-... | کوئری‌استرینگ به سبک Gemini (در لاگ‌ها ثبت می‌شود؛ فقط برای تست) |
curl https://api.hooshi.ai/v1/balance \
-H "Authorization: Bearer $HOOSHI_API_KEY"پاسخ موفق:
{ "object": "balance", "currency": "IRT", "balance": 482350.5, "min_required": 1000 }endpoint عمومی
GET /v1/models و GET /v1/models/{id} بدون کلید هم پاسخ می‌دهند تا بتوانی فهرست مدل‌ها و قیمت‌ها را در ابزارها و صفحات عمومی نمایش دهی. بقیهٔ endpointها کلید می‌خواهند.
مراحل بررسی هر درخواست
قبل از ارسال درخواست به پروایدر، هوشی به ترتیب این موارد را بررسی می‌کند. اولین شرطی که برقرار نباشد، با خطای مربوطه پاسخ داده می‌شود و هزینه‌ای کسر نمی‌شود:
| بررسی | در صورت شکست | HTTP |
|---|---|---|
| کلید ارسال شده و با hk- شروع می‌شود | invalid_api_key | 401 |
| کلید وجود دارد، فعال است، منقضی نشده و حساب کاربر فعال است | invalid_api_key | 401 |
| IP درخواست در فهرست IPهای مجاز کلید است (اگر تعریف شده باشد) | ip_not_allowed | 403 |
| تعداد درخواست‌های دقیقهٔ جاری از سقف کلید بیشتر نشده | rate_limit_exceeded | 429 |
| موجودی کیف پول API حداقل به اندازهٔ حداقل موجودی است | insufficient_quota | 402 |
| مصرف ماه جاری این کلید از سقف هزینهٔ ماهانه‌اش کمتر است | spend_limit_reached | 402 |
| مدل درخواستی در فهرست مدل‌های مجاز کلید است (اگر تعریف شده باشد) | model_not_allowed | 403 |
محدودیت‌های قابل تنظیم برای هر کلید
همهٔ تنظیمات زیر از کنسول قابل تغییرند و بلافاصله (حداکثر با یک دقیقه تأخیر کش) اعمال می‌شوند.
| تنظیم | پیش‌فرض | توضیح |
|---|---|---|
| محدودیت نرخ (درخواست در دقیقه) | ۶۰ | بین ۱ تا ۳۰۰۰. جزئیات در محدودیت نرخ. |
| سقف هزینهٔ ماهانه (تومان) | بدون سقف | وقتی مجموع هزینهٔ این کلید از اول ماه میلادی جاری به سقف برسد، درخواست‌ها با 402 رد می‌شوند. |
| IPهای مجاز | همه | تا ۵۰ آدرس IPv4/IPv6. درخواست از IP دیگر با 403 رد می‌شود. آدرس دقیق را وارد کن؛ رنج (CIDR) پشتیبانی نمی‌شود. |
| مدل‌های مجاز | همه | فهرستی از شناسه‌های provider/model؛ مثلاً فقط openai/gpt-6-luna برای یک کلید تست ارزان. |
| تزریق هویت مدل | روشن | سیستم‌پرامپت کوتاهی که به مدل می‌گوید دقیقاً کدام مدل است. بیشتر بخوان. |
| تاریخ انقضا | ندارد | بعد از این تاریخ کلید به‌طور خودکار نامعتبر می‌شود؛ مناسب کلیدهای موقت پیمانکار یا هکاتون. |
| فعال / غیرفعال | فعال | بدون حذف کلید، موقتاً قطعش کن. |
کلیدهای جدا برای هر محیط
یک کلید برای توسعه با سقف هزینهٔ کم و مدل‌های ارزان، و یک کلید جدا برای production با IP سرور مجاز بساز. اگر کلیدی لو رفت، فقط همان را باطل می‌کنی.
بهترین روش‌های امنیتی
کلید را در متغیر محیطی نگه دار
import os
from openai import OpenAI
client = OpenAI(base_url="https://api.hooshi.ai/v1", api_key=os.environ["HOOSHI_API_KEY"])هرگز از مرورگر یا اپ موبایل مستقیم صدا نزن
کد سمت کلاینت قابل مشاهده است. یک endpoint کوچک در بک‌اند خودت بساز که کاربر را احراز کند و درخواست را با کلید هوشی به API بفرستد (نمونه در رابط چت استریمی). این‌طوری محدودیت مصرف هر کاربر را هم خودت کنترل می‌کنی.
کلیدها را دوره‌ای عوض کن
- کلید جدید بساز، در سرورها جایگزین کن و بعد کلید قدیمی را غیرفعال یا حذف کن؛ این‌طوری قطعی نداری.
- از ستون «آخرین استفاده» در کنسول و گزارش مصرف برای پیدا کردن کلیدهای بلااستفاده یا مصرف مشکوک استفاده کن.
- اگر کلیدی را در گیت‌هاب یا جای عمومی دیدی، فوراً از کنسول حذفش کن.
سقف هزینه و IP مجاز را جدی بگیر
حتی اگر کلید لو برود، سقف هزینهٔ ماهانه خسارت را محدود می‌کند و فهرست IP مجاز عملاً کلید را خارج از سرورهای تو بی‌استفاده می‌کند.
خطاهای احراز هویت
{
"error": {
"message": "Invalid, disabled or expired API key.",
"type": "invalid_api_key",
"code": "invalid_api_key",
"param": null
}
}فهرست کامل کدها در خطاها و تلاش مجدد آمده است.