مستندات وب‌سرویس هوشان

راهنمای جامع اتصال به API استاندارد و سازگار با الگوی OpenAI. مناسب برای افزونه‌های وردپرس، فروشگاه‌های اینترنتی و توسعه‌دهندگان.

۱. شروع سریع

1. در سایت https://hooshan-api.ir ثبت‌نام کنید (ورود با کد یکبارمصرف).
2. پروفایل خود را تکمیل نمایید.
3. از بخش داشبورد، یک توکن API ایجاد کنید. توکن تنها یک‌بار نمایش داده می‌شود؛ آن را در محل امن ذخیره کنید.
4. حساب خود را شارژ کنید.
5. درخواست‌ها را با هدر احراز هویت ارسال نمایید.

آدرس پایه API:

https://hooshan-api.ir/v1

۲. احراز هویت

تمام endpointها (به‌جز وضعیت سلامت سرویس) نیازمند توکن هستند.

Authorization: Bearer YOUR_API_TOKEN

۳. فهرست Endpointها

۴. بازنویسی و تکمیل متن

{
  "model": "gpt-4o-mini",
  "messages": [
    {
      "role": "system",
      "content": "متن را به صورت حرفه‌ای، یونیک و مناسب فروشگاه اینترنتی بازنویسی کن. از نام برندهای رقیب استفاده نکن."
    },
    {
      "role": "user",
      "content": "متن اصلی محصول در اینجا قرار می‌گیرد..."
    }
  ],
  "max_tokens": 1500,
  "temperature": 0.7
}

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1710000000,
  "model": "gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "متن بازنویسی‌شده..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 120,
    "completion_tokens": 340,
    "total_tokens": 460
  },
  "hooshan": {
    "remaining_balance": 1249540
  }
}

۵. بررسی اعتبار حساب

curl -X GET https://hooshan-api.ir/v1/account \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

{
  "object": "account",
  "data": {
    "mobile": "09xxxxxxxxx",
    "balance_tokens": 1250000,
    "balance_rial": 187500,
    "total_charged": 2000000,
    "total_consumed": 750000
  }
}

۶. ساخت تصویر

{
  "model": "dall-e-3",
  "prompt": "تصویر حرفه‌ای محصول روی پس‌زمینه روشن",
  "size": "1024x1024",
  "n": 1
}

{
  "created": 1710000000,
  "data": [
    { "url": "https://..." }
  ],
  "hooshan": {
    "tokens_used": 10000,
    "remaining_balance": 1239158
  }
}

۷. نمونه کدها

در تمام نمونه‌ها به‌جای YOUR_API_TOKEN توکن واقعی خود را قرار دهید. هرگز توکن را در مخزن کد عمومی قرار ندهید.

cURL

curl -X POST https://hooshan-api.ir/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "system", "content": "بازنویسی حرفه‌ای و یونیک برای فروشگاه"},
      {"role": "user", "content": "متن محصول..."}
    ],
    "max_tokens": 1200
  }'

PHP

$token = getenv('HOOSHAN_API_TOKEN'); // از متغیر محیطی بخوانید
$url   = 'https://hooshan-api.ir/v1/chat/completions';

$payload = [
    'model' => 'gpt-4o-mini',
    'messages' => [
        ['role' => 'system', 'content' => 'بازنویسی حرفه‌ای، یونیک و مناسب فروشگاه اینترنتی'],
        ['role' => 'user', 'content' => $productText],
    ],
    'max_tokens' => 1500,
];

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $token,
        'Content-Type: application/json',
        'Accept: application/json',
    ],
    CURLOPT_POSTFIELDS     => json_encode($payload, JSON_UNESCAPED_UNICODE),
    CURLOPT_TIMEOUT        => 120,
    CURLOPT_SSL_VERIFYPEER => true,
]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$data = json_decode($response, true);
if ($httpCode === 200 && isset($data['choices'][0]['message']['content'])) {
    $rewritten = $data['choices'][0]['message']['content'];
    $remaining = $data['hooshan']['remaining_balance'] ?? null;
}

JavaScript

const res = await fetch('https://hooshan-api.ir/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify({
    model: 'gpt-4o-mini',
    messages: [
      { role: 'system', content: 'بازنویسی یونیک و سئو‌شده' },
      { role: 'user', content: productText }
    ],
    max_tokens: 1500
  })
});
const data = await res.json();
if (res.ok) {
  console.log(data.choices[0].message.content);
} else {
  console.error(data.error?.message || data.message);
}

Python

import os
import requests

token = os.environ.get("HOOSHAN_API_TOKEN")
url = "https://hooshan-api.ir/v1/chat/completions"

payload = {
    "model": "gpt-4o-mini",
    "messages": [
        {"role": "system", "content": "بازنویسی حرفه‌ای برای فروشگاه"},
        {"role": "user", "content": product_text},
    ],
    "max_tokens": 1500,
}
headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json",
}
r = requests.post(url, json=payload, headers=headers, timeout=120)
data = r.json()
if r.status_code == 200:
    print(data["choices"][0]["message"]["content"])
else:
    print(data.get("error", {}).get("message", data))

۸. کدهای خطا

پاسخ خطا در قالب استاندارد مشابه OpenAI برگردانده می‌شود:

{
  "error": {
    "message": "توضیح خطا به زبان فارسی",
    "type": "insufficient_quota",
    "code": 402
  }
}

۹. امنیت و محدودیت‌ها

• ارتباط باید از طریق HTTPS برقرار شود.
• توکن‌ها به‌صورت رمزنگاری‌شده (hash) در پایگاه داده ذخیره می‌شوند و فقط یک‌بار در زمان ایجاد نمایش داده می‌شوند.
• محدودیت نرخ درخواست (Rate Limit) روی نشانی و روی هر توکن اعمال می‌شود.
• اعتبار قبل از اجرای هر درخواست بررسی می‌شود و هرگز منفی نمی‌گردد.
• در صورت خطا در ساخت تصویر، اعتبار بازگردانده می‌شود.
• تمام درخواست‌ها با نشانی و زمان ثبت می‌شوند.
• امکان مسدودسازی نشانی‌های مشکوک توسط مدیریت وجود دارد.

۱۰. نکات ویژه افزونه وردپرس

• قبل از بازنویسی، با GET /v1/account موجودی را چک کنید تا پیام خطای مناسب به مدیر فروشگاه نمایش داده شود.
• پرامپت سیستم را از تنظیمات افزونه (قابل ویرایش توسط مدیر سایت مشتری) بخوانید.
• توکن را فقط در تنظیمات امن افزونه ذخیره کنید و هرگز در خروجی صفحه قرار ندهید.
• لینک شارژ اعتبار را به آدرس رسمی داشبورد کاربر هدایت کنید.
• از فیلد hooshan.remaining_balance برای به‌روزرسانی نمایش اعتبار در ادمین وردپرس استفاده کنید.

نسخه مستندات: ۱.۵.۰ — هوشان — https://hooshan-api.ir