API بومی: همان SDKهای رسمی، از طریق هوشی

یکپارچه یا بومی؟#

پروایدرها و Base URLها#

فقط endpointهای قابل‌محاسبه (billable) و چند endpoint رایگان مثل فهرست مدل‌ها باز هستند. درخواست به مسیر دیگری خطای endpoint_not_supported برمی‌گرداند. برای پروایدرهای سازگار با OpenAI، هر مسیر استاندارد (chat/completions، responses، embeddings، images، audio) برای مدل‌هایی که در کاتالوگ هوشی هستند کار می‌کند.

درخواست‌های GET به فهرست مدل‌ها (مثل /openai/v1/models، /anthropic/v1/models، /gemini/v1beta/models)، فهرست صداها و مدل‌های ElevenLabs و count_tokens/countTokens رایگان هستند.

OpenAI#

علاوه بر Chat Completions، Responses API هم پشتیبانی می‌شود. هدر OpenAI-Beta هم عبور داده می‌شود.

from openai import OpenAI

client = OpenAI(base_url="https://api.hooshi.ai/openai/v1", api_key="hk-...")

# Responses API
resp = client.responses.create(model="gpt-5.5", input="یک هایکو دربارهٔ پاییز تهران بنویس.")
print(resp.output_text)

# Chat Completions
chat = client.chat.completions.create(model="gpt-6-luna", messages=[{"role": "user", "content": "سلام"}])

در استریم Chat Completions بومی، هوشی stream_options.include_usage را همیشه روشن می‌کند تا مصرف دقیق محاسبه شود؛ پس یک chunk پایانی با choices: [] و usage دریافت می‌کنی که SDKهای رسمی به‌درستی مدیریتش می‌کنند.

Anthropic (Claude)#

Base URL را https://api.hooshi.ai/anthropic بگذار (بدون /v1؛ SDK خودش اضافه می‌کند). کلید در x-api-key فرستاده می‌شود. هدرهای anthropic-version و anthropic-beta عیناً به Anthropic می‌رسند.

import anthropic

client = anthropic.Anthropic(base_url="https://api.hooshi.ai/anthropic", api_key="hk-...")

with client.messages.stream(
    model="claude-sonnet-5-5",
    max_tokens=2048,
    system="تو یک ویراستار دقیق فارسی هستی.",
    messages=[{"role": "user", "content": "این متن را ویرایش کن: ..."}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

برای Claude Code و ابزارهای مشابه، بخش Claude Code و Cursor را ببین.

Google Gemini#

با Google GenAI SDK فقط base_url را در http_options عوض کن. کلید در هدر x-goog-api-key فرستاده می‌شود. هم v1beta و هم v1 پشتیبانی می‌شوند.

# pip install google-genai
from google import genai
from google.genai import types

client = genai.Client(
    api_key="hk-...",
    http_options=types.HttpOptions(base_url="https://api.hooshi.ai/gemini"),
)

resp = client.models.generate_content(model="gemini-3.1-pro-preview", contents="خلاصهٔ کتاب بوف کور در سه جمله")
print(resp.text)

for chunk in client.models.generate_content_stream(model="gemini-3.8-flash", contents="یک شعر کوتاه"):
    print(chunk.text, end="")

endpoint سازگار با OpenAI گوگل هم در دسترس است: https://api.hooshi.ai/gemini/v1beta/openai (برای chat/completions و embeddings).

xAI (Grok)#

xAI سازگار با OpenAI است؛ SDK رسمی OpenAI یا xAI SDK با Base URL هوشی کار می‌کند.

from openai import OpenAI

grok = OpenAI(base_url="https://api.hooshi.ai/xai/v1", api_key="hk-...")
r = grok.chat.completions.create(model="grok-4.7", messages=[{"role": "user", "content": "آخرین روندهای هوش مصنوعی؟"}])
print(r.choices[0].message.content)

DeepSeek#

from openai import OpenAI

ds = OpenAI(base_url="https://api.hooshi.ai/deepseek", api_key="hk-...")
r = ds.chat.completions.create(model="deepseek-v4-pro", messages=[{"role": "user", "content": "اثبات کن √2 گنگ است."}])
print(getattr(r.choices[0].message, "reasoning_content", None))  # زنجیرهٔ استدلال
print(r.choices[0].message.content)

سایر پروایدرهای سازگار با OpenAI#

Mistral، Groq، Together، Perplexity، Qwen، Moonshot (Kimi)، OpenRouter، MiniMax و Zhipu همگی با SDK رسمی OpenAI کار می‌کنند؛ فقط Base URL را از جدول بالا بردار و شناسهٔ بالادستی مدل را بفرست.

from openai import OpenAI

BASES = {
    "mistral":    "https://api.hooshi.ai/mistral/v1",
    "groq":       "https://api.hooshi.ai/groq/openai/v1",
    "together":   "https://api.hooshi.ai/together/v1",
    "perplexity": "https://api.hooshi.ai/perplexity",
    "qwen":       "https://api.hooshi.ai/qwen/compatible-mode/v1",
    "moonshot":   "https://api.hooshi.ai/moonshot/v1",
}

kimi = OpenAI(base_url=BASES["moonshot"], api_key="hk-...")
r = kimi.chat.completions.create(model="kimi-k3", messages=[{"role": "user", "content": "سلام کیمی"}])

sonar = OpenAI(base_url=BASES["perplexity"], api_key="hk-...")
r = sonar.chat.completions.create(model="sonar-pro", messages=[{"role": "user", "content": "قیمت امروز طلا؟"}])
print(r.model_extra.get("citations"))

ElevenLabs (صدا)#

SDK رسمی ElevenLabs با base_url="https://api.hooshi.ai/elevenlabs" کار می‌کند؛ کلید در هدر xi-api-key. فهرست صداها و مدل‌ها (GET /v1/voices، /v1/models، /v1/shared-voices) رایگان است.

# pip install elevenlabs
from elevenlabs.client import ElevenLabs

el = ElevenLabs(api_key="hk-...", base_url="https://api.hooshi.ai/elevenlabs")

audio = el.text_to_speech.convert(
    voice_id="YOUR_VOICE_ID",
    model_id="eleven_v4",
    text="سلام! این صدا با ElevenLabs از طریق هوشی ساخته شده.",
    output_format="mp3_44100_128",
)
with open("out.mp3", "wb") as f:
    for chunk in audio:
        f.write(chunk)

Black Forest Labs (FLUX) و Stability#

FLUX (BFL)#

درخواست به POST /bfl/v1/{model} (مثلاً flux-2-pro) یک کار ناهمگام می‌سازد و id برمی‌گرداند. نتیجه را با GET /bfl/v1/get_result?id=… از طریق هوشی بگیر (رایگان). هزینه به ازای هر درخواست موفق است.

# ۱) ساخت کار
curl https://api.hooshi.ai/bfl/v1/flux-2-pro \
  -H "x-key: $HOOSHI_API_KEY" -H "Content-Type: application/json" \
  -d '{"prompt": "a teal paper boat on a calm lake", "width": 1024, "height": 768}'
# → {"id": "a1b2c3...", "polling_url": "..."}

# ۲) گرفتن نتیجه (تا وقتی status = Ready شود)
curl "https://api.hooshi.ai/bfl/v1/get_result?id=a1b2c3..." -H "x-key: $HOOSHI_API_KEY"

Stability AI#

curl https://api.hooshi.ai/stability/v2beta/stable-image/generate/core \
  -H "Authorization: Bearer $HOOSHI_API_KEY" \
  -H "Accept: image/*" \
  -F prompt="a cozy Persian tea house, watercolor" \
  -F aspect_ratio=16:9 \
  -F output_format=png \
  --output tea-house.png

مسیرهای ultra، core و sd3 (با فیلد model، پیش‌فرض sd3.5-large) پشتیبانی می‌شوند و هزینه به ازای هر تصویر است.

رفتار مشترک API بومی#

تزریق هویت#

برای مدل‌های گفتگو، همان سیستم‌پرامپت هویت API یکپارچه به فرمت هر پروایدر اضافه می‌شود: در Anthropic به ابتدای system، در Gemini به systemInstruction، در Responses API به instructions و در Chat Completions به messages. با هدر X-Hooshi-Identity: off یا از تنظیمات کلید خاموشش کن.

خطاها#

خطاهای مربوط به هوشی (کلید، موجودی، محدودیت نرخ، مدل/مسیر پشتیبانی‌نشده) با قالب خطای هوشی برمی‌گردند. خطاهای اعتبارسنجی خود پروایدر (مثلاً پارامتر نادرست) عیناً با همان قالب و کد وضعیت پروایدر برگردانده می‌شوند تا SDK رسمی آن‌ها را درست تفسیر کند.

صورتحساب و ردیابی#

مصرف از روی usage واقعی پاسخ (یا طول صدا/تعداد کاراکتر/تعداد تصویر) محاسبه و از کیف پول API کسر می‌شود. هر پاسخ هدر X-Request-Id دارد. هزینه‌ها در /v1/usage و کنسول قابل مشاهده‌اند.