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

SDKها و زبان‌های برنامه‌نویسی

اتصال به هوشوانا با SDKهای رسمی OpenAI در Python، Node.js، PHP و Go و با cURL، به همراه تنظیم متغیرهای محیطی OPENAI_BASE_URL و OPENAI_API_KEY.

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

هوشوانا SDK اختصاصی ندارد و لازم هم نیست. چون API آن با OpenAI و Anthropic سازگار است، SDKهای رسمی و کتابخانه‌های محبوب همین حالا با آن کار می‌کنند. فقط دو چیز را تنظیم می‌کنید: آدرس پایه و کلید API.

تنظیممقدار
آدرس پایه (OpenAI)https://hooshvana.ir/api/v1
آدرس پایه (Anthropic SDK)https://hooshvana.ir/api
کلیدکلید hv-... از داشبورد

متغیرهای محیطی

بیشتر SDKها و ابزارهای سازگار با OpenAI، آدرس و کلید را از این متغیرها می‌خوانند:

Shell
export OPENAI_BASE_URL="https://hooshvana.ir/api/v1"
export OPENAI_API_KEY="$HOOSHVANA_API_KEY"

با این تنظیم، SDKهای Python و Node.js بدون هیچ پارامتری به هوشوانا وصل می‌شوند:

Python
from openai import OpenAI

client = OpenAI()  # reads OPENAI_BASE_URL and OPENAI_API_KEY

اگر در همان سیستم با خود OpenAI هم کار می‌کنید، به جای متغیرهای سراسری، آدرس و کلید را صریحاً در کد بدهید تا اشتباهی پیش نیاید. برای SDKهای Anthropic متغیرهای معادل ANTHROPIC_BASE_URL و ANTHROPIC_API_KEY هستند.

Python

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"],
    timeout=60,
    max_retries=3,
)

resp = client.chat.completions.create(
    model="openai/gpt-4o-mini",
    messages=[{"role": "user", "content": "یک جمله‌ی انگیزشی کوتاه بنویس."}],
)
print(resp.choices[0].message.content)

برای برنامه‌های async از AsyncOpenAI استفاده کنید:

Python
import asyncio
import os
from openai import AsyncOpenAI

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

async def main():
    resp = await client.chat.completions.create(
        model="google/gemini-2.5-flash",
        messages=[{"role": "user", "content": "پایتخت ژاپن کجاست؟"}],
    )
    print(resp.choices[0].message.content)

asyncio.run(main())

Node.js و TypeScript

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

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

const resp = await client.chat.completions.create({
  model: "openai/gpt-4o-mini",
  messages: [{ role: "user", content: "یک جمله‌ی انگیزشی کوتاه بنویس." }],
});

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

این کد را فقط در سمت سرور (Node.js، توابع سرور Next.js و مشابه) اجرا کنید. کلید نباید به مرورگر برسد. احراز هویت و کلیدها را ببینید.

PHP

کتابخانه‌ی openai-php/client با Composer نصب می‌شود. برای تعیین آدرس پایه از factory استفاده کنید:

Shell
composer require openai-php/client guzzlehttp/guzzle
PHP
<?php

require __DIR__ . '/vendor/autoload.php';

$client = OpenAI::factory()
    ->withApiKey(getenv('HOOSHVANA_API_KEY'))
    ->withBaseUri('https://hooshvana.ir/api/v1')
    ->make();

$response = $client->chat()->create([
    'model' => 'openai/gpt-4o-mini',
    'messages' => [
        ['role' => 'user', 'content' => 'سلام! یک نکته‌ی کوتاه درباره‌ی PHP بگو.'],
    ],
]);

echo $response->choices[0]->message->content . PHP_EOL;

در Laravel می‌توانید از بسته‌ی openai-php/laravel استفاده کنید و در فایل .env مقدار OPENAI_API_KEY را کلید هوشوانا و OPENAI_BASE_URL را https://hooshvana.ir/api/v1 قرار دهید.

Go

کتابخانه‌ی رسمی github.com/openai/openai-go آدرس پایه را با option.WithBaseURL می‌گیرد:

Shell
go get github.com/openai/openai-go
Go
package main

import (
	"context"
	"fmt"
	"os"

	"github.com/openai/openai-go"
	"github.com/openai/openai-go/option"
)

func main() {
	client := openai.NewClient(
		option.WithBaseURL("https://hooshvana.ir/api/v1"),
		option.WithAPIKey(os.Getenv("HOOSHVANA_API_KEY")),
	)

	resp, err := client.Chat.Completions.New(context.Background(), openai.ChatCompletionNewParams{
		Model: "openai/gpt-4o-mini",
		Messages: []openai.ChatCompletionMessageParamUnion{
			openai.UserMessage("یک جمله درباره‌ی زبان Go بنویس."),
		},
	})
	if err != nil {
		panic(err)
	}

	fmt.Println(resp.Choices[0].Message.Content)
}

امضای برخی توابع در نسخه‌های مختلف openai-go کمی فرق می‌کند. اگر کد بالا با نسخه‌ی شما کامپایل نشد، مثال‌های README همان نسخه را ببینید. تنظیم option.WithBaseURL در همه‌ی نسخه‌ها یکسان است.

cURL

برای آزمایش سریع یا زبان‌هایی که SDK ندارند، مستقیم HTTP بفرستید:

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": "user", "content": "سلام"}]
  }'

هر زبانی که بتواند درخواست HTTPS با بدنه‌ی JSON بفرستد، می‌تواند با هوشوانا کار کند. ساختار درخواست و پاسخ در Chat Completions آمده است.

SDKهای Anthropic

برای مدل‌های Claude با API سازگار با Anthropic، از SDK رسمی Anthropic با آدرس پایه‌ی https://hooshvana.ir/api استفاده کنید:

Python
import os
import anthropic

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

نمونه‌های کامل در Anthropic Messages API آمده است.

کتابخانه‌ها و ابزارهای دیگر

هر ابزاری که امکان تعیین «OpenAI base URL» یا «OpenAI-compatible endpoint» را دارد، با هوشوانا کار می‌کند. چند نمونه:

  • LangChain (Python): در ChatOpenAI پارامترهای base_url و api_key را تنظیم کنید.
  • LlamaIndex: از کلاس OpenAILike با api_base استفاده کنید.
  • Vercel AI SDK: با createOpenAI({ baseURL, apiKey }) یک ارائه‌دهنده‌ی سفارشی بسازید.

راهنمای ابزارهای کدنویسی و دستیارها مثل Claude Code و Codex CLI در بخش یکپارچه‌سازی‌ها آمده است.

عیب‌یابی

مشکلعلت احتمالی
خطای ۴۰۱کلید درست خوانده نشده؛ مقدار متغیر محیطی را چاپ و بررسی کنید (فقط چند نویسه‌ی اول را)
خطای ۴۰۴ روی همه‌ی درخواست‌هاآدرس پایه اشتباه است؛ برای SDKهای OpenAI باید به /v1 ختم شود
model_not_foundشناسه‌ی مدل بدون پیشوند سازنده نوشته شده؛ مثلاً gpt-4o-mini به جای openai/gpt-4o-mini
درخواست‌ها به OpenAI می‌روندمتغیر OPENAI_BASE_URL در محیط اجرا تنظیم نشده یا SDK قدیمی آن را نمی‌خواند؛ آدرس را صریحاً در کد بدهید

جدول کامل خطاها در خطاها و کدها آمده است.