API چت هوشا

از طریق یک اندپوینت واحد که با فرمت OpenAI Chat Completions سازگار است، با مدل‌های GPT 6.1 Terra، Gemini 3.8 Flash، DeepSeek V4.1 Flash، GLM 5.3 FlashX و Muse Spark 1.3 چت کنید. همه SDKهای OpenAI با آن کار می‌کنند؛ کافی است آدرس پایه (base URL) را روی هوشا بگذارید و از کلید API هوشای خود استفاده کنید.

هوشا در ایجنت‌های کدنویسیراه‌اندازی Cline، Roo Code، Claude Code، OpenCode، Continue، Aider و Zed، قدم به قدم.راهنمای اتصال

شروع سریع

کد
from openai import OpenAI

client = OpenAI(
    base_url="https://api.hoosha.com/v1",
    api_key="sk-hoosha-...",
)

reply = client.chat.completions.create(
    model="gemini-3.8-flash",
    messages=[{"role": "user", "content": "What is HTTP caching?"}],
)
print(reply.choices[0].message.content)
print(reply.usage.cost_credits, "credits")

کد
curl https://api.hoosha.com/v1/chat/completions \
  -H "Authorization: Bearer sk-hoosha-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

احراز هویت

کلید خود را به شکل Authorization: Bearer sk-hoosha-… بفرستید. کلیدها در کنسول برنامه‌نویسان هوشا ساخته و باطل می‌شوند و همین کلید برای API مدیا هم کار می‌کند.

مدل‌ها

هر مدل همیشه روی یک پرووایدر ثابت اجرا می‌شود. درخواست‌ها هرگز به مدل یا پرووایدر دیگری منتقل نمی‌شوند.

مدل	کانتکست	حداکثر خروجی	ورودی	ورودی کش‌شده	خروجی
gpt-6.1-terra	922,000	128,000	121.33	6.07	606.63
muse-spark-1.3-contributor	1,048,576	131,072	12.13	0.24	24.27
deepseek-v4.1-flash-1017	1,048,576	131,072	18.20	0.36	72.80
gemini-3.8-flash	1,048,576	65,536	90.99	9.10	454.97
glm-5.3-flashx	1,048,576	131,072	44.89	10.92	151.66

کانتکست و حداکثر خروجی بر حسب توکن‌اند و قیمت‌ها بر حسب اعتبار به ازای هر میلیون توکن. توکن‌های reasoning با نرخ توکن خروجی محاسبه می‌شوند. prefix تکراری پرامپت که پرووایدر آن را کش کرده باشد، با قیمت ورودی کش‌شده محاسبه می‌شود؛ در gpt-6.1-terra نوشتن یک prefix طولانی در کش، 1.25 برابر قیمت ورودی هزینه دارد. اندپوینت GET /models هم همین ارقام را برمی‌گرداند.

مدل muse-spark-1.3-contributor در سطح contributor متا ارائه می‌شود؛ در این سطح، متا از ورودی‌هایی که به مدل فرستاده می‌شود برای آموزش مدل‌هایش استفاده می‌کند. داده‌ای را که نمی‌توانید در اختیار دیگران بگذارید، به این مدل نفرستید.

محاسبه هزینه

هزینه هر درخواست از موجودی اعتبار شما در هوشا کسر می‌شود و هیچ سهمیه رایگانی وجود ندارد.

1. وقتی درخواستی می‌رسد، بیشترین هزینه ممکن آن (ورودی به‌علاوه خروجی به اندازه max_tokens) از موجودی شما رزرو می‌شود. اگر موجودی برای این مقدار کافی نباشد، درخواست با 402 insufficient_credits رد می‌شود و هزینه‌ای کسر نمی‌شود.
2. وقتی کار مدل تمام شد، رزرو اعتبار با هزینه دقیق توکن‌های مصرف‌شده تسویه می‌شود و باقی آن به موجودی شما برمی‌گردد.
3. موجودی اعتبار همیشه عددی صحیح است، به همین دلیل بخش اعشاری اعتبار به درخواست بعدی شما منتقل می‌شود. فیلد usage.cost_credits هزینه دقیق هر درخواست را گزارش می‌کند. اگر هزینه درخواستی از رزرو اعتبارش بیشتر شود و موجودی شما برای پوشش مابه‌التفاوت کافی نباشد، این مابه‌التفاوت هم منتقل می‌شود و به رزرو اعتبار بعدی شما اضافه می‌شود.

برای درخواست ناموفق هزینه‌ای کسر نمی‌شود. درخواست بدون استریم که پس از 110 ثانیه تمام نشده باشد، 504 timeout برمی‌گرداند و برای آن هم هزینه‌ای کسر نمی‌شود. در درخواست استریمی، هزینه توکن‌هایی که مدل تولید کرده است کسر می‌شود، حتی اگر اتصال را زودتر ببندید یا استریم به سقف 9 دقیقه‌ای خود برسد.

استریم

با تنظیم stream: true، پاسخ را به‌صورت eventهای SSE در فرمت chunkهای OpenAI دریافت می‌کنید که با data: [DONE] پایان می‌یابد. با افزودن stream_options: {"include_usage": true} یک chunk پایانی هم دریافت می‌کنید که آرایه choices آن خالی است و آبجکت usage را دارد. تا وقتی مدل در حال فکر کردن است، استریم هر 15 ثانیه یک خط کامنت : keep-alive می‌فرستد؛ کلاینت‌های SSE این خط‌ها را نادیده می‌گیرند.

اگر مدل پیش از فرستادن هر چیزی با خطا روبه‌رو شود، به‌جای استریم یک خطای معمولی HTTP دریافت می‌کنید. خطایی که پس از شروع استریم رخ دهد، به شکل یک event data: پایانی می‌رسد که ساختار خطا را در خود دارد و بعد از آن [DONE] نمی‌آید.

برای پاسخ‌های طولانی بهتر است از استریم استفاده کنید، چون درخواست بدون استریم باید ظرف 110 ثانیه تمام شود.

Reasoning

هر 5 مدل می‌توانند پیش از پاسخ دادن فکر کنند. میزان reasoning را با reasoning_effort تنظیم کنید (none، minimal، low، medium، high، xhigh). مدل‌های Muse، Gemini و GLM همیشه فکر می‌کنند و به همین دلیل none را نمی‌پذیرند؛ برای کمترین میزان reasoning از minimal استفاده کنید. توکن‌های reasoning جزو max_tokens حساب می‌شوند، پس اگر max_tokens کوچک باشد، ممکن است پاسخ پیش از شروع تمام شود (finish_reason: length).

اگر مدل reasoning خوانای خود را در اختیار بگذارد، این reasoning به شکل reasoning_content در پیام یا در delta استریم می‌آید. بعضی مدل‌ها reasoning_details را هم برمی‌گردانند؛ این‌ها بلوک‌هایی opaque هستند که می‌توانید در درخواست بعدی همراه پیام assistant دوباره بفرستید تا زنجیره reasoning مدل حفظ شود. کنار گذاشتن آن‌ها هم مجاز است.

Toolها، تصویرها و JSON

• Toolها. تعریف فانکشن‌ها را در tools بفرستید؛ tool callها در tool_calls و همراه با finish_reason: tool_calls برمی‌گردند. نتیجه هر tool call را در پیامی با role: tool و tool_call_id متناظر برگردانید.
• تصویرها. بخش‌هایی از نوع image_url به پیام user اضافه کنید؛ به شکل یک URL با https:// یا یک data URL به‌صورت base64 از تصویری با فرمت PNG، JPEG، GIF یا WebP. تصویرها همان‌طور که فرستاده‌اید به مدل داده می‌شوند و هوشا URLهای شما را دانلود نمی‌کند. هر درخواست حداکثر 32 تصویر می‌تواند داشته باشد.
• JSON. گزینه response_format: {"type": "json_object"} روی همه مدل‌ها کار می‌کند. مقدار json_schema روی همه مدل‌ها به‌جز deepseek-v4.1-flash-1017 کار می‌کند؛ این مدل با 400 unsupported_value پاسخ می‌دهد.

تصمیم‌ها

POST /decisions مدل تصمیم‌گیری Jev از TypeSafe را اجرا می‌کند. Jev متن نمی‌نویسد: محتوایی را که باید سنجیده شود در state می‌فرستید و questions نام‌گذاری‌شده‌ای درباره آن می‌پرسید. پاسخ هر سؤال تایپ‌دار و با احتمال‌های کالیبره‌شده برمی‌گردد تا کد شما مستقیم بر اساس آن عمل کند. درخواست و پاسخ از Decisions API پیروی می‌کنند، با آیدی‌های هوشا و قیمت به اعتبار.

مدل	کانتکست	ورودی	خروجی
jev-1.14	262,144	5.10	0.00

قیمت‌ها به اعتبار برای هر یک میلیون توکن است. Jev فقط برای ورودی هزینه می‌گیرد و تصویرها هم توکن ورودی حساب می‌شوند. usage.cost_credits هزینه دقیق هر تصمیم را گزارش می‌کند؛ اعتبار آن مانند درخواست چت رزرو و تسویه می‌شود و بخش اعشاری اعتبار به درخواست بعدی منتقل می‌شود. تصمیمی که پس از 110 ثانیه تمام نشده باشد 504 timeout برمی‌گرداند و هزینه‌ای ندارد.

نوع سؤال	چه می‌پرسد	پاسخ
noul	آیا این گزاره درست است؟ criteria اختیاری با true و false.	noul، احتمال بله
choice	کدام گزینه مناسب است؟ criteria هر گزینه را به توضیحش وصل می‌کند.	choice، probabilities، confidence
score	روی یک مقیاس کجا قرار می‌گیرد؟ criteria سطح‌ها را از پایین‌ترین فهرست می‌کند.	score، probabilities، legend، confidence
box	در تصویر کجاست؟	box با top، bottom، left و right به صورت کسری از تصویر

تصویرها در assets به صورت base64 ساده از PNG یا JPEG و با یک string رفرنس فرستاده می‌شوند. این رفرنس را هر جا که تصویر لازم است در state، instructions یا criteria بنویسید. asset بدون رفرنس رد می‌شود و هر بار تکرار رفرنس، تصویر را دوباره می‌فرستد. هر ضلع تصویر باید بین 256 تا 1,568 پیکسل باشد و TypeSafe تصویر و box را قابلیت‌هایی اولیه می‌داند که فرمتشان ممکن است تغییر کند. Jev زبان‌های دیگر را هم می‌خواند، اما دقتش در انگلیسی بهتر است.

پارامترهایی که مدل از آن‌ها استفاده نمی‌کند

پارامترهای sampling OpenAI (temperature، top_p، stop، seed، presence_penalty، frequency_penalty) روی همه مدل‌ها پذیرفته می‌شوند. مدلی که از یکی از این پارامترها پشتیبانی نکند، آن را نادیده می‌گیرد؛ فهرست supported_parameters هر مدل در GET /models نشان می‌دهد آن مدل کدام پارامترها را اعمال می‌کند. فیلدهایی که در این داکیومنت نیامده‌اند با 400 unsupported_parameter رد می‌شوند؛ به‌جز store و metadata که پذیرفته و نادیده گرفته می‌شوند، و هر فیلدی که با مقدار null فرستاده شود.

محدودیت‌ها

محدودیت	مقدار
درخواست‌ها	60 در دقیقه برای هر حساب
درخواست‌های GET /models	120 در دقیقه برای هر حساب
درخواست‌های هم‌زمان	4 برای هر حساب، چت و تصمیم روی هم
body درخواست	20 مگابایت
تصویرها	32 در هر درخواست
Toolها	128 در هر درخواست
مقدار پیش‌فرض max_tokens	8,192، یا سقف مدل اگر کمتر باشد
درخواست بدون استریم	110 ثانیه
درخواست استریمی	9 دقیقه
پیام‌ها	2,048 در هر درخواست
stop sequenceها	4
درخواست‌های تصمیم	120 در دقیقه برای هر حساب
سؤال‌ها در هر تصمیم	64
تصویرها در هر تصمیم	16

خطاها

خطاها با همان ساختار خطای OpenAI برگردانده می‌شوند، بنابراین SDKهای OpenAI همان exceptionهای همیشگی خود را throw می‌کنند:

کد
{ "error": { "message": "The model `gpt-4o` does not exist or you do not have access to it.", "type": "invalid_request_error", "param": "model", "code": "model_not_found" } }

وضعیت	code	علت
400	unsupported_parameter, invalid_value, unsupported_value, null	درخواست نامعتبر است؛ param نام فیلد را مشخص می‌کند.
400	context_length_exceeded	پیام‌ها در context window مدل جا نمی‌شوند.
400	upstream_rejected	مدل درخواست را نپذیرفت؛ برای نمونه به‌خاطر تصویری که خوانده نمی‌شود.
401	invalid_api_key	کلید ارسال نشده، نامعتبر است، باطل شده یا منقضی شده است.
402	insufficient_credits	موجودی شما برای پوشش بیشترین هزینه ممکن درخواست کافی نیست.
404	model_not_found	آیدی مدل در GET /models نیست.
413	request_too_large	حجم body بیشتر از 20 مگابایت است، یا مدل اندازه آن را نپذیرفت.
415	null	body با نوع application/json فرستاده نشده است.
429	rate_limit_exceeded, concurrency_limit_exceeded, upstream_rate_limited	تعداد درخواست‌ها بیش از حد مجاز است؛ به مدتی که Retry-After تعیین می‌کند صبر کنید.
502	upstream_error	مدل با خطا روبه‌رو شد. هزینه‌ای کسر نشده و تلاش دوباره بی‌خطر است.
503	service_unavailable, model_unavailable	سرویس چت یا مدل موقتاً در دسترس نیست. هزینه‌ای کسر نشده است.
504	timeout	مدل به‌موقع پاسخ نداد. هزینه‌ای کسر نشده است.

پاسخ 504 timeout هدر x-should-retry: false را دارد و SDKهای OpenAI از آن پیروی می‌کنند، چون تکرار همان درخواست طولانی باز هم timeout می‌شود. به‌جای آن، درخواست را به‌صورت استریم بفرستید.