چطور کلیدهای API سفارشی به Cursor اضافه کنیم: راهنمای کامل (۲۰۲۶)

چطور کلیدهای API سفارشی به Cursor اضافه کنیم: راهنمای کامل (۲۰۲۶)

⚠️ توجه — BYOK مدل GPT-5.5 در Cursor در حال حاضر کار نمی‌کند. اعتبارسنج BYOK کرسر gpt-5.5 را صرف‌نظر از ارائه‌دهنده رد می‌کند — در موضوع انجمن Cursor تأیید شده است. تا زمانی که Cursor رفع کند، در BYOK کرسر از gpt-5.4 (بدون مشکل کار می‌کند) یا هر مدل Claude / Gemini استفاده کنید. خود gpt-5.5 در Codex CLI، OpenCode و فراخوانی مستقیم API بدون مشکل کار می‌کند — تنها BYOK کرسر تحت تأثیر است.

Cursor یکی از محبوب‌ترین ویرایشگرهای کد مجهز به هوش مصنوعی است، اما استفاده داخلی از هوش مصنوعی آن با محدودیت‌های ماهانه همراه است. با افزودن کلیدهای API شخصی، می‌توانید این محدودیت‌ها را دور بزنید، مدل دلخواه خود را انتخاب کنید، و هزینه‌ها را مستقیماً کنترل کنید. این راهنما فرایند افزودن کلیدهای API از OpenAI، Anthropic، Google، و سایر ارائه‌دهندگان به Cursor را توضیح می‌دهد.

چرا کلیدهای API سفارشی اضافه کنیم؟

دلایل متعددی برای آوردن کلیدهای API شخصی به Cursor وجود دارد:

مزیت	Cursor پیش‌فرض	کلیدهای API سفارشی
درخواست‌های سریع ماهانه	۵۰ (رایگان) / ۵۰۰ (Pro)	نامحدود (پرداخت به ازای توکن)
انتخاب مدل	مدل‌های موجود در Cursor	هر مدل از ارائه‌دهنده شما
کنترل هزینه	اشتراک ثابت	فقط هزینه واقعی مصرف
محدودیت نرخ	مشترک با همه کاربران	محدودیت نرخ API خودتان
حریم خصوصی	Cursor درخواست‌ها را پردازش می‌کند	مستقیم به ارائه‌دهنده

اگر قبلاً اعتبار API از OpenAI، Anthropic، یا Google دارید، استفاده از آنها در Cursor به این معناست که برای قابلیت‌های هوش مصنوعی به اشتراک Cursor Pro نیاز ندارید.

مرحله ۱: تنظیمات Cursor را باز کنید

دو روش برای دسترسی به تنظیمات کلید API در Cursor وجود دارد:

روش ۱: رابط تنظیمات

1. Cursor را باز کنید.
2. برای باز کردن تنظیمات Cmd + , (macOS) یا Ctrl + , (Windows/Linux) را فشار دهید.
3. روی "Models" در نوار کناری چپ کلیک کنید.

روش ۲: Command Palette

1. Cmd + Shift + P (macOS) یا Ctrl + Shift + P (Windows/Linux) را فشار دهید.
2. "Cursor Settings" را تایپ کنید و "Cursor: Open Cursor Settings" را انتخاب کنید.
3. به بخش "Models" بروید.

فهرستی از ارائه‌دهندگان هوش مصنوعی با فیلدهایی برای کلیدهای API مشاهده خواهید کرد.

مرحله ۲: کلید API OpenAI اضافه کنید

کلید API OpenAI خود را دریافت کنید

1. به platform.openai.com/api-keys بروید.
2. روی "Create new secret key" کلیک کنید.
3. نامی مثل "Cursor IDE" برای شناسایی آسان انتخاب کنید.
4. کلید را کپی کنید (با sk- شروع می‌شود).

آن را به Cursor اضافه کنید

1. در Cursor Settings > Models، فیلد "OpenAI API Key" را پیدا کنید.
2. کلید API خود را جای‌گذاری کنید.
3. برای تست اتصال روی "Verify" کلیک کنید.

پس از افزودن، می‌توانید مدل‌های OpenAI مثل GPT-4o، GPT-4o-mini، o4-mini، و o3 را در چت، ویرایش‌های inline، و حالت agent در Cursor استفاده کنید.

مدل‌های توصیه‌شده OpenAI برای Cursor

مدل	بهترین برای	هزینه (به ازای ۱ میلیون توکن)
gpt-4o	کدنویسی عمومی، وظایف پیچیده	$2.50 ورودی / $10 خروجی
gpt-4o-mini	تکمیل‌های سریع، وظایف ساده	$0.15 ورودی / $0.60 خروجی
o4-mini	استدلال، دیباگ	$1.10 ورودی / $4.40 خروجی
o3	تصمیمات معماری پیچیده	$2.00 ورودی / $8.00 خروجی

مرحله ۳: کلید API Anthropic اضافه کنید

کلید API Anthropic خود را دریافت کنید

1. به console.anthropic.com بروید.
2. وارد شوید یا یک حساب بسازید.
3. به "API Keys" بروید و روی "Create Key" کلیک کنید.
4. کلید را کپی کنید (با sk-ant- شروع می‌شود).

آن را به Cursor اضافه کنید

1. در Cursor Settings > Models، فیلد "Anthropic API Key" را پیدا کنید.
2. کلید API خود را جای‌گذاری کنید.
3. روی "Verify" کلیک کنید.

اکنون از طریق کلید API شخصی خود به مدل‌های Claude دسترسی دارید.

مدل‌های توصیه‌شده Anthropic برای Cursor

مدل	بهترین برای	هزینه (به ازای ۱ میلیون توکن)
claude-sonnet-4-5-20250514	بهترین کدنویسی جامع	$3.00 ورودی / $15.00 خروجی
claude-haiku-3-5-20241022	تکمیل‌های سریع، وظایف سبک	$0.80 ورودی / $4.00 خروجی
claude-opus-4-20250514	استدلال پیچیده، معماری	$15.00 ورودی / $75.00 خروجی

برای اکثر وظایف کدنویسی، Claude Sonnet 4.5 بهترین تعادل کیفیت و هزینه را دارد.

مرحله ۴: کلید API Google Gemini اضافه کنید

کلید Google AI API خود را دریافت کنید

1. به aistudio.google.com/apikey بروید.
2. روی "Create API Key" کلیک کنید.
3. یک پروژه Google Cloud انتخاب یا بسازید.
4. کلید تولیدشده را کپی کنید.

Google سطح رایگان سخاوتمندانه‌ای برای مدل‌های Gemini ارائه می‌دهد که این را یک گزینه مقرون‌به‌صرفه می‌کند.

آن را به Cursor اضافه کنید

1. در Cursor Settings > Models، فیلد "Google AI API Key" را پیدا کنید.
2. کلید API خود را جای‌گذاری کنید.
3. روی "Verify" کلیک کنید.

مدل‌های توصیه‌شده Google برای Cursor

مدل	بهترین برای	هزینه (به ازای ۱ میلیون توکن)
gemini-2.0-flash	کدنویسی سریع و مقرون‌به‌صرفه	سطح رایگان موجود
gemini-3-pro-preview	وظایف پیچیده چند فایله	$1.25 ورودی / $10.00 خروجی
gemini-2.5-flash	تعادل سرعت و کیفیت	$0.15 ورودی / $0.60 خروجی

سطح رایگان Gemini 2.0 Flash به ویژه مفید است — قبل از پرداخت هر چیزی استفاده قابل توجهی دریافت می‌کنید.

مرحله ۵: یک endpoint سفارشی سازگار با OpenAI اضافه کنید

Cursor از هر API که از قالب OpenAI پیروی کند پشتیبانی می‌کند. این امکان اتصال به موارد زیر را می‌دهد:

• مدل‌های محلی از طریق Ollama
• Together AI
• Groq
• Fireworks AI
• OpenRouter
• هر سرور سازگار با OpenAI

اتصال Ollama (مدل‌های محلی)

ابتدا Ollama را نصب و اجرا کنید:

# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# Pull a coding model
ollama pull qwen2.5-coder:14b

# Ollama runs on localhost:11434 by default

سپس در Cursor:

1. به Settings > Models بروید.
2. "OpenAI API Base URL" یا "Override OpenAI Base URL" را پیدا کنید.
3. base URL را به http://localhost:11434/v1 تنظیم کنید.
4. کلید API را به ollama تنظیم کنید (هر رشته غیر-خالی کار می‌کند).
5. نام مدل qwen2.5-coder:14b را به فهرست مدل‌های خود اضافه کنید.

اتصال OpenRouter (دسترسی به ۱۰۰+ مدل)

OpenRouter امکان دسترسی به صدها مدل از طریق یک کلید API واحد را می‌دهد.

1. به openrouter.ai بروید و یک حساب بسازید.
2. یک کلید API تولید کنید.
3. در Cursor، OpenAI Base URL را به https://openrouter.ai/api/v1 تنظیم کنید.
4. کلید API OpenRouter خود را در فیلد OpenAI API Key جای‌گذاری کنید.
5. از شناسه‌های مدل مثل anthropic/claude-sonnet-4-5، google/gemini-3-pro-preview و غیره استفاده کنید.

اتصال Groq (استنتاج سریع)

Groq استنتاج بسیار سریعی برای مدل‌های متن‌باز ارائه می‌دهد.

1. به console.groq.com بروید و یک حساب بسازید.
2. یک کلید API تولید کنید.
3. در Cursor، OpenAI Base URL را به https://api.groq.com/openai/v1 تنظیم کنید.
4. کلید API Groq خود را جای‌گذاری کنید.
5. از مدل‌هایی مثل llama-3.3-70b-versatile یا mixtral-8x7b-32768 استفاده کنید.

مرحله ۶: تنظیمات اولویت مدل

پس از افزودن کلیدهای API، می‌توانید مدل مورد استفاده Cursor برای وظایف مختلف را تنظیم کنید.

تنظیم مدل‌های پیش‌فرض

در Cursor Settings > Models می‌توانید مدل‌ها را به ویژگی‌های خاص اختصاص دهید:

• Chat: مدل استفاده‌شده برای Cursor Chat (Cmd+L). توصیه‌شده: Claude Sonnet 4.5 یا GPT-4o.
• Inline Edit: مدل برای ویرایش‌های کد inline (Cmd+K). توصیه‌شده: Claude Sonnet 4.5 یا GPT-4o.
• Agent: مدل برای حالت agent. توصیه‌شده: Claude Sonnet 4.5.
• Tab Completion: مدل برای پیشنهادات تکمیل خودکار. توصیه‌شده: یک مدل سریع مثل GPT-4o-mini یا Gemini Flash.

نمونه تنظیم برای بهینه‌سازی هزینه

از مدل‌های ارزان‌تر برای وظایف مکرر و ساده، و مدل‌های پریمیوم برای کارهای پیچیده استفاده کنید:

ویژگی	مدل	دلیل
تکمیل tab	gpt-4o-mini	سریع، ارزان، حجم بالا
ویرایش‌های inline	claude-sonnet-4-5	کیفیت خوب برای تغییرات هدفمند
Chat	claude-sonnet-4-5	بهترین برای بحث و برنامه‌ریزی
حالت Agent	claude-sonnet-4-5	قوی برای وظایف چندمرحله‌ای

مرحله ۷: همه چیز را تأیید کنید

هر کلید API را با یک وظیفه ساده تست کنید:

1. تست chat: Cmd+L را فشار دهید، مدل سفارشی را انتخاب کنید، و "Write a hello world function in Python" بخواهید.
2. تست ویرایش inline: یک بلوک کد را انتخاب کنید، Cmd+K را فشار دهید، و "Add error handling to this function" بخواهید.
3. تست agent: حالت agent را شروع کنید و "Create a new file called test.py with a function that calculates factorial" بخواهید.

اگر هر تستی ناموفق بود، بررسی کنید:

• کلید API به درستی وارد شده باشد (بدون فاصله اضافی).
• حساب API شما اعتبار یا روش پرداخت فعال داشته باشد.
• base URL صحیح باشد (به خصوص برای endpointهای سفارشی).
• نام مدل با قرارداد نام‌گذاری ارائه‌دهنده مطابقت داشته باشد.

رفع اشکال مشکلات رایج

مشکل	علت	راه‌حل
"Invalid API key"	کلید اشتباه یا منقضی‌شده	کلید را از ارائه‌دهنده دوباره تولید کنید
"Model not found"	نام مدل اشتباه	مستندات ارائه‌دهنده را برای شناسه‌های دقیق مدل بررسی کنید
"Rate limit exceeded"	درخواست‌های زیاد	صبر کنید و دوباره امتحان کنید، یا سطح API را ارتقا دهید
"Connection refused" (Ollama)	Ollama اجرا نمی‌شود	Ollama را با ollama serve شروع کنید
پاسخ‌های کند	موقعیت سرور	ارائه‌دهنده‌ای با سرورهای نزدیک به خود انتخاب کنید
"Insufficient credits"	موجودی صفر	به حساب API خود وجه اضافه کنید

سوالات متداول

آیا اگر کلیدهای API شخصی اضافه کنم به Cursor Pro نیاز دارم؟ خیر. با کلیدهای API شخصی می‌توانید از قابلیت‌های هوش مصنوعی بدون اشتراک Cursor Pro استفاده کنید. البته برخی ویژگی‌های خاص Cursor مثل تکمیل‌های tab پیشرفته ممکن است همچنان به Pro نیاز داشته باشند.

کدام کلید API از نظر هزینه مقرون‌به‌صرفه‌تر است؟ Google Gemini سخاوتمندانه‌ترین سطح رایگان را ارائه می‌دهد. برای استفاده پولی، GPT-4o-mini و Gemini Flash ارزان‌ترین گزینه‌های باکیفیت هستند.

آیا می‌توانم چند کلید API را هم‌زمان استفاده کنم؟ بله. می‌توانید کلیدهای چند ارائه‌دهنده را اضافه کنید و بر اساس نیاز بین مدل‌ها جابجا شوید. Cursor از کلید مناسب بر اساس مدل انتخابی استفاده می‌کند.

آیا کلیدهای API به صورت امن ذخیره می‌شوند؟ Cursor کلیدهای API را به صورت محلی روی دستگاه شما ذخیره می‌کند. وقتی از کلیدهای شخصی استفاده می‌کنید، آنها به سرورهای Cursor آپلود نمی‌شوند — درخواست‌ها مستقیماً به ارائه‌دهنده می‌روند.

آیا استفاده از کلیدهای API سفارشی بر محدودیت‌های داخلی Cursor تأثیر می‌گذارد؟ بله. وقتی از کلید API شخصی استفاده می‌کنید، آن درخواست‌ها جزء محدودیت‌های رایگان یا Pro Cursor به حساب نمی‌آیند. صورت‌حساب مستقیماً از ارائه‌دهنده API دریافت می‌کنید.

جمع‌بندی

افزودن کلیدهای API سفارشی به Cursor کنترل کاملی بر تجربه کدنویسی با هوش مصنوعی به شما می‌دهد. می‌توانید مدل‌ها را بر اساس پیچیدگی وظیفه انتخاب کنید، هزینه‌ها را دقیق مدیریت کنید، و از رسیدن به محدودیت‌های داخلی Cursor جلوگیری کنید. تنظیم به ازای هر ارائه‌دهنده کمتر از پنج دقیقه طول می‌کشد.

اگر اپلیکیشن‌هایی می‌سازید که علاوه بر کد به رسانه‌های تولیدشده با هوش مصنوعی نیاز دارند، Hypereal AI را رایگان امتحان کنید — ۳۵ اعتبار، بدون نیاز به کارت اعتباری. API به یکپارچه‌سازی روان در پروژه‌هایی که در Cursor یا هر ویرایشگر دیگری می‌سازید کمک می‌کند.