قبل از اولین درخواست
کلید را امن نگه دارید.
کلید خود را از حساب کاربری بردارید و فقط در محیط امن سمت سرور استفاده کنید. نمونه‌ها برای Bash / zsh نوشته شده‌اند؛ در ویندوز از Git Bash یا WSL استفاده کنید.
export AIZAMIN_API_KEY='YOUR_API_KEY'
export AIZAMIN_BASE_URL='https://aizamin.ir/v1'
YOUR_API_KEY فقط جای‌نگهدار است. در محیط عملیاتی، کلید را از متغیر محیطی یا مخزن امن اسرار بارگذاری کنید؛ آن را داخل کد یا تاریخچهٔ ترمینال ذخیره نکنید.
کلید در هدر، نه در نشانی.کلید را با هدر Authorization و روش Bearer ارسال کنید. کلید را در پارامتر URL، کد مرورگر، مخزن عمومی، تصویر صفحه یا پیام پشتیبانی قرار ندهید. این صفحه کلیدی دریافت نمی‌کند و هیچ درخواست آزمایشی اجرا نمی‌کند.
اول مدل، بعد درخواست
شناسهٔ مدل را حدس نزنید.
فهرست مدل‌ها را با همان کلیدی بگیرید که برای درخواست اصلی استفاده می‌کنید. مقدار دقیق id را از اعضای data بردارید؛ نام نمایشی مدل لزوماً شناسهٔ API نیست.
دریافت فهرست مدل‌ها GET /models
curl --fail-with-body "$AIZAMIN_BASE_URL/models" \
-H "Authorization: Bearer $AIZAMIN_API_KEY"
- وجود مدل در فهرست، به معنی پشتیبانی آن از همهٔ مسیرها نیست. مدل گفتگو را برای چت و مدل تصویر یا صوت را در مسیر مربوط به خودش استفاده کنید.
- در نمونهٔ گفتگو،
CHAT_MODEL_ID را با شناسهٔ یک مدل گفتگویی در دسترس جایگزین کنید. مدل‌های مشخصِ نمونه‌های دیگر هم باید برای کلید شما فعال باشند.
- برای گفتار، فهرست عمومی مدل‌ها به‌تنهایی کافی نیست؛ صدا، زبان و فعال‌بودن مدل باید در تنظیمات حساب نیز مجاز باشند. جزئیات را در بخش متن به گفتار ببینید.
مدل‌ها و دسترسی‌ها ممکن است تغییر کنند؛ هزینهٔ هر قابلیت را پیش از اجرا در تعرفه‌ها بررسی کنید. نمونه‌ها تضمین دسترسی یا قیمت ثابت نیستند.
مرجع سریع
هر قابلیت، مسیر خودش.
نمونه را باز کنید، مقادیر لازم را جایگزین کنید و از سمت سرور بفرستید.
گفتگو و تولید متنPOST
یک پیام بفرستید.
/v1/chat/completions
مدل گفتگویی انتخاب‌شده و پیام‌ها را در messages ارسال کنید. این نمونه جریان پاسخ را غیرفعال می‌کند تا پاسخ یک‌جا دریافت شود.
نمونهٔ درخواست گفتگو curl
curl --fail-with-body "$AIZAMIN_BASE_URL/chat/completions" \
-H "Authorization: Bearer $AIZAMIN_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "CHAT_MODEL_ID",
"messages": [{"role": "user", "content": "سلام! خودت را کوتاه معرفی کن."}],
"stream": false
}'
پیش از اجرا، CHAT_MODEL_ID را با شناسهٔ واقعیِ مدل گفتگویی از فهرست مدل‌های کلید خود جایگزین کنید.
ساخت تصویرPOST
توضیح بدهید، تصویر بگیرید.
/v1/images/generations
توصیف تصویر را در prompt بنویسید. نمونهٔ زیر از مدل و تنظیمات تصویرِ ابزار راه‌اندازی سایت استفاده می‌کند؛ دسترسی کلیدتان را پیش از اجرا بررسی کنید.
نمونهٔ ساخت تصویر curl
curl --fail-with-body "$AIZAMIN_BASE_URL/images/generations" \
-H "Authorization: Bearer $AIZAMIN_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "gpt-image-2.5-sunburst",
"prompt": "یک باغ ایرانی در نور ملایم صبح، نقاشی آبرنگ",
"n": 1,
"size": "1024x1024",
"quality": "medium",
"output_format": "png"
}'
پاسخ این مسیر JSON است، نه فایل PNG خام. دادهٔ تصویر را از پاسخ استخراج کنید؛ تغییر پسوند فایلِ پاسخ به PNG کافی نیست. گزینه‌های اندازه و کیفیت برای همهٔ مدل‌ها یکسان نیست.
جستجوی معنایی و بازیابیPOST
متن را به بردار تبدیل کنید.
/v1/embeddings
برای مقایسهٔ معنایی و جستجو، متن را در input ارسال کنید. خروجی بردار عددی است، نه پاسخ گفتگویی.
نمونهٔ بردارسازی متن curl
curl --fail-with-body "$AIZAMIN_BASE_URL/embeddings" \
-H "Authorization: Bearer $AIZAMIN_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "gemini-embedding-2",
"input": "متن برای جستجوی معنایی",
"dimensions": 128
}'
این نمونهٔ مستندشده برای کلید پولیِ دارای دسترسی است؛ فعال‌بودن آن برای کلید رایگان را فرض نکنید. برای مقایسهٔ بردارها، مدل و تعداد ابعاد را ثابت نگه دارید.
تبدیل متن به گفتار · TTSPOST
متن را بشنوید.
/v1/audio/speech
متن، مدل، شناسهٔ صدا و زبان را ارسال کنید. نمونهٔ زیر خروجی MP3 را در فایل ذخیره می‌کند؛ APPROVED_VOICE_ID جای‌نگهدارِ شناسهٔ صدای مجاز حساب شماست، نه نام صدا.
مدل و صدای مجاز را از کجا پیدا کنم؟پس از ورود به سایت، کاتالوگ گفتار حساب را بررسی کنید: در models، مقدار id، وضعیت enabled، فهرست voices، زبان‌های languages و سقف max_characters را ببینید. این مسیر با نشست ورود سایت کار می‌کند، نه هدر Bearer. برای فارسی، وجود fa را بررسی کنید.
نمونهٔ تولید فایل صوتی curl
curl --fail-with-body "$AIZAMIN_BASE_URL/audio/speech" \
-H "Authorization: Bearer $AIZAMIN_API_KEY" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: tts-example-001' \
-d '{
"model": "eleven_v4_turbo",
"input": "سلام، به ای آی زمین خوش آمدید.",
"voice": "APPROVED_VOICE_ID",
"language": "fa",
"response_format": "mp3"
}' \
--output speech.mp3
مدل نمونه باید در کاتالوگ حساب فعال باشد. جای‌نگهدار صدا را عوض کنید و موفق‌بودن پاسخ HTTP را بررسی کنید؛ پاسخ خطا ممکن است به‌جای صوت در فایل ذخیره شود.
تبدیل صوت به متن · STTPOST
صدا را به نوشته تبدیل کنید.
/v1/audio/transcriptions
فایل محلی را با multipart/form-data بفرستید. مدل‌های عمومی این سرویس whisper-large-v3 و whisper-large-v3-turbo هستند؛ فعال‌بودن آن‌ها برای حساب شما شرط استفاده است.
نمونهٔ پیاده‌سازی صوت curl
curl --fail-with-body "$AIZAMIN_BASE_URL/audio/transcriptions" \
-H "Authorization: Bearer $AIZAMIN_API_KEY" \
-H 'Idempotency-Key: stt-example-001' \
-F 'model=whisper-large-v3-turbo' \
-F 'language=fa' \
-F 'response_format=json' \
-F 'file=@recording.wav'
فایل recording.wav را با مسیر فایل خود جایگزین کنید. هدر Content-Type را دستی تنظیم نکنید؛ curl مرزهای فرم را می‌سازد. قالب‌های پاسخ پشتیبانی‌شده: json، text و verbose_json.
رفع اشکال، بدون افشای کلید
اگر درخواست موفق نبود
- کلید و دسترسی
- هدر Bearer، فعال‌بودن کلید، اعتبار باقی‌مانده و مجازبودن مدل را بررسی کنید.
- مدل و ورودی
- شناسه را دوباره از کاتالوگ بردارید. مسیر، فیلدهای اجباری و نوع بدنهٔ JSON یا فرم را با نمونه تطبیق دهید.
- قطع ارتباط یا پاسخ نامشخص
- درخواست هزینه‌دار را کورکورانه تکرار نکنید. در مسیرهای صوتی، شناسهٔ تکرار را عوض نکنید؛ اگر وضعیت مبهم یا خطای تعارض دریافت شد، ابتدا نتیجه را با پشتیبانی بررسی کنید.
برای پشتیبانی، مسیر درخواست، کد HTTP و متن خطای پاک‌سازی‌شده را بفرستید؛ نه کلید API، هدر احراز هویت یا فایل خصوصی.
