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

رفع خطای unsupported_country در API OpenAI از ایران

· ۶ دقیقه مطالعه

OpenAIخطاراهنماAPI

اگر از ایران به API OpenAI درخواست بفرستید و پاسخ HTTP 403 با کد unsupported_country_region_territory و پیام «Country, region, or territory not supported» بگیرید، کد شما مشکلی ندارد. OpenAI درخواست‌هایی را که از کشورهای خارج از فهرست پشتیبانی‌اش می‌آیند رد می‌کند و ایران در این فهرست نیست. راه پایدار رفع این خطا این است که به‌جای اتصال مستقیم، درخواست‌ها را به یک API سازگار با OpenAI مثل هوشوانا بفرستید. در عمل فقط base_url و کلید API عوض می‌شود و بقیه‌ی کد همان می‌ماند.

در ادامه دقیق‌تر می‌بینیم این خطا از کجا می‌آید، چرا راه‌حل‌های موقت معمولاً دوام ندارند و چطور در چند دقیقه برنامه‌تان را دوباره راه بیندازید.

خطای unsupported_country دقیقاً چه می‌گوید؟

پاسخ خطا معمولاً چیزی شبیه این است:

JSON
{
  "error": {
    "code": "unsupported_country_region_territory",
    "message": "Country, region, or territory not supported",
    "param": null,
    "type": "request_forbidden"
  }
}

کد وضعیت HTTP این پاسخ ۴۰۳ است، یعنی سرور درخواست را فهمیده ولی اجازه‌ی پاسخ دادن به آن را ندارد. OpenAI مبدأ درخواست را از روی IP تشخیص می‌دهد. به همین دلیل این خطا حتی با کلید معتبر و حساب شارژشده هم ممکن است برگردد، چون موضوع اعتبار کلید نیست، موضوع محل ارسال درخواست است.

چرا ساختن حساب OpenAI از ایران هم سخت است؟

خطای ۴۰۳ فقط یک بخش ماجراست. برای استفاده از API رسمی OpenAI باید حساب بسازید، شماره‌ی تلفن تأیید کنید و برای پرداخت، کارت بین‌المللی ثبت کنید. کارت‌های بانکی ایرانی در درگاه پرداخت OpenAI پذیرفته نمی‌شوند و شماره‌های ایرانی هم معمولاً برای تأیید حساب قبول نمی‌شوند. نتیجه این است که حتی اگر مشکل IP را کنار بگذاریم، شارژ حساب و پرداخت صورت‌حساب برای بیشتر توسعه‌دهنده‌های داخل ایران عملی نیست.

چرا VPN و پروکسی راه‌حل پایداری نیستند؟

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

  • اعتبار IP: بسیاری از IPهای سرویس‌های VPN عمومی و دیتاسنترهای ارزان شناخته‌شده‌اند. سرویس‌های بزرگ این IPها را با دقت بیشتری بررسی می‌کنند و ممکن است درخواست‌ها بدون هشدار قبلی رد شوند.
  • ریسک مسدود شدن حساب: طبق شرایط استفاده‌ی OpenAI، استفاده از سرویس در مناطق پشتیبانی‌نشده مجاز نیست. اگر حساب به این دلیل مسدود شود، اعتبار باقی‌مانده و کلیدها هم از دست می‌روند.
  • تأخیر و قطعی: هر لایه‌ی اضافه در مسیر، زمان پاسخ را بیشتر می‌کند. وقتی VPN قطع شود یا IP عوض شود، برنامه‌ی شما هم از کار می‌افتد و پیدا کردن علت در محیط تولید وقت‌گیر است.
  • نگهداری سرور: اجرای پروکسی شخصی روی سرور خارجی یعنی هزینه‌ی ارزی، مدیریت امنیت و پایش دائمی؛ کاری که ربطی به محصول اصلی شما ندارد.

راه پایدار: یک API سازگار با OpenAI

هوشوانا یک دروازه‌ی API است که همان قالب درخواست و پاسخ OpenAI را پیاده کرده است. شما درخواست را به سرور هوشوانا می‌فرستید و هوشوانا آن را به ارائه‌دهنده‌ی مدل می‌رساند. چون قالب یکسان است، SDK رسمی OpenAI و کتابخانه‌هایی مثل LangChain بدون تغییر کار می‌کنند. پرداخت هم از کیف پول ریالی انجام می‌شود و به کارت ارزی نیازی ندارید. اگر هنوز حساب نساخته‌اید، راهنمای شروع سریع همه‌ی مراحل را از ثبت‌نام تا اولین درخواست توضیح می‌دهد.

قدم اول: ساخت کلید و تنظیم متغیر محیطی

پس از ثبت‌نام، از بخش کلیدهای داشبورد یک کلید بسازید و آن را در متغیر محیطی قرار دهید. کلید را هیچ‌وقت مستقیم داخل کد ننویسید:

Shell
export HOOSHVANA_API_KEY="hv-کلید-شما"

قدم دوم: تغییر base_url در پایتون

اگر از کتابخانه‌ی رسمی openai در پایتون استفاده می‌کنید، فقط دو پارامتر را هنگام ساختن کلاینت عوض کنید:

Python
import os
from openai import OpenAI

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

response = client.chat.completions.create(
    model="openai/gpt-4o-mini",
    messages=[{"role": "user", "content": "سلام! خودت را در یک جمله معرفی کن."}],
)
print(response.choices[0].message.content)

دقت کنید که شناسه‌ی مدل در هوشوانا پیشوند سازنده دارد، یعنی به‌جای gpt-4o-mini باید openai/gpt-4o-mini بنویسید. فهرست کامل شناسه‌ها در کاتالوگ مدل‌ها هست و مشخصات این مدل را در صفحه‌ی GPT-4o Mini می‌بینید.

قدم سوم: تغییر baseURL در Node.js

در SDK رسمی OpenAI برای Node.js هم همین دو تغییر کافی است:

JavaScript
import OpenAI from "openai";

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

const response = await client.chat.completions.create({
  model: "openai/gpt-4o-mini",
  messages: [{ role: "user", content: "سلام! خودت را در یک جمله معرفی کن." }],
});
console.log(response.choices[0].message.content);

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

اگر پاسخ JSON با فیلد choices برگشت، اتصال درست است.

استریم پاسخ

استریم هم مثل API اصلی کار می‌کند. کافی است stream=True (در پایتون) یا stream: true (در Node.js) را بفرستید تا پاسخ تکه‌تکه و با قالب Server-Sent Events برسد. برای رابط‌های چت، استریم باعث می‌شود کاربر اولین کلمه‌ها را زودتر ببیند و منتظر کامل شدن پاسخ نماند.

چطور اتصال را بررسی کنیم؟

ساده‌ترین بررسی، گرفتن فهرست مدل‌هاست. این درخواست هزینه‌ای ندارد و هم درستی کلید و هم دسترسی به سرور را نشان می‌دهد:

Shell
curl https://hooshvana.ir/api/v1/models \
  -H "Authorization: Bearer $HOOSHVANA_API_KEY"

در پاسخ فهرستی از مدل‌ها با شناسه‌ی کامل می‌بینید. اگر شناسه‌ای که در کد استفاده کرده‌اید در این فهرست نیست، احتمالاً پیشوند سازنده را جا انداخته‌اید.

خطاهای دیگری که ممکن است ببینید

بعد از رفع خطای ۴۰۳، اگر خطای دیگری گرفتید، معمولاً یکی از این‌هاست:

  • ۴۰۱ و کد invalid_api_key: کلید ارسال نشده، اشتباه کپی شده یا باطل شده است. مقدار متغیر محیطی را بررسی کنید و مطمئن شوید هدر Authorization با Bearer شروع می‌شود.
  • ۴۰۲ و کد insufficient_balance: موجودی کیف پول برای این درخواست کافی نیست. کیف پول را شارژ کنید یا مقدار max_tokens را پایین بیاورید.
  • ۴۰۲ و کد spend_cap_reached: سقف هزینه‌ای که برای کلید یا حساب گذاشته‌اید پر شده است. این خطا یعنی محافظ شما درست کار کرده.
  • ۴۰۴ و کد model_not_found: شناسه‌ی مدل اشتباه است. آن را با خروجی GET /models مقایسه کنید.
  • ۴۲۹ و کد rate_limited: تعداد درخواست یا توکن در دقیقه از حد مجاز بیشتر شده است. طبق هدر Retry-After صبر کنید و با backoff دوباره تلاش کنید.

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

جمع‌بندی

خطای unsupported_country_region_territory به محدودیت جغرافیایی OpenAI مربوط است، نه به کد شما. VPN و پروکسی شاید موقتاً جواب بدهند ولی برای محصول واقعی شکننده‌اند. با تغییر base_url به https://hooshvana.ir/api/v1 و استفاده از کلید هوشوانا، همان کد قبلی بدون تغییر دیگری کار می‌کند و هزینه را به تومان پرداخت می‌کنید. برای مقایسه‌ی قیمت مدل‌ها سری به صفحه‌ی قیمت‌ها بزنید و اگر مخصوصاً دنبال مدل‌های GPT هستید، صفحه‌ی API چت‌جی‌پی‌تی را ببینید.

سؤال‌های رایج

آیا با هوشوانا باز هم خطای ۴۰۳ کشور را می‌گیرم؟

خیر. درخواست شما به سرور هوشوانا می‌رسد و ارتباط با ارائه‌دهنده‌ی مدل از سمت هوشوانا انجام می‌شود، پس محدودیت IP ایران روی درخواست شما اعمال نمی‌شود.

باید کدم را بازنویسی کنم؟

خیر. فقط base_url، کلید API و شناسه‌ی مدل (با پیشوند سازنده) عوض می‌شود. ساختار درخواست، پاسخ، استریم و فراخوانی ابزار همان قالب OpenAI است.

غیر از مدل‌های OpenAI به چه مدل‌هایی دسترسی دارم؟

با همان کلید و همان کد می‌توانید مدل‌های Anthropic، Google، DeepSeek و سازنده‌های دیگر را هم صدا بزنید؛ فقط مقدار model را عوض کنید. فهرست کامل در کاتالوگ مدل‌ها است.

آیا برای استفاده به کارت ارزی یا احراز هویت نیاز دارم؟

خیر. ثبت‌نام با شماره‌ی موبایل انجام می‌شود و کیف پول را با کارت بانکی ایرانی شارژ می‌کنید.

اولین درخواستتان را تا پنج دقیقه‌ی دیگر بفرستید

شروع رایگانراهنمای شروع سریع