مرکز توسعه‌دهندگان آوناAPI v1

راهنمای اتصال به API آونا

آدرس API و روش احراز هویت را اینجا پیدا کنید. بعد با یکی از نمونه‌کدها اولین درخواست را از پروژه‌تان بفرستید.

سازگار با رابط OpenAIاتصال امن با کلید APIیک آدرس پایه
BASE URLhttps://api.avenaai.ir/v1
01 / GETTING STARTED

اولین درخواست در سه قدم

برای اولین درخواست، فقط یک کلید معتبر، یک مدل فعال و اعتبار کافی لازم دارید.

02 / AUTHENTICATION

احراز هویت و کلید API

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

کلید API یک اطلاعات محرمانه است.

آن را در متغیر محیطی سرور نگه دارید، نه در جاوااسکریپت مرورگر یا مخزن عمومی کد.

Authorization: Bearer av-YOUR_API_KEY

نمونه‌ها از متغیر محیطی AVENAAI_API_KEY استفاده می‌کنند. مقدار YOUR_API_KEY صرفاً جای‌نگهدار است.

03 / EXAMPLES

نمونه‌کد آماده برای اتصال

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

مدل انتخاب‌شده
در حال اتصال به فهرست مدل‌ها
POST /v1/chat/completions
curl -sS https://api.avenaai.ir/v1/chat/completions \
  -H "Authorization: Bearer $AVENAAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"YOUR_ENABLED_MODEL","messages":[{"role":"user","content":"Hello from AvenaAI!"}],"max_completion_tokens":256}'

در نمونه‌ها سقف خروجی ۲۵۶ توکن قرار داده شده تا مبلغ رزروشده اولیه کنترل شود. شناسه مدل باید برای حساب شما مجاز باشد؛ انتشار عمومی مدل به‌تنهایی به‌معنای دسترسی همه حساب‌ها نیست.

04 / MODELS

مدل‌ها و شناسه‌های قابل استفاده

لیست مدل‌ها از تنظیمات زنده Gateway استخراج می‌شود. مدل‌های قابل استفاده برای هر کلید را از مسیر خصوصی زیر دریافت کنید.

GET/v1/modelsاحراز هویت لازم است
List authorized models
curl -sS https://api.avenaai.ir/v1/models \
  -H "Authorization: Bearer $AVENAAI_API_KEY"
05 / BILLING

کیف پول، شارژ و محاسبه مصرف

اعتبار حساب به دلار نگهداری می‌شود. از همین کلید API می‌توانید موجودی و کد شش‌رقمی شارژ را مشاهده کنید.

GET/v1/walletاحراز هویت لازم است
Read wallet balance
curl -sS https://api.avenaai.ir/v1/wallet \
  -H "Authorization: Bearer $AVENAAI_API_KEY"
شارژ کارت‌به‌کارت

در شارژ عمومی، کد شش‌رقمی کیف پول را وارد کرده و رسید پرداخت را برای تأیید دستی ارسال کنید.

رفتن به شارژ عمومی
قیمت‌گذاری مدل‌ها

مدل‌های متنی براساس توکن و مدل‌های تصویری پشتیبانی‌شده مطابق تعرفه هر تصویر محاسبه می‌شوند. قیمت نهایی را در کاتالوگ مشاهده کنید.

مشاهده تعرفه‌ها
06 / API REFERENCE

مسیرهای اصلی API

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

GET/v1/modelsفهرست مدل‌های مجاز حساب
GET/v1/walletموجودی و کد شارژ کیف پول
POST/v1/chat/completionsگفت‌وگو با مدل متنی
POST/v1/responsesدرخواست با رابط Responses
POST/v1/embeddingsبردارسازی متن با مدل مجاز
POST/v1/images/generationsتولید تصویر با مدل تصویر
POST/v1/images/editsویرایش تصویر در مدل پشتیبانی‌شده
07 / TROUBLESHOOTING

خطاهای رایج و معنای آن‌ها

کد HTTP معمولاً مشخص می‌کند مشکل از اعتبار، دسترسی مدل، سهمیه یا سرویس بالادستی است.

400پارامتر نامعتبر یا مدل ناسازگار با مسیر
401کلید API نامعتبر، منقضی یا لغوشده
402اعتبار دلاری کیف پول کافی نیست
404مدل منتشر نشده یا برای این حساب مجاز نیست
429سقف درخواست روزانه کلید یا محدودیت ارائه‌دهنده
503کاتالوگ مدل یا سرویس موقتاً دردسترس نیست
خطای ۴۰۲ یعنی اعتبار کافی نیست.

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

08 / BEST PRACTICES

چند نکته برای اجرای مطمئن

امنیت کلید API و کنترل هزینه‌ها را از اولین روز پروژه در نظر بگیرید.

کلید فقط در بک‌اندهیچ کلیدی را داخل HTML، جاوااسکریپت عمومی یا اپلیکیشن قابل استخراج قرار ندهید.
کلیدهای جداگانه برای پروژه‌هابرای هر سرویس کلید مستقل صادر کنید تا بتوانید دسترسی آن را لغو و مصرفش را پایش کنید.
کنترل سقف خروجی و خطاسقف خروجی و تعداد تلاش دوباره را محدود کنید؛ به خطای ۴۲۹ با فاصله زمانی پاسخ دهید.
شروع ساخت

پروژه بعدی‌ات را به هوش مصنوعی وصل کن.

کلید API، مدل‌ها و مدیریت اعتبار، همگی در پنل شخصی شما آماده‌اند.

رفتن به پنل