مرجع API

GatifyAI یک endpoint برای chat completions ارائه می‌کند که با OpenAI SDK سازگار است — client فعلی OpenAI خود را به GatifyAI اشاره دهید و بدون نیاز به client library خاصی کار می‌کند.

Base URL

هر request به این نشانی می‌رود:

https://gatifyai.com/api/v1

احراز هویت

در صفحه API keys یک key بسازید، سپس آن را به‌صورت bearer token در header Authorization بفرستید. فقط hash کلید شما ذخیره می‌شود — هنگام ساخت آن را کپی کنید، چون GatifyAI نمی‌تواند دوباره آن را به شما نشان دهد.

شروع سریع

یک request حداقلی در curl، Python یا TypeScript:

curl https://gatifyai.com/api/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_NAME",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

محدود کردن key به modelهای مشخص

به‌صورت پیش‌فرض، یک key جدید می‌تواند از هر model رایگان GatifyAI استفاده کند، با همان automatic fallover که web chat هنگام در دسترس نبودن یک model استفاده می‌کند. به‌جای آن می‌توانید key را به یک model مشخص یا یک list کوتاه محدود کنید — در این صورت key فقط modelهای همان list را، به ترتیبی که داده‌اید، استفاده می‌کند، فارغ از اینکه request چه modelای بخواهد. درخواست model خارج از آن list یک 400 error برمی‌گرداند که modelهای واقعاً مجاز برای key را نام می‌برد.

Chat کردن به‌عنوان persona

برای chat کردن به‌عنوان persona منتشرشده در community gallery مقدار model: "persona/<slug>" را بفرستید — personality و modelهای preferred آن خودکار استفاده می‌شوند، و اگر برای key خود allowed models تنظیم کرده باشید همچنان با آن‌ها محدود می‌شوند. slug یک persona و نمونه آماده را در صفحه خودش، زیر tab API، پیدا کنید.

{
  "model": "persona/senior-engineer",
  "messages": [{"role": "user", "content": "Review my code."}]
}

Streaming در برابر non-streaming

برای دریافت tokenها هم‌زمان با تولیدشان، stream: true را تنظیم کنید، دقیقاً مانند format streaming در OpenAI (Server-Sent Events، پایان‌یافته با [DONE]). آن را حذف کنید یا false بگذارید تا منتظر reply کامل بمانید و یک response JSON دریافت کنید — این حالت default است.

Errors

Errors از شکل خطای OpenAI پیروی می‌کنند: {"error": {"message": "...", "type": "..."}}. 401 یعنی key گم‌شده، invalid یا revoked است. 400 یعنی خود request invalid است — معمولاً model ناشناخته، persona slug منتشرنشده/ناشناخته یا model خارج از allowed list کلید شما. 502 یعنی هیچ candidate modelای پاسخ نداده است.

{
  "error": {
    "message": "This API key may only use: llama-3.1-8b:free",
    "type": "invalid_request_error"
  }
}

Rate limits

API requests در همان per-account chat rate limit مربوط به web app حساب می‌شوند — فعلاً quota جداگانه‌ای برای API traffic وجود ندارد.