مستندات API هوشی

API هوشی چیست؟#

API هوشی یک درگاه واحد برای مدل‌های زبانی، تصویری و صوتی دنیاست. دو سبک دسترسی داری که هر دو با یک کلید و یک کیف پول کار می‌کنند:

• API یکپارچه (Unified): یک API کاملاً سازگار با OpenAI روی https://api.hooshi.ai/v1. مدل را با فرمت provider/model انتخاب می‌کنی (مثلاً anthropic/claude-opus-5-5) و هوشی درخواست را به فرمت همان پروایدر ترجمه می‌کند؛ حتی Tool Calling و Vision برای Claude.
• API بومی (Native): مسیرهای اصلی هر پروایدر، بدون هیچ تغییری، زیر https://api.hooshi.ai/{provider}. مناسب وقتی که از قابلیت‌های اختصاصی یک پروایدر یا ابزارهایی مثل Claude Code استفاده می‌کنی.

شروع سریع در ۳ قدم#

1. ثبت‌نام و ساخت کلید: وارد کنسول توسعه‌دهندگان شو و یک کلید بساز. کلید با hk- شروع می‌شود و فقط یک‌بار نمایش داده می‌شود؛ جایی امن ذخیره‌اش کن.
2. شارژ کیف پول API: از همان کنسول کیف پول API را به تومان شارژ کن. این کیف پول از اشتراک ماهانهٔ چت جداست و فقط به اندازهٔ مصرف واقعی از آن کسر می‌شود.
3. اولین درخواست: کلید را در متغیر محیطی HOOSHI_API_KEY بگذار و یکی از نمونه‌های زیر را اجرا کن.

export HOOSHI_API_KEY="hk-..."

با API یکپارچه (پیشنهادی)#

# pip install openai
from openai import OpenAI

client = OpenAI(
    base_url="https://api.hooshi.ai/v1",
    api_key="hk-...",  # کلید هوشی از /console
)

resp = client.chat.completions.create(
    model="anthropic/claude-sonnet-5-5",  # یا openai/gpt-5.5 ، xai/grok-4.7 ، ...
    messages=[
        {"role": "system", "content": "تو یک دستیار برنامه‌نویسی دقیق هستی."},
        {"role": "user", "content": "یک تابع پایتون برای تبدیل اعداد به حروف فارسی بنویس."},
    ],
)

print(resp.choices[0].message.content)
print("هزینه:", resp.model_extra["hooshi"]["cost"], "تومان")

پاسخ دقیقاً شکل پاسخ OpenAI را دارد، به‌علاوهٔ یک شیء hooshi که هزینهٔ همین درخواست را به تومان نشان می‌دهد:

{
  "id": "chatcmpl-8Q2c7xN0aJ3...",
  "object": "chat.completion",
  "created": 1791590400,
  "model": "anthropic/claude-sonnet-5-5",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "حتماً! این تابع ..." },
    "finish_reason": "stop",
    "logprobs": null
  }],
  "usage": {
    "prompt_tokens": 412,
    "completion_tokens": 638,
    "total_tokens": 1050,
    "prompt_tokens_details": { "cached_tokens": 0 }
  },
  "hooshi": { "model": "anthropic/claude-sonnet-5-5", "cost": 1118.37, "currency": "IRT" }
}

با API بومی (مثال: SDK رسمی Anthropic)#

# pip install anthropic
import anthropic

client = anthropic.Anthropic(
    base_url="https://api.hooshi.ai/anthropic",
    api_key="hk-...",  # همان کلید هوشی؛ در هدر x-api-key ارسال می‌شود
)

message = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "مفهوم Big-O را با یک مثال ساده توضیح بده."}],
)
print(message.content[0].text)

آدرس‌های پایه (Base URL)#

همهٔ درخواست‌ها روی HTTPS و دامنهٔ api.hooshi.ai هستند. در API بومی، بعد از نام پروایدر دقیقاً همان مسیر اصلی پروایدر را می‌گذاری.

فهرست کامل پروایدرهای بومی (Mistral، Groq، Together، Perplexity، Qwen، Moonshot، OpenRouter، BFL، Stability و…) در صفحهٔ API بومی آمده است.

احراز هویت#

هر درخواست باید کلید هوشی را همراه داشته باشد. ساده‌ترین روش هدر استاندارد Authorization: Bearer hk-... است، اما برای اینکه SDKهای رسمی بدون تغییر کار کنند، کلید در هدرهای مخصوص هر پروایدر هم پذیرفته می‌شود:

endpointهای API یکپارچه#

مشخصات OpenAPI#

مشخصات کامل API یکپارچه در قالب OpenAPI 3.1 در hooshi.ai/openapi.json منتشر شده است. می‌توانی آن را در Postman یا Insomnia ایمپورت کنی یا با ابزارهایی مثل openapi-generator کلاینت بسازی.

curl -O https://hooshi.ai/openapi.json

قدم بعدی#

• مرجع کامل Chat Completions: پارامترها، استریم SSE، Tool Calling، Vision و خروجی JSON.
• نمونه‌های آماده: رابط چت استریمی، ایجنت با ابزار، RAG، LangChain، Vercel AI SDK و Claude Code.
• خطاها و محدودیت نرخ را قبل از رفتن به محیط production بخوان.