راهنمای کامل API یکپارچه‌ی سازگار با OpenAI و APIهای بومی هوشی، با نمونه‌کد پایتون، جاوااسکریپت، curl و PHP
تحریریهٔ هوشی ۱۵ دقیقه مطالعهبه‌روزرسانی: ۱۸ مهر ۱۴۰۵
API هوش مصنوعی هوشی با یک کلید و کیف پول تومانی، GPT-5.5، Claude و Grok را به کد شما می‌آورد. دو سبک یکپارچه و بومی، قیمت‌ها و نمونه‌کد.
هوش مصنوعی یعنی سیستم‌هایی که از داده یاد می‌گیرند و کارهای فکری انجام می‌دهند. در این راهنما تعریف، تاریخچه، طرز کار، کاربردها، خطرها و راه شروع رایگان را می‌خوانی.
بهترین هوش مصنوعی برای تو به کارت بستگی دارد. در این مقایسه هشت مدل برتر ۲۰۲۶ را از نظر قیمت، پنجرهٔ زمینه، کیفیت فارسی و کاربرد کنار هم گذاشته‌ایم.
API هوش مصنوعی راهی است که برنامه‌نویس‌ها با چند خط کد، مدل‌هایی مثل GPT-5.5، Claude Opus 5.5 یا Grok 4.7 را داخل سایت، اپلیکیشن یا ربات خودشان به کار بگیرند. مشکل همیشگی توسعه‌دهنده‌های ایرانی این بوده که OpenAI API در ایران و API کلاد با کارت ارزی و آی‌پی ایران کار نمی‌کنند. در این راهنما می‌بینید API هوشی چطور این مشکل را حل میکند: یک API یکپارچه‌ی سازگار با OpenAI برای همهی مدلها، به‌علاوه‌ی APIهای بومی هر سرویس که با SDK رسمی و فقط با عوضکردن آدرس کار می‌کنند؛ با کیف پول تومانی و نمونه‌کد پایتون، جاوااسکریپت، curl و PHP.
API هوش مصنوعی یک نقطه‌ی اتصال اینترنتی است که شما متن (یا تصویر و صدا) را برایش می‌فرستید و پاسخ مدل را بهصورت JSON می‌گیرید. هزینه هم بر اساس مقدار مصرف، معمولاً تعداد توکن، حساب میشود.
تفاوتش با نسخه‌ی چت این است که خودتان کنترل کامل دارید: پیام سیستمی، دما، طول پاسخ، فراخوانی ابزار (Function Calling) و ترکیب با پایگاه داده‌ی خودتان. چند کاربرد رایج:
هوشی دو راه برای اتصال دارد: API یکپارچه که با یک فرمت (فرمت OpenAI) به همهی مدلها وصل میشود، و API بومی که دقیقاً همان API اصلی هر سرویس را بازتاب میدهد. هر دو با یک کلید (که با hk- شروع میشود) و یک کیف پول کار می‌کنند.
| ویژگی | API یکپارچه (OpenAI-compatible) | API بومی (Provider-native) |
|---|---|---|
| آدرس پایه | https://api.hooshi.ai/v1 | https://api.hooshi.ai/<provider> |
| شناسه‌ی مدل | openai/gpt-5.5، anthropic/claude-opus-5-5، xai/grok-4.7 | همان شناسه‌ی اصلی: claude-opus-5-5 |
| SDK | SDK رسمی OpenAI یا هر کتابخانه‌ی سازگار | SDK رسمی هر سرویس (Anthropic، Google GenAI، ElevenLabs…) |
| بهترین کاربرد | جابه‌جایی آسان بین مدلها، مقایسه و مسیریابی | استفاده از قابلیتهای اختصاصی هر سرویس، مهاجرت کد موجود |
| Endpointها | chat/completions، embeddings، images، audio/speech، audio/transcriptions | مسیرهای اصلی هر سرویس (فقط بخش‌های قابل‌محاسبه) |
آدرس‌های API بومی: OpenAI روی https://api.hooshi.ai/openai/v1، Anthropic روی https://api.hooshi.ai/anthropic، Gemini روی https://api.hooshi.ai/gemini و ElevenLabs روی https://api.hooshi.ai/elevenlabs. سرویس‌های دیگر مثل xAI، DeepSeek، Mistral و Qwen هم الگوی مشابه دارند؛ فهرست کامل در مستندات API آمده است. فهرست مدلها هم از GET https://api.hooshi.ai/v1/models بدون کلید قابل دریافت است.
اگر قبلاً با SDK رسمی OpenAI کار کرده‌اید، فقط base_url و کلید را عوض کنید و نام مدل را به شکل provider/model بنویسید. همین کد با عوضکردن یک رشته، از GPT به Claude یا Grok می‌رود.
pip install openai یا npm install openai.from openai import OpenAI
client = OpenAI(
base_url="https://api.hooshi.ai/v1",
api_key="hk-...", # کلید API هوشی
)
resp = client.chat.completions.create(
model="anthropic/claude-opus-5-5", # یا openai/gpt-5.5 یا xai/grok-4.7
messages=[
{"role": "system", "content": "You are a helpful assistant. Answer in Persian."},
{"role": "user", "content": "سه ایده برای نام یک کافه‌ی کتاب پیشنهاد بده."},
],
)
print(resp.choices[0].message.content)
print(resp.usage) # توکن‌های ورودی و خروجیimport OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://api.hooshi.ai/v1",
apiKey: process.env.HOOSHI_API_KEY, // hk-...
});
const resp = await client.chat.completions.create({
model: "openai/gpt-5.5",
messages: [{ role: "user", content: "یک تابع جاوااسکریپت برای اعتبارسنجی کد ملی بنویس." }],
});
console.log(resp.choices[0].message.content);curl https://api.hooshi.ai/v1/chat/completions \
-H "Authorization: Bearer $HOOSHI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "xai/grok-4.7",
"messages": [{"role": "user", "content": "سلام! خودت را در یک جمله معرفی کن."}]
}'<?php
$ch = curl_init("https://api.hooshi.ai/v1/chat/completions");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer " . getenv("HOOSHI_API_KEY"),
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => json_encode([
"model" => "anthropic/claude-sonnet-5-5",
"messages" => [["role" => "user", "content" => "متن زیر را خلاصه کن: ..."]],
], JSON_UNESCAPED_UNICODE),
]);
$data = json_decode(curl_exec($ch), true);
echo $data["choices"][0]["message"]["content"];اگر کدتان با SDK رسمی API کلاد یا Gemini نوشته شده، لازم نیست چیزی را بازنویسی کنید. API بومی هوشی مسیرها، پارامترها، پاسخ‌ها و استریم هر سرویس را یک‌به‌یک بازتاب میدهد؛ فقط آدرس پایه و کلید عوض میشود.
import anthropic
client = anthropic.Anthropic(
base_url="https://api.hooshi.ai/anthropic",
api_key="hk-...",
)
msg = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[{"role": "user", "content": "این کد پایتون را بازبینی کن: ..."}],
)
print(msg.content[0].text)from openai import OpenAI
# همان SDK رسمی OpenAI، فقط آدرس و کلید عوض شده
client = OpenAI(base_url="https://api.hooshi.ai/openai/v1", api_key="hk-...")
resp = client.chat.completions.create(
model="gpt-5.5",
messages=[{"role": "user", "content": "Explain recursion in Persian."}],
)
print(resp.choices[0].message.content)from google import genai
client = genai.Client(
api_key="hk-...",
http_options={"base_url": "https://api.hooshi.ai/gemini"},
)
r = client.models.generate_content(model="gemini-3.8-flash", contents="شعر کوتاهی درباره‌ی پاییز بگو.")
print(r.text)import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic({
baseURL: "https://api.hooshi.ai/anthropic",
apiKey: process.env.HOOSHI_API_KEY,
});
const msg = await client.messages.create({
model: "claude-sonnet-5-5",
max_tokens: 1024,
messages: [{ role: "user", content: "یک ایمیل رسمی برای پیگیری سفارش بنویس." }],
});
console.log(msg.content[0].text);curl https://api.hooshi.ai/elevenlabs/v1/text-to-speech/VOICE_ID \
-H "xi-api-key: $HOOSHI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text": "سلام، به هوشی خوش آمدید.", "model_id": "eleven_v4"}' \
--output hello.mp3<?php
$ch = curl_init("https://api.hooshi.ai/anthropic/v1/messages");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"x-api-key: " . getenv("HOOSHI_API_KEY"),
"anthropic-version: 2023-06-01",
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => json_encode([
"model" => "claude-haiku-5-5",
"max_tokens" => 512,
"messages" => [["role" => "user", "content" => "این نظر مشتری مثبت است یا منفی؟ ..."]],
], JSON_UNESCAPED_UNICODE),
]);
echo curl_exec($ch);هدر کلید: هوشی کلید hk- را در هر هدری که SDK اصلی می‌فرستد می‌پذیرد: Authorization: Bearer، x-api-key (Anthropic)، x-goog-api-key (Gemini) یا xi-api-key (ElevenLabs).
استریم یعنی پاسخ مدل کلمه‌به‌کلمه برسد، نه یک‌جا بعد از چند ثانیه. برای چت‌بات‌ها تجربه‌ی کاربر را بسیار بهتر میکند. در API یکپارچه کافی است stream=True بگذارید؛ پاسخ با فرمت استاندارد Server-Sent Events می‌آید.
stream = client.chat.completions.create(
model="openai/gpt-5.5",
messages=[{"role": "user", "content": "یک داستان کوتاه بنویس."}],
stream=True,
stream_options={"include_usage": True}, # مصرف توکن در آخرین تکه
)
for chunk in stream:
if chunk.choices and chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="", flush=True)const stream = await client.chat.completions.create({
model: "anthropic/claude-sonnet-5-5",
messages: [{ role: "user", content: "مراحل راه‌اندازی یک فروشگاه اینترنتی را بگو." }],
stream: true,
});
for await (const chunk of stream) {
process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}با stream_options.include_usage مصرف توکن در آخرین تکه‌ی استریم هم برمیگردد تا هزینهی هر درخواست را ثبت کنید. در API بومی، استریم دقیقاً مثل سرویس اصلی کار میکند (مثلاً رویدادهای message_delta در Anthropic).
در API هوشی هزینه بر اساس توکن مصرفی واقعی هر درخواست از کیف پول API کم میشود؛ اشتراک ماهانه یا حداقل مصرف ندارد. هر توکن تقریباً معادل سه‌چهارم یک کلمه‌ی انگلیسی است و متن فارسی معمولاً توکن بیشتری مصرف میکند.
| مدل | شناسه در API یکپارچه | ورودی | خروجی | ورودی کش‌شده |
|---|---|---|---|---|
| GPT-6 Astra | openai/gpt-6-astra | ۱۰ | ۵۰ | ۱ |
| GPT-5.5 | openai/gpt-5.5 | ۵ | ۳۰ | ۰٫۵ |
| GPT-6 Luna | openai/gpt-6-luna | ۰٫۱ | ۰٫۵ | ۰٫۰۱ |
| Claude Opus 5.5 | anthropic/claude-opus-5-5 | ۴ | ۲۰ | ۰٫۲ |
| Claude Sonnet 5.5 | anthropic/claude-sonnet-5-5 | ۲ | ۱۰ | ۰٫۱ |
| Claude Haiku 5.5 | anthropic/claude-haiku-5-5 | ۰٫۱ | ۰٫۵ | ۰٫۰۱ |
| Gemini 3.8 Flash | gemini/gemini-3.8-flash | ۰٫۷۵ | ۳٫۷۵ | ۰٫۰۷۵ |
| Grok 4.7 | xai/grok-4.7 | ۲ | ۶ | ۰٫۵ |
| DeepSeek Flash | deepseek/deepseek-flash | ۰٫۳ | ۱٫۲ | ۰٫۰۰۶ |
توجه: اعداد جدول قیمت فهرست رسمی سازندهها به دلار و فقط برای مقایسه‌ی نسبی مدل‌هاست. قیمت تومانی که از کیف پول شما کم میشود را در صفحهی مدلها ببینید. برخی مدلها برای پرامپت‌های خیلی بلند نرخ بالاتری دارند.
مقایسه‌ی هزینهی خروجی چند مدل محبوب (دلار به‌ازای یک میلیون توکن خروجی، نسبت به GPT-6 Astra):
موجودی کیف پول و گزارش مصرف را هم از خود API می‌گیرید:
curl https://api.hooshi.ai/v1/balance -H "Authorization: Bearer $HOOSHI_API_KEY"
# {"object":"balance","currency":"IRT","balance":...}مثال محاسبه: یک درخواست با ۲٬۰۰۰ توکن ورودی و ۵۰۰ توکن خروجی روی Claude Sonnet 5.5 حدود ۰٫۰۰۴ + ۰٫۰۰۵ = ۰٫۰۰۹ دلار هزینه دارد؛ یعنی هزار درخواست مشابه حدود ۹ دلار. همین کار روی Claude Haiku 5.5 حدود بیست برابر ارزان‌تر است.
برای اینکه همهی این‌ها کنار هم معنا پیدا کند، فرض کنید می‌خواهید برای یک فروشگاه اینترنتی چت‌باتی بسازید که به سؤالات مشتری درباره‌ی ارسال، مرجوعی و موجودی جواب دهد. معماری ساده و ارزان آن این‌طور است:
/v1/embeddings (مثلاً openai/text-embedding-3-small) بردار هر تکه را بسازید و در پایگاه داده ذخیره کنید.anthropic/claude-haiku-5-5 بدهید و بخواهید فقط از روی همان متن، کوتاه و مؤدبانه جواب دهد.anthropic/claude-sonnet-5-5 یا openai/gpt-5.5 بفرستید. در API یکپارچه این یعنی فقط عوضکردن یک رشته.چون پیام سیستمی و قوانین ثابت‌اند، از کش پرامپت هم سود می‌برید. در عمل بیشتر هزینهی چنین چت‌باتی صرف توکن‌های ورودی میشود، نه خروجی؛ پس کوتاه نگه‌داشتن تکه‌های بازیابی‌شده مستقیم روی صورت‌حساب اثر دارد. همین الگو را می‌توانید برای ربات تلگرام، دستیار داخلی شرکت یا جست‌وجوی هوشمند مستندات هم به کار ببرید. اگر به صدا هم نیاز دارید، پاسخ متنی را با /v1/audio/speech یا API بومی ElevenLabs به گفتار تبدیل کنید؛ جزئیات در راهنمای تبدیل متن به صدا آمده است.
سه چیز یک یکپارچه‌سازی حرفه‌ای را از یک نمونه‌ی آزمایشی جدا میکند: مدیریت خطا، کنترل هزینه و امنیت کلید.
خطاهای 429 (محدودیت نرخ) و 5xx (مشکل موقت سرویس‌دهنده) را با تأخیر تصاعدی (Exponential Backoff) و کمی تصادفی‌سازی دوباره امتحان کنید؛ خطاهای 4xx دیگر مثل کلید نامعتبر یا مدل اشتباه را تکرار نکنید. SDKهای رسمی خودشان چند بار تلاش مجدد دارند (max_retries).
import time, random
from openai import OpenAI, RateLimitError, APIStatusError
client = OpenAI(base_url="https://api.hooshi.ai/v1", api_key="hk-...", max_retries=0, timeout=60)
def ask(messages, model="openai/gpt-6-luna", tries=5):
for i in range(tries):
try:
return client.chat.completions.create(model=model, messages=messages, max_tokens=800)
except RateLimitError:
pass
except APIStatusError as e:
if e.status_code < 500:
raise # خطای درخواست؛ تکرار فایده ندارد
time.sleep(min(30, 2 ** i) + random.random()) # Exponential backoff + jitter
raise RuntimeError("سرویس فعلاً در دسترس نیست")max_tokens بگذارید.usage هر پاسخ را ذخیره کنید و برای کاربران خودتان سقف بگذارید.بیشتر سازندهها برای بخش تکراری ابتدای پرامپت (مثل پیام سیستمی طولانی یا مستندات) قیمت «ورودی کش‌شده» دارند که طبق جدول بالا تا حدود یک‌دهم قیمت عادی است. برای استفاده از آن، بخش ثابت پرامپت را همیشه اول و دقیقاً یکسان بفرستید و بخش متغیر را آخر بگذارید. در OpenAI کش خودکار است و در Anthropic با cache_control در API بومی فعال میشود. پاسخ‌های کاملاً تکراری (مثل سؤالات متداول) را هم در سمت خودتان، مثلاً در Redis، کش کنید.
پاسخ‌های خطای API یکپارچه همان ساختار استاندارد OpenAI را دارند (error.message، error.type و error.code)، پس کتابخانه‌های موجود بدون تغییر آنها را می‌فهمند. رایج‌ترین خطاها:
| کد | معنی | راه‌حل |
|---|---|---|
| 401 | کلید ارسال نشده یا نامعتبر است | بررسی کنید کلید با hk- شروع شود و در هدر درست قرار گرفته باشد |
| 402 | موجودی کیف پول API کافی نیست (insufficient_quota) یا سقف هزینهی ماهانهی کلید پر شده (spend_limit_reached) | کیف پول را شارژ کنید یا سقف کلید را بالا ببرید؛ با /v1/balance هشدار خودکار بسازید |
| 404 | مدل یا مسیر پیدا نشد | شناسه‌ی مدل را از /v1/models بردارید؛ در API یکپارچه پیشوند سازنده را فراموش نکنید |
| 429 | محدودیت نرخ درخواست | تکرار با تأخیر تصاعدی، کاهش هم‌زمانی یا صف‌بندی درخواست‌ها |
| 5xx | مشکل موقت سرویس‌دهنده‌ی بالادستی | چند بار تکرار کنید؛ در صورت تداوم، موقتاً به مدل جایگزین بروید |
یک ترفند ساده‌ی پایداری این است که برای هر کار یک «مدل پشتیبان» تعریف کنید. مثلاً اگر anthropic/claude-sonnet-5-5 چند بار پشت سر هم خطای ۵۰۰ داد، درخواست را با همان پیام‌ها به openai/gpt-5.5 بفرستید. چون در API یکپارچه فرمت درخواست و پاسخ برای همه یکی است، این کار فقط یک خط کد است و کاربر شما متوجه قطعی نمی‌شود.
API یکپارچه فقط برای چت نیست. با /v1/embeddings برای جست‌وجوی معنایی و RAG بردار متن می‌سازید، با /v1/images/generations از مدل‌هایی مثل GPT Image 2 یا FLUX تصویر می‌گیرید، با /v1/audio/speech متن را به گفتار تبدیل می‌کنید و با /v1/audio/transcriptions فایل صوتی را به متن برمی‌گردانید. همه با همان کلید و همان کیف پول. گزارش مصرف تفکیکی هم از /v1/usage در دسترس است تا بدانید هر سرویس یا هر مشتری شما چقدر هزینه ساخته است. برای ساخت تصویر و نوشتن پرامپت تصویری خوب، راهنمای ساخت عکس با هوش مصنوعی را ببینید.
هشدار: کلید hk- را هرگز در کد سمت مرورگر یا اپلیکیشن موبایل قرار ندهید و در گیت‌هاب منتشر نکنید. درخواست‌ها را از سرور خودتان بفرستید، کلید را در متغیر محیطی نگه دارید و برای هر پروژه کلید جدا بسازید تا در صورت نشت، فقط همان را باطل کنید.
به‌طور خلاصه: یک حساب، یک کلید و یک کیف پول تومانی برای دسترسی به مدلهای OpenAI، Anthropic، Google، xAI، DeepSeek، ElevenLabs و سازنده‌های دیگر؛ بدون کارت ارزی و بدون نیاز به سرور خارج.
کلید API خودتان را بسازید. کیف پول را با هر مبلغی شارژ کنید و اولین درخواست را در کمتر از پنج دقیقه بفرستید.
شروع با API هوشیاگر بین مدلها مردد هستید، مقایسه‌ی بهترین مدلهای هوش مصنوعی ۲۰۲۶ و برای نوشتن پیام سیستمی بهتر، راهنمای مهندسی پرامپت را بخوانید. اگر فقط می‌خواهید با مدلها چت کنید، پنل چت هوشی بدون کدنویسی همین دسترسی را میدهد.
دسترسی مستقیم به OpenAI API از ایران به دلیل تحریم و نیاز به کارت ارزی عملاً ممکن نیست. با API هوشی می‌توانید همان SDK رسمی OpenAI را با آدرس https://api.hooshi.ai/openai/v1 یا API یکپارچه‌ی https://api.hooshi.ai/v1 و کلید hk- استفاده کنید و هزینه را از کیف پول تومانی بپردازید.
API یکپارچه با فرمت OpenAI کار میکند و با عوضکردن نام مدل (مثل anthropic/claude-opus-5-5) بین همهی سازندهها جابهجا میشود؛ برای مقایسه و مسیریابی مدلها عالی است. API بومی دقیقاً API اصلی هر سرویس را بازتاب میدهد تا با SDK رسمی Anthropic، Gemini یا ElevenLabs و قابلیتهای اختصاصی آنها کار کنید.
مدلهای زبانی بر اساس تعداد توکن ورودی و خروجی هر درخواست قیمتگذاری میشوند؛ مدلهای تصویری و صوتی بر اساس تصویر، کاراکتر یا دقیقه. در هوشی هزینهی واقعی هر درخواست از کیف پول API تومانی کم میشود و فیلد usage در پاسخ مصرف را نشان میدهد. قیمت تومانی هر مدل در صفحهی مدلها آمده است.
خیر. اشتراک ماهانهی هوشی برای استفاده در پنل چت، استودیوی تصویر و صدا است و API کیف پول جداگانهای دارد که به تومان شارژ میشود. این جداسازی باعث میشود هزینهی برنامهها و سرویسهایتان شفاف و قابل کنترل باشد و مصرف API روی سهمیهی چت شما اثر نگذارد.
بله. در API یکپارچه با stream=True پاسخ بهصورت Server-Sent Events و تکهتکه میرسد و با stream_options.include_usage مصرف توکن هم در آخرین تکه برمیگردد. در API بومی، استریم دقیقاً مثل سرویس اصلی کار میکند؛ مثلاً رویدادهای استریم Anthropic یا Gemini بدون تغییر به کد شما میرسند.
برای بیشتر کارهای عمومی Claude Sonnet 5.5 یا GPT-5.5 تعادل خوبی بین کیفیت و هزینه دارند. برای کارهای ساده و پرحجم مثل طبقه‌بندی، Claude Haiku 5.5، GPT-6 Luna یا DeepSeek Flash بسیار ارزان‌ترند. برای سخت‌ترین استدلال‌ها و کدنویسی پیچیده، Claude Opus 5.5 یا GPT-6 Astra را امتحان کنید.
کلیدهای هوشی با hk- شروع میشوند و فقط یکبار هنگام ساخت نمایش داده میشوند. آنها را در متغیر محیطی یا سرویس مدیریت اسرار روی سرور نگه دارید، هرگز در کد سمت مرورگر یا اپ موبایل قرار ندهید و برای هر پروژه کلید جدا بسازید تا در صورت نشت، فقط همان کلید را باطل کنید.
