# Hooshvana (هوشوانا)

> Hooshvana is a Persian AI API gateway for Iranian developers and businesses: one OpenAI-compatible and Anthropic-compatible API for 80+ models (OpenAI, Anthropic, Google, DeepSeek, Meta, Mistral, xAI, Qwen, ElevenLabs voices). Rial payment (Parsian, Zarinpal, card-to-card), no KYC, Iranian servers, automatic failover, pay-as-you-go with no monthly plan.

هوشوانا درگاه API هوش مصنوعی برای توسعه‌دهنده‌های ایرانی است: یک کلید سازگار با OpenAI و Anthropic برای بیش از ۸۰ مدل GPT، Claude، Gemini، DeepSeek و دیگران، با پرداخت ریالی، بدون تحریم و احراز هویت.

Full documentation as one Markdown file: https://hooshvana.ir/llms-full.txt

## Key facts

- Website: https://hooshvana.ir (Persian, fa-IR). Signup: https://hooshvana.ir/auth/register
- OpenAI-compatible base URL: https://hooshvana.ir/api/v1
- Anthropic-compatible base URL (Claude Code, Anthropic SDKs): https://hooshvana.ir/api
- MCP server: https://hooshvana.ir/api/mcp (Streamable HTTP, Bearer key)
- Auth: `Authorization: Bearer hv-...` or `x-api-key: hv-...`
- Endpoints: GET /v1/models, POST /v1/chat/completions, /v1/responses, /v1/messages, /v1/embeddings, /v1/images/generations, /v1/audio/speech, /v1/audio/transcriptions, /v1/kb/{id}/query
- Model ids use the vendor prefix, e.g. openai/gpt-4o-mini, anthropic/claude-sonnet-4.6
- Pricing: customer price = upstream USD price x Hooshvana dollar rate (currently 295,000 toman per USD, updated 2026-10-14) x model markup (1 for most models; any other markup is shown on the model page). Pay per token, no subscription.
- Signup bonus credit: 20,000 toman
- Referral: 10% of referred users' top-ups for 12 months
- Catalog: 86 models from 17 vendors
- Support: support@hooshvana.ir, Telegram @hooshvana_support, https://hooshvana.ir/contact

## Docs

- [شروع سریع](https://hooshvana.ir/docs/quickstart): در چند دقیقه در هوشوانا ثبت‌نام کنید، کلید API بسازید و اولین درخواست خود را با cURL، Python یا Node.js به مدل‌های هوش مصنوعی بفرستید.
- [احراز هویت و کلیدهای API](https://hooshvana.ir/docs/authentication): نحوه‌ی ارسال کلید API هوشوانا با هدر Bearer یا x-api-key، نگهداری امن کلیدها در متغیر محیطی، چرخش و ابطال کلید و الگوی پراکسی سمت سرور.
- [قوانین کلید و گروه مدل](https://hooshvana.ir/docs/key-rules): با قوانین کلید و حساب، مدل‌ها، endpointها، سقف هزینه، محدودیت نرخ، IP و تاریخ انقضا را کنترل کنید و با گروه‌های مدل دسترسی را ساده مدیریت کنید.
- [Chat Completions](https://hooshvana.ir/docs/api/chat-completions): مرجع کامل endpoint چت هوشوانا: پارامترها، استریم SSE، فراخوانی ابزار، ورودی تصویر، خروجی JSON و json_schema، شیء usage و اتصال پایگاه دانش.
- [Responses API](https://hooshvana.ir/docs/api/responses): استفاده از Responses API در هوشوانا: ساختار درخواست با input و instructions، رویدادهای استریم، تفاوت با Chat Completions و تنظیم Codex CLI.
- [Anthropic Messages API](https://hooshvana.ir/docs/api/messages): فراخوانی مدل‌های Claude با API سازگار با Anthropic در هوشوانا: هدرها، cURL، SDK پایتون و TypeScript، استریم رویدادها و فراخوانی ابزار.
- [Embeddings](https://hooshvana.ir/docs/api/embeddings): ساخت بردار embedding برای متن فارسی و انگلیسی در هوشوانا: درخواست، ارسال دسته‌ای، کاهش ابعاد، محاسبه‌ی شباهت کسینوسی و نرمال‌سازی متن فارسی.
- [تولید تصویر](https://hooshvana.ir/docs/api/images): ساخت تصویر از متن با مدل‌هایی مثل GPT Image 2 در هوشوانا: پارامترها، اندازه‌ها، ذخیره‌ی خروجی base64 در فایل و نحوه‌ی محاسبه‌ی هزینه.
- [تبدیل متن به گفتار](https://hooshvana.ir/docs/api/text-to-speech): تبدیل متن فارسی و انگلیسی به صدا با مدل‌های OpenAI و ElevenLabs در هوشوانا: انتخاب صدا، قالب‌های خروجی، ذخیره‌ی استریم در فایل و هزینه‌ی هر نویسه.
- [تبدیل گفتار به متن](https://hooshvana.ir/docs/api/speech-to-text): تبدیل فایل صوتی فارسی به متن با whisper-1 و gpt-transcribe در هوشوانا: آپلود multipart، زبان fa، قالب‌های خروجی و زیرنویس، حد حجم و هزینه‌ی هر دقیقه.
- [فهرست مدل‌ها](https://hooshvana.ir/docs/api/models): دریافت فهرست مدل‌های در دسترس هوشوانا با GET /models، ساختار پاسخ، قالب شناسه‌ی مدل‌ها و راهنمای انتخاب مدل مناسب برای هر کاربرد و بودجه.
- [پایگاه دانش](https://hooshvana.ir/docs/knowledge-base): با پایگاه دانش هوشوانا سایت، فایل‌ها و پایگاه داده‌ی خود را به مدل‌های هوش مصنوعی وصل کنید تا پاسخ‌ها بر اساس اطلاعات خودتان و با ذکر منبع باشد.
- [سرور MCP هوشوانا](https://hooshvana.ir/docs/mcp): سرور MCP هوشوانا را به Claude Code، Cursor و سایر کلاینت‌ها وصل کنید تا دستیار شما در پایگاه دانش جستجو کند، مدل‌ها را ببیند و مصرف حساب را گزارش دهد.
- [لاگ درخواست‌ها](https://hooshvana.ir/docs/logs): هر درخواست به API هوشوانا با مدل، توکن، هزینه و وضعیت ثبت می‌شود. با لاگ‌ها مصرف را پیگیری کنید، خطاها را بیابید و با شناسه‌ی درخواست اشکال‌زدایی کنید.
- [خطاها و کدهای خطا](https://hooshvana.ir/docs/errors): فهرست کامل کدهای خطای API هوشوانا با وضعیت HTTP، معنی و راه‌حل هر کدام، به همراه راهنمای تلاش دوباره و نمونه‌کد مدیریت خطا در Python و Node.js.
- [محدودیت نرخ درخواست](https://hooshvana.ir/docs/rate-limits): محدودیت تعداد درخواست و توکن در دقیقه (RPM و TPM) در هوشوانا، هدرهای محدودیت، مدیریت خطای ۴۲۹ با backoff نمایی و راه‌های کم کردن برخورد با محدودیت.
- [قیمت‌گذاری و صورتحساب](https://hooshvana.ir/docs/pricing-billing): نحوه‌ی محاسبه‌ی هزینه‌ی هر درخواست به تومان در هوشوانا، کیف پول، روش‌های شارژ ریالی و کارت‌به‌کارت، کد تخفیف، فاکتور، اعتبار هدیه و برآورد هزینه‌ی ماهانه.
- [SDKها و زبان‌های برنامه‌نویسی](https://hooshvana.ir/docs/sdks): اتصال به هوشوانا با SDKهای رسمی OpenAI در Python، Node.js، PHP و Go و با cURL، به همراه تنظیم متغیرهای محیطی OPENAI_BASE_URL و OPENAI_API_KEY.

## Integrations

- [Claude Code](https://hooshvana.ir/integrations/claude-code): Claude Code را با کلید هوشوانا و پرداخت ریالی اجرا کنید، بدون حساب خارجی و دردسر تحریم.
- [Cursor](https://hooshvana.ir/integrations/cursor): مدل‌های GPT، Claude، Gemini و DeepSeek را با کلید هوشوانا در چت و Agent ویرایشگر Cursor استفاده کنید.
- [Codex CLI](https://hooshvana.ir/integrations/codex): Codex CLI را با یک ارائه‌دهنده‌ی سفارشی در config.toml به هوشوانا وصل کنید و ریالی پرداخت کنید.
- [Cline](https://hooshvana.ir/integrations/cline): افزونه‌های Cline و Roo Code را با گزینه‌ی OpenAI Compatible به هوشوانا وصل کنید و با هر مدلی کد بزنید.
- [Continue](https://hooshvana.ir/integrations/continue): Continue را در VS Code و JetBrains با چند مدل هوشوانا برای چت، ویرایش و جست‌وجوی کد تنظیم کنید.
- [n8n](https://hooshvana.ir/integrations/n8n): در گردش‌کارهای n8n از مدل‌های هوشوانا، AI Agent و پایگاه دانش خودتان استفاده کنید.
- [LangChain](https://hooshvana.ir/integrations/langchain): در LangChain پایتون و جاوااسکریپت با ChatOpenAI و OpenAIEmbeddings از مدل‌های هوشوانا استفاده کنید.
- [LlamaIndex](https://hooshvana.ir/integrations/llamaindex): در LlamaIndex با OpenAILike و OpenAILikeEmbedding از مدل‌های هوشوانا برای RAG استفاده کنید.
- [WordPress](https://hooshvana.ir/integrations/wordpress): با افزونه‌ی AI Engine یا افزونه‌های سازگار با OpenAI، چت‌بات و تولید محتوا را با هوشوانا در وردپرس راه بیندازید.

## Models

- [Model catalog with toman prices](https://hooshvana.ir/models)
- [API ChatGPT در ایران با پرداخت ریالی و قیمت تومانی](https://hooshvana.ir/chatgpt-api): API مدل‌های ChatGPT و GPT از OpenAI را بدون تحریم و کارت ارزی استفاده کنید: قیمت تومانی هر مدل، نمونه‌کد Python و Node.js و راهنمای انتخاب مدل.
- [API Claude در ایران با پرداخت ریالی و قیمت تومانی](https://hooshvana.ir/claude-api): API مدل‌های Claude از Anthropic را بدون تحریم استفاده کنید: سازگار با SDK رسمی Anthropic و OpenAI، اتصال Claude Code، قیمت تومانی و نمونه‌کد.
- [API Gemini در ایران با پرداخت ریالی و قیمت تومانی](https://hooshvana.ir/gemini-api): API مدل‌های Gemini گوگل را بدون تحریم و با SDK سازگار با OpenAI استفاده کنید: قیمت تومانی Flash و Pro، کانتکست طولانی، ورودی تصویر و نمونه‌کد.
- [API DeepSeek در ایران با پرداخت ریالی و قیمت تومانی](https://hooshvana.ir/deepseek-api): API مدل‌های DeepSeek را با پرداخت ریالی و SDK سازگار با OpenAI استفاده کنید: قیمت تومانی مدل‌های چت و استدلالی، نمونه‌کد و راهنمای انتخاب مدل.
- [محبوب‌ترین مدل‌های هوش مصنوعی](https://hooshvana.ir/models/category/popular)
- [ارزان‌ترین مدل‌های هوش مصنوعی](https://hooshvana.ir/models/category/cheap)
- [بهترین مدل‌های هوش مصنوعی برای کدنویسی](https://hooshvana.ir/models/category/coding)
- [بهترین مدل‌ها برای تولید محتوای فارسی](https://hooshvana.ir/models/category/content)
- [مدل‌های هوش مصنوعی استدلالی](https://hooshvana.ir/models/category/reasoning)
- [مدل‌های هوش مصنوعی با قابلیت بینایی](https://hooshvana.ir/models/category/vision)
- [بهترین مدل‌های هوش مصنوعی برای زبان فارسی](https://hooshvana.ir/models/category/persian)
- [مدل‌های صوتی: متن به گفتار و گفتار به متن](https://hooshvana.ir/models/category/voice)
- [مدل‌های تولید تصویر با هوش مصنوعی](https://hooshvana.ir/models/category/image)
- [مدل‌های Embedding برای جست‌وجوی معنایی](https://hooshvana.ir/models/category/embedding)
- [بهترین مدل‌های هوش مصنوعی برای ترجمه](https://hooshvana.ir/models/category/translation)
- [مدل‌های هوش مصنوعی با کانتکست طولانی](https://hooshvana.ir/models/category/long-context)
- [openai models (23)](https://hooshvana.ir/models/vendor/openai)
- [google models (9)](https://hooshvana.ir/models/vendor/google)
- [qwen models (8)](https://hooshvana.ir/models/vendor/qwen)
- [mistral models (7)](https://hooshvana.ir/models/vendor/mistral)
- [anthropic models (6)](https://hooshvana.ir/models/vendor/anthropic)
- [deepseek models (5)](https://hooshvana.ir/models/vendor/deepseek)
- [meta models (5)](https://hooshvana.ir/models/vendor/meta)
- [perplexity models (4)](https://hooshvana.ir/models/vendor/perplexity)
- [elevenlabs models (4)](https://hooshvana.ir/models/vendor/elevenlabs)
- [x-ai models (3)](https://hooshvana.ir/models/vendor/x-ai)
- [moonshotai models (3)](https://hooshvana.ir/models/vendor/moonshotai)
- [z-ai models (3)](https://hooshvana.ir/models/vendor/z-ai)
- [minimax models (2)](https://hooshvana.ir/models/vendor/minimax)
- [cohere models (1)](https://hooshvana.ir/models/vendor/cohere)
- [xiaomi models (1)](https://hooshvana.ir/models/vendor/xiaomi)
- [nvidia models (1)](https://hooshvana.ir/models/vendor/nvidia)
- [inception models (1)](https://hooshvana.ir/models/vendor/inception)
- [Claude Sonnet 5.5](https://hooshvana.ir/models/anthropic-claude-sonnet-5-5): `anthropic/claude-sonnet-5.5`, input 590,000 toman / output 2,950,000 toman per 1M tokens
- [GPT-6.1 Sol](https://hooshvana.ir/models/openai-gpt-6-1-sol): `openai/gpt-6.1-sol`, input 590,000 toman / output 2,950,000 toman per 1M tokens
- [Claude Opus 5.5](https://hooshvana.ir/models/anthropic-claude-opus-5-5): `anthropic/claude-opus-5.5`, input 1,180,000 toman / output 5,900,000 toman per 1M tokens
- [GPT-6 Luna](https://hooshvana.ir/models/openai-gpt-6-luna): `openai/gpt-6-luna`, input 29,500 toman / output 147,500 toman per 1M tokens
- [DeepSeek V4.1 Flash](https://hooshvana.ir/models/deepseek-deepseek-v4-1-flash): `deepseek/deepseek-v4.1-flash`, input 44,250 toman / output 177,000 toman per 1M tokens
- [Claude Haiku 5.5](https://hooshvana.ir/models/anthropic-claude-haiku-5-5): `anthropic/claude-haiku-5.5`, input 29,500 toman / output 147,500 toman per 1M tokens
- [Gemini 3.8 Flash](https://hooshvana.ir/models/google-gemini-3-8-flash): `google/gemini-3.8-flash`, input 221,250 toman / output 1,106,250 toman per 1M tokens
- [Gemini 4 Argon](https://hooshvana.ir/models/google-gemini-4-argon): `google/gemini-4-argon`, input 590,000 toman / output 2,950,000 toman per 1M tokens
- [Grok 4.7](https://hooshvana.ir/models/x-ai-grok-4-7): `x-ai/grok-4.7`, input 590,000 toman / output 1,770,000 toman per 1M tokens
- [Kimi K3](https://hooshvana.ir/models/moonshotai-kimi-k3): `moonshotai/kimi-k3`, input 215,350 toman / output 2,950,000 toman per 1M tokens
- [GPT-4o Mini](https://hooshvana.ir/models/openai-gpt-4o-mini): `openai/gpt-4o-mini`, input 44,250 toman / output 177,000 toman per 1M tokens
- [GPT-6 Astra](https://hooshvana.ir/models/openai-gpt-6-astra): `openai/gpt-6-astra`, input 2,950,000 toman / output 14,750,000 toman per 1M tokens
- [DeepSeek V4 Pro](https://hooshvana.ir/models/deepseek-deepseek-v4-pro): `deepseek/deepseek-v4-pro`, input 281,814 toman / output 563,598 toman per 1M tokens
- [GPT-5 Mini](https://hooshvana.ir/models/openai-gpt-5-mini): `openai/gpt-5-mini`, input 73,750 toman / output 590,000 toman per 1M tokens
- [Gemini 3.1 Pro](https://hooshvana.ir/models/google-gemini-3-1-pro-preview): `google/gemini-3.1-pro-preview`, input 590,000 toman / output 3,540,000 toman per 1M tokens

## Tools and use cases

- [Persian token counter and cost calculator](https://hooshvana.ir/tools/token-counter)
- [Customer support chatbot use case](https://hooshvana.ir/use-cases/customer-support-chatbot)
- [Persian content generation use case](https://hooshvana.ir/use-cases/content-generation)

## Blog

- [رفع خطای unsupported_country در API OpenAI از ایران](https://hooshvana.ir/blog/openai-api-iran-403-error): اگر درخواست شما به API OpenAI با خطای ۴۰۳ و کد unsupported_country_region_territory برمی‌گردد، مشکل از کد نیست؛ OpenAI درخواست‌های ایران را نمی‌پذیرد. در این راهنما علت خطا و راه پایدار رفع آن را با نمونه‌کد پایتون، Node.js و curl توضیح می‌دهیم.
- [API هوش مصنوعی چیست و چطور از آن استفاده کنیم؟](https://hooshvana.ir/blog/what-is-ai-api): API هوش مصنوعی راهی است که برنامه‌ی شما با آن از مدل‌هایی مثل GPT و Claude متن، تصویر یا صدا می‌گیرد. در این راهنما مفاهیم پایه مثل درخواست، پاسخ، توکن و قیمت‌گذاری را ساده توضیح می‌دهیم و قدم‌به‌قدم اولین درخواست را می‌فرستیم.
- [توکن چیست و چرا متن فارسی گران‌تر است؟](https://hooshvana.ir/blog/persian-tokens-cost): توکن واحدی است که مدل‌های زبانی متن را با آن می‌خوانند و هزینه را با آن حساب می‌کنند. متن فارسی معمولاً به توکن‌های بیشتری شکسته می‌شود و همین آن را گران‌تر می‌کند. در این مقاله علت را توضیح می‌دهیم و نشان می‌دهیم چطور مصرف توکن را بسنجید و کم کنید.
- [اتصال Cursor و Codex CLI به API ایرانی](https://hooshvana.ir/blog/cursor-codex-iranian-api-guide): Cursor و Codex CLI را به مدل‌های GPT، Claude، Gemini و DeepSeek وصل کنید و هزینه را ریالی بپردازید. تنظیمات کامل هر دو ابزار، انتخاب مدل و رفع خطاهای رایج.
- [تبدیل متن به گفتار فارسی با ElevenLabs در ایران](https://hooshvana.ir/blog/persian-text-to-speech-elevenlabs): صدای فارسی طبیعی برای کتاب صوتی، ویدئو و دستیار صوتی بسازید. کدام مدل ElevenLabs فارسی را خوب می‌خواند، هزینه‌ی هر دقیقه چقدر است و چطور با API هوشوانا شروع کنیم؟
- [ساخت چت‌بات فروشگاهی با هوش مصنوعی و پایگاه دانش](https://hooshvana.ir/blog/shop-chatbot-with-knowledge-base): چت‌باتی بسازید که محصولات، قیمت‌ها و قوانین فروشگاه شما را می‌شناسد و شبانه‌روز به مشتری پاسخ می‌دهد. از ساخت پایگاه دانش تا اتصال به سایت، همه‌ی مراحل را با مثال پیش می‌بریم.
- [۱۰ روش کاهش هزینه‌ی API هوش مصنوعی](https://hooshvana.ir/blog/reduce-ai-api-costs): صورت‌حساب API بالا رفته است؟ با انتخاب درست مدل، کش پرامپت، محدود کردن خروجی و چند ترفند ساده می‌توانید هزینه را تا چند برابر کم کنید، بدون اینکه کیفیت محصول افت کند.
- [بهترین هوش مصنوعی برای محتوای فارسی: GPT یا Claude؟](https://hooshvana.ir/blog/gpt-vs-claude-vs-gemini-persian-content): کدام مدل فارسی طبیعی‌تری می‌نویسد؟ کدام برای سئو بهتر است و کدام ارزان‌تر تمام می‌شود؟ سه خانواده‌ی اصلی مدل‌های زبانی را با معیارهای واقعی تولید محتوا مقایسه کرده‌ایم.
- [اتصال Claude Code به API ایرانی با پرداخت ریالی](https://hooshvana.ir/blog/claude-code-hooshvana-guide): Claude Code را بدون تحریم، بدون کارت ارزی و با پرداخت ریالی راه بیندازید. در این راهنما قدم‌به‌قدم کلید می‌سازیم، متغیرهای محیطی را تنظیم می‌کنیم و هزینه را زیر کنترل نگه می‌داریم.

## Company

- [About Hooshvana](https://hooshvana.ir/about)
- [Referral program (wallet credit, not cash)](https://hooshvana.ir/referral)
- [Security and data privacy](https://hooshvana.ir/security)
- [Changelog](https://hooshvana.ir/changelog)
- [Contact and support](https://hooshvana.ir/contact)

## Optional

- [Pricing and calculator](https://hooshvana.ir/pricing)
- [Compare with direct APIs and monthly plans](https://hooshvana.ir/compare)
- [Service status](https://hooshvana.ir/status)
- [Terms](https://hooshvana.ir/terms) and [Privacy](https://hooshvana.ir/privacy)