راهنمای فنی اتصال به آتنا

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

آدرس‌ها و فهرست مدل‌ها

دامنهٔ آتنا را با یکی از مسیرهای زیر به‌عنوان Base URL تنظیم کنید. نام دقیق مدل را از فهرست مدل‌های مجاز همان خانواده دریافت کنید.

https://athena.zistbom.digital/openai/v1
https://athena.zistbom.digital/deepseek/v1
https://athena.zistbom.digital/anthropic/v1

GET /openai/v1/models
Authorization: Bearer <ATHENA_KEY>

GET /deepseek/v1/models
Authorization: Bearer <ATHENA_KEY>

GET /anthropic/v1/models
x-api-key: <ATHENA_KEY>
anthropic-version: 2023-06-01

قراردادهای سازگار با OpenAI و DeepSeek

برای هر دو خانواده از Chat Completions استفاده کنید. در درخواست DeepSeek، مسیر را به /deepseek/v1/chat/completions تغییر دهید. نام مدل باید متعلق به فهرست همان خانواده باشد.

POST /openai/v1/chat/completions
Authorization: Bearer <ATHENA_KEY>
Idempotency-Key: unique-request-0001
Content-Type: application/json

{"model":"YOUR_ENABLED_MODEL","messages":[{"role":"user","content":"سلام"}],"max_completion_tokens":256,"stream":false}

قرارداد سازگار با Anthropic / Claude

POST /anthropic/v1/messages
x-api-key: <ATHENA_KEY>
anthropic-version: 2023-06-01
Idempotency-Key: unique-request-0002
Content-Type: application/json

{"model":"YOUR_ENABLED_MODEL","messages":[{"role":"user","content":"سلام"}],"max_tokens":256,"stream":false}

پاسخ جریانی

برای دریافت تدریجی پاسخ، stream: true بفرستید و پاسخ text/event-stream را به‌صورت SSE بخوانید. آتنا قالب رویدادهای همان خانواده را منتقل می‌کند. در OpenAI و DeepSeek آمار استفاده در جریان درخواست می‌شود. پراکسی محصول باید پاسخ را بدون بافر عبور دهد. اتصال قطع‌شده بازپخش نمی‌شود.

انتقال فراخوانی ابزار

در مدل‌های دارای قابلیت ابزار، تعریف ابزارها را طبق قرارداد همان خانواده در درخواست قرار دهید. فراخوانی ابزار به محصول شما برمی‌گردد؛ محصول ابزار را اجرا می‌کند و نتیجه را در ادامهٔ گفت‌وگو می‌فرستد. آتنا ابزار مشتری را اجرا نمی‌کند.

شناسهٔ درخواست و خطاها

برای هر عملیات یک Idempotency-Key یکتا با ۸ تا ۱۰۰ نویسه از حروف و ارقام انگلیسی، خط تیره یا زیرخط ارسال کنید. تکرار همان شناسه پاسخ ۴۰۹ می‌دهد و درخواست دوباره به مدل ارسال نمی‌شود. پاسخ قبلی بازگردانده نمی‌شود. شناسهٔ پیگیری در هدر X-Athena-Operation-Id قرار دارد.

خطای ۴۰۰ معمولاً نشان‌دهندهٔ پارامتر نامعتبر یا قابلیت پشتیبانی‌نشده، ۴۰۱ کلید نامعتبر، ۴۰۳ دسترسی غیرمجاز، ۴۰۴ مدل ناموجود، ۴۰۹ عملیات تکراری، ۴۲۹ محدودیت درخواست و ۵۰۲ تا ۵۰۴ خطای اتصال یا پاسخ سرویس‌دهنده است. برای بررسی خطا، کد خطا و شناسهٔ عملیات را نگه دارید. پس از قطع ارتباط یا پایان مهلت، درخواست را با شناسهٔ جدید خودکار تکرار نکنید؛ ممکن است سرویس‌دهنده پردازش را انجام داده باشد.

قابلیت‌ها و نگهداری متن

نسخهٔ فعلی گفت‌وگوی متنی، پاسخ عادی و جریانی و انتقال فراخوانی ابزار را پشتیبانی می‌کند. فایل، تصویر، صوت، Responses، ابزارهای میزبانی‌شده، thinking اختصاصی و strict schema پشتیبانی نمی‌شوند. قابلیت ابزار باید برای مدل فعال باشد.

ذخیرهٔ متن درخواست و پاسخ پیش‌فرض خاموش است. با فعال‌سازی تاریخچه برای پروژه، متن تا ۳۰ روز نگهداری می‌شود. درخواست حذف تاریخچه، ذخیرهٔ جدید را هم خاموش می‌کند.