معرفی

API فست‌ای‌آی‌جی یک لایه یکپارچه و شفاف بر بستر درگاه‌های مدل‌های هوش‌مصنوعی است که با الگوی (OpenAI) کار می‌کند. تمام درخواست‌ها از مسیر /api/v1 عبور کرده و ساختار ورودی/خروجی آشنا (OpenAI-style) را حفظ می‌کنند.

آدرس پایه API

• Production: https://api.fastaig.ir/api/v1

احراز هویت

در تمام درخواست‌ها هدر زیر الزامی است:

Authorization: Bearer <CLIENT_API_KEY>

کلید سمت مشتری (Client Key) را از پنل دریافت کنید.

شروع سریع

یک پیام ساده به مسیر Chat Completions ارسال می‌کنیم:

curl https://api.fastaig.ir/api/v1/chat/completions 	-H "Authorization: Bearer $CLIENT_API_KEY" 	-H "Content-Type: application/json" 	-d '{
		"model": "openai/gpt-4o-mini",
		"messages": [
			{"role": "user", "content": "سلام! امروز هوای تهران چطور است؟"}
		]
	}'

تست لایو

const res = await fetch('https://api.fastaig.ir/api/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + process.env.FASTAIG_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'openai/gpt-4o-mini',
    messages: [{ role: 'user', content: 'سلام! یک نکته جالب درباره تهران بگو.' }]
  })
});
const json = await res.json();
console.log(json.choices?.[0]?.message?.content);

Chat Completions

الگوی سازگار با OpenAI. بدنه درخواست:

POST /api/v1/chat/completions
Content-Type: application/json

{
	"model": "meta/llama-3.1-70b-instruct",
	"messages": [
		{"role": "user", "content": "یک هشتگ جذاب برای فروشگاه آنلاین لوازم خانگی پیشنهاد بده"}
	],
	"temperature": 0.7,
	"top_p": 0.9
}

نمونه پاسخ (خلاصه‌شده):

{
	"id": "gen_...",
	"model": "meta/llama-3.1-70b-instruct",
	"choices": [
		{
			"message": {
				"role": "assistant",
				"content": "#خانه_هوشمند، #به_صرفه، #انتخاب_برتر"
			}
		}
	]
}

استریم (Server-Sent Events)

با قرار دادن "stream": true پاسخ به‌صورت SSE ارسال می‌شود.

curl https://api.fastaig.ir/api/v1/chat/completions 		-H "Authorization: Bearer $CLIENT_API_KEY" 		-H "Content-Type: application/json" 		-d '{
			"model": "openai/gpt-4o-mini",
			"stream": true,
			"messages": [
				{"role":"user","content":"یک جوک کوتاه بگو"}
			]
		}'
	

توجه: برای ثبت تاریخچه چت در فست‌ای‌آی‌جی، می‌توانید هدرX-Chat-Session-IDرا با مقدار عددی شناسه چت ارسال کنید.

مدل‌ها

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

• openai/gpt-4o-mini
• google/gemini-2.0-flash-001
• meta/llama-3.1-70b-instruct

برای فهرست کامل مدل‌ها به مستندات درگاه یا پنل فست‌ای‌آی‌جی مراجعه کنید.

هدرهای اختیاری مفید

• HTTP-Referer: نسبت‌دادن درخواست به دامنه/مسیر
• X-Title: عنوان مختصر اپلیکیشن/صفحه برای گزارش‌دهی
• X-Chat-Session-ID: ثبت تاریخچه چت سمت فست‌ای‌آی‌جی

کدهای خطا

• 401: کلید API نامعتبر یا ارسال نشده
• 403: دسترسی غیرفعال یا درگاه نامعتبر
• 429: محدودیت نرخ (Rate Limit)
• 5xx: خطای درگاه بالادستی

نمونه پاسخ خطا:

{
	"error": {
		"message": "Invalid API key",
		"type": "invalid_request_error"
	}
}

لیمیت‌ها

محدودیت‌ها بر اساس پلن شما و سیاست‌های درگاه بالادستی اعمال می‌شوند. در صورت دریافت 429، فاصله بین درخواست‌ها را افزایش دهید یا با پشتیبانی تماس بگیرید.

نمونه کدها

بین زبان‌های مختلف جابه‌جا شوید.

const res = await fetch('https://api.fastaig.ir/api/v1/chat/completions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + process.env.NEXT_PUBLIC_FASTAIG_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'openai/gpt-4o-mini',
    messages: [{ role: 'user', content: 'سلام دنیا!' }]
  })
});
const json = await res.json();
console.log(json.choices?.[0]?.message?.content);