رفتن به محتوای اصلی
هوشوانا

شروع سریع

در چند دقیقه در هوشوانا ثبت‌نام کنید، کلید API بسازید و اولین درخواست خود را با cURL، Python یا Node.js به مدل‌های هوش مصنوعی بفرستید.

آخرین به‌روزرسانی:

هوشوانا یک درگاه API برای مدل‌های هوش مصنوعی است. با یک کلید و یک آدرس، به بیش از ۸۰ مدل از OpenAI، Anthropic، Google، DeepSeek، Meta، Mistral، xAI، Qwen و صداهای ElevenLabs دسترسی دارید. API هوشوانا با OpenAI و Anthropic سازگار است، پس اگر قبلاً با این SDKها کار کرده‌اید، کافی است آدرس پایه و کلید را عوض کنید. پرداخت ریالی است، احراز هویت لازم نیست و فقط به اندازه‌ی مصرف هزینه می‌دهید.

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

۱. ثبت‌نام و اعتبار هدیه

به https://hooshvana.ir بروید و حساب بسازید. بلافاصله بعد از ثبت‌نام، ۲۰٬۰۰۰ تومان اعتبار هدیه به کیف پول شما اضافه می‌شود تا بتوانید بدون پرداخت، چند درخواست آزمایشی بفرستید.

۲. شارژ کیف پول

برای استفاده‌ی جدی‌تر، کیف پول را از https://hooshvana.ir/dashboard/wallet شارژ کنید. سه روش پرداخت در دسترس است:

  • درگاه پرداخت پارسیان
  • درگاه زرین‌پال
  • کارت‌به‌کارت (پس از تأیید واحد مالی به کیف پول اضافه می‌شود)

حداقل مبلغ شارژ ۵۰٬۰۰۰ تومان است. جزئیات بیشتر در قیمت‌گذاری و صورتحساب آمده است.

۳. ساخت کلید API

در داشبورد به بخش کلیدها بروید و «کلید جدید» را بزنید. یک نام قابل‌تشخیص انتخاب کنید (مثلاً «سرور تولید» یا «لپ‌تاپ شخصی»). کلید با پیشوند hv- شروع می‌شود و فقط یک بار نمایش داده می‌شود، پس همان لحظه آن را در جای امنی ذخیره کنید.

بهترین کار این است که کلید را در یک متغیر محیطی نگه دارید:

Shell
export HOOSHVANA_API_KEY="hv-..."

در هنگام ساخت کلید می‌توانید برای آن قانون بگذارید، مثلاً سقف هزینه‌ی ماهانه یا محدود کردن به چند مدل خاص. این موضوع در قوانین کلید و گروه مدل توضیح داده شده است.

۴. اولین درخواست

آدرس پایه‌ی API برای همه‌ی SDKهای سازگار با OpenAI این است:

https://hooshvana.ir/api/v1

با cURL

Shell
curl https://hooshvana.ir/api/v1/chat/completions \
  -H "Authorization: Bearer $HOOSHVANA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant. Answer in Persian."},
      {"role": "user", "content": "سه کاربرد هوش مصنوعی در کسب‌وکارهای کوچک را بگو."}
    ]
  }'

با Python

ابتدا SDK رسمی OpenAI را نصب کنید:

Shell
pip install openai
Python
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://hooshvana.ir/api/v1",
    api_key=os.environ["HOOSHVANA_API_KEY"],
)

completion = client.chat.completions.create(
    model="openai/gpt-4o-mini",
    messages=[
        {"role": "system", "content": "You are a helpful assistant. Answer in Persian."},
        {"role": "user", "content": "سه کاربرد هوش مصنوعی در کسب‌وکارهای کوچک را بگو."},
    ],
)

print(completion.choices[0].message.content)
print(completion.usage)

با Node.js

Shell
npm install openai
JavaScript
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://hooshvana.ir/api/v1",
  apiKey: process.env.HOOSHVANA_API_KEY,
});

const completion = await client.chat.completions.create({
  model: "openai/gpt-4o-mini",
  messages: [
    { role: "system", content: "You are a helpful assistant. Answer in Persian." },
    { role: "user", content: "سه کاربرد هوش مصنوعی در کسب‌وکارهای کوچک را بگو." },
  ],
});

console.log(completion.choices[0].message.content);

اگر پاسخ را دیدید، همه چیز آماده است. اگر خطا گرفتید، پیام خطا به فارسی توضیح می‌دهد چه اتفاقی افتاده است. فهرست کامل کدها در خطاها و کدها آمده است.

۵. تعویض مدل

شناسه‌ی مدل‌ها به شکل vendor/model است. برای امتحان یک مدل دیگر، فقط مقدار model را عوض کنید:

کاربردنمونه‌ی شناسه
گفتگوی سریع و ارزانopenai/gpt-4o-mini
کدنویسی و استدلالanthropic/claude-sonnet-4.6
متن‌های طولانیgoogle/gemini-2.5-pro
اقتصادیdeepseek/deepseek-v4-flash

این شناسه‌ها فقط نمونه‌اند. فهرست دقیق و به‌روز را از کاتالوگ مدل‌ها یا با فراخوانی GET /models بگیرید:

Shell
curl https://hooshvana.ir/api/v1/models \
  -H "Authorization: Bearer $HOOSHVANA_API_KEY"
Python
for model in client.models.list():
    print(model.id)

۶. پیگیری مصرف

هر درخواست با زمان، مدل، تعداد توکن، هزینه و وضعیت در لاگ درخواست‌ها ثبت می‌شود. هزینه‌ی هر درخواست بعد از اتمام آن از کیف پول کسر می‌شود و در دفتر تراکنش‌ها قابل مشاهده است.

نصب یک‌خطی برای ابزارهای کدنویسی

اگر از Claude Code، Codex CLI یا Cursor استفاده می‌کنید، یک اسکریپت نصب همه را یک‌جا به هوشوانا وصل می‌کند:

Shell
curl -fsSL https://hooshvana.ir/install.sh | bash

این اسکریپت کلید شما را می‌پرسد و سپس:

  • متغیرهای محیطی Claude Code را تنظیم می‌کند: ANTHROPIC_BASE_URL با مقدار https://hooshvana.ir/api و ANTHROPIC_AUTH_TOKEN با کلید شما
  • سرور MCP هوشوانا را به Claude Code اضافه می‌کند
  • یک ارائه‌دهنده برای Codex CLI به فایل پیکربندی آن اضافه می‌کند
  • پیکربندی MCP را برای Cursor اضافه می‌کند

بخشی که برای Codex CLI اضافه می‌شود چنین است:

TOML
[model_providers.hooshvana]
name = "Hooshvana"
base_url = "https://hooshvana.ir/api/v1"
env_key = "HOOSHVANA_API_KEY"
wire_api = "responses"

اسکریپت پیش از تغییر هر فایل، از آن نسخه‌ی پشتیبان می‌گیرد. با این حال، اجرای مستقیم اسکریپت از اینترنت با bash یعنی به آن اعتماد کرده‌اید. پیشنهاد می‌کنیم ابتدا آن را دانلود کنید، بخوانید و بعد اجرا کنید:

Shell
curl -fsSL https://hooshvana.ir/install.sh -o hooshvana-install.sh
less hooshvana-install.sh
bash hooshvana-install.sh

اگر ترجیح می‌دهید تنظیمات را دستی انجام دهید، اتصال Claude Code را ببینید.

قدم‌های بعدی