اتصال به کلود (Claude) از ایران با نمونه کد Python و Node.js

بین توسعه‌دهنده‌ها یک اجماع نانوشته وجود دارد: وقتی پای کد پیچیده، متن طولانی یا پیروی دقیق از دستور وسط باشد، خیلی‌ها Claude را ترجیح می‌دهند. مشکل این‌جاست که Anthropic نه حساب ایرانی می‌پذیرد، نه کارت ایرانی و نه درخواست از IP ایرانی؛ و برخلاف ChatGPT، حتی گرفتن یک حساب واسطه هم به‌سادگی نیست. نتیجه این شده که بسیاری از تیم‌های ایرانی با وجود علاقه، هرگز API کلود را در محصولشان امتحان نکرده‌اند. این راهنما آن فاصله را پر می‌کند: مدل‌ها، روش اتصال از ایران با پرداخت تومانی، نمونه کد در Python و Node.js، نکات پرامپت‌نویسی مخصوص Claude و یک برآورد هزینهٔ واقعی. این راهنما دربارهٔ وصل شدن و نوشتن کد است؛ قیمت تومانی هر مدل Claude، حداقل شارژ و راه ساختن کلید در صفحهٔ API کلود (Claude) با پرداخت تومانی آمده است.

مدل‌های Claude و تفاوتشان

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

یک نکتهٔ فنی که در نمونه‌کدها به کارتان می‌آید: مدل‌های Claude روی درگاه نِت اَرز از مسیر OpenRouter عبور می‌کنند، برای همین شناسهٔ هر کدام با openrouter/anthropic/ شروع می‌شود. همین رشته را عیناً در فیلد model بگذارید؛ بقیهٔ کد فرقی نمی‌کند.

اگر یک توصیه بخواهید: با Sonnet شروع کنید. برای اکثر پروژه‌ها نسبت کیفیت به قیمت آن بهترین است و اگر بخشی از کار سبک‌تر بود، همان بخش را به Haiku بسپارید. Opus را برای جایی نگه دارید که واقعاً فرق می‌کند؛ مثلاً بازبینی معماری یا تحلیل قراردادهای چندصدصفحه‌ای.

چرا API کلود از ایران سخت است و راه‌حل چیست

Anthropic فهرست کشورهای پشتیبانی‌شده دارد و ایران در آن نیست؛ ثبت‌نام به شمارهٔ تلفن خارجی و پرداخت به کارت بین‌المللی وابسته است و فراخوانی از IP ایرانی رد می‌شود. راه‌حل، استفاده از یک درگاه است: API هوش مصنوعی نِت اَرز با استاندارد OpenAI سازگار است، درخواست شما را از مسیر OpenRouter به مدل‌های Anthropic می‌رساند و پاسخ را با همان قالب برمی‌گرداند. شما اعتبار را به تومان می‌خرید (از ۱۰۰ هزار تومان به‌علاوهٔ ۹ درصد مالیات)، کلیدی با پیشوند sk-ntz-v1- می‌گیرید و از داخل ایران، بدون تغییر IP، به Claude وصل می‌شوید. پرامپت‌ها و پاسخ‌ها در نِت اَرز ذخیره نمی‌شوند و درخواست ناموفق هزینه‌ای ندارد.

اتصال با OpenAI SDK؛ بدون نیاز به کتابخانهٔ Anthropic

نکتهٔ مهم: لازم نیست SDK مخصوص Anthropic نصب کنید. درگاه، قالب OpenAI را می‌پذیرد و خودش به قالب Anthropic ترجمه می‌کند؛ یعنی همان کدی که برای GPT نوشته‌اید، با تغییر نام مدل برای Claude هم کار می‌کند. یک توصیهٔ عملی: برای مدل‌های Claude همیشه max_tokens را صریح تعیین کنید، چون این مدل‌ها به سقف خروجی مشخص عادت دارند و با یک عدد منطقی هم هزینه و هم زمان پاسخ قابل پیش‌بینی‌تر می‌شود.

from openai import OpenAI

client = OpenAI(
    base_url="https://netarz.ir/api/ai/v1",
    api_key="sk-ntz-v1-...",
)

response = client.chat.completions.create(
    model="openrouter/anthropic/claude-sonnet-4.5",
    max_tokens=800,
    messages=[
        {"role": "system", "content": "You are a senior Python reviewer. Reply in Persian, be concrete."},
        {"role": "user", "content": "این تابع را بازبینی کن و مشکلاتش را فهرست کن:\n\ndef total(items):\n    s = 0\n    for i in items: s += i['price'] * i.get('qty')\n    return s"},
    ],
)

print(response.choices[0].message.content)

خروجی استریم برای رابط‌های چت که باید کلمه‌به‌کلمه پاسخ را نشان دهند:

stream = client.chat.completions.create(
    model="openrouter/anthropic/claude-haiku-4.5",
    max_tokens=500,
    stream=True,
    messages=[{"role": "user", "content": "دو پاراگراف دربارهٔ اهمیت تست‌نویسی بنویس."}],
)

for chunk in stream:
    piece = chunk.choices[0].delta.content
    if piece:
        print(piece, end="", flush=True)

و همان کار در Node.js:

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://netarz.ir/api/ai/v1",
  apiKey: process.env.NETARZ_AI_KEY,
});

const stream = await client.chat.completions.create({
  model: "openrouter/anthropic/claude-sonnet-4.5",
  max_tokens: 600,
  stream: true,
  messages: [{ role: "user", content: "یک تابع TypeScript برای اعتبارسنجی کد ملی ایران بنویس." }],
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0].delta.content ?? "");
}

برای PHP، Go، Java یا هر زبان دیگر هم همین الگو برقرار است: کتابخانهٔ OpenAI همان زبان را نصب کنید و آدرس پایه را عوض کنید. جزئیات مسیرها و پارامترهایی که برای Claude پشتیبانی می‌شود در مستندات فنی آمده است.

مهاجرت از SDK رسمی Anthropic

اگر قبلاً با کتابخانهٔ رسمی Anthropic کد زده‌اید، نگاشت پارامترها ساده است. پارامتر system که در Messages API جداگانه داده می‌شد، این‌جا به یک پیام با نقش system در ابتدای فهرست پیام‌ها تبدیل می‌شود. max_tokens همان است و همچنان توصیه می‌کنیم صریح بنویسید. stop_sequences به stop تغییر نام می‌دهد، temperature بدون تغییر منتقل می‌شود و ابزارها با همان قالب tools و tool_choice استاندارد OpenAI تعریف می‌شوند؛ پاسخ فراخوانی ابزار هم در tool_calls برمی‌گردد. ورودی تصویر با بخش image_url فرستاده می‌شود و درگاه آن را به قالب Anthropic تبدیل می‌کند. اگر پارامتری پشتیبانی نشود، خطای شفاف با پیام فارسی می‌گیرید و چون درخواست ناموفق هزینه ندارد، آزمایش کردن ضرری ندارد. فهرست دقیق پارامترهای پشتیبانی‌شده برای هر ارائه‌دهنده در مستندات فنی نگه‌داری می‌شود.

چک‌لیست کوتاه مهاجرت:

• کلاینت Anthropic را با کلاینت OpenAI و base_url نِت اَرز جایگزین کنید.
• پیام سیستم را به ابتدای آرایهٔ messages منتقل کنید.
• نام مدل را به شناسهٔ فهرست نِت اَرز (مثلاً openrouter/anthropic/claude-sonnet-4.5) تغییر دهید و از متغیر محیطی بخوانید.
• خواندن پاسخ را از content[0].text به choices[0].message.content تغییر دهید.
• بیست پرامپت واقعی را از هر دو مسیر بفرستید و خروجی و تعداد توکن را مقایسه کنید.

نکات پرامپت‌نویسی مخصوص Claude

• پیام سیستم را جدی بگیرید: Claude به نقش و قواعدی که در پیام سیستم می‌نویسید وفادار می‌ماند؛ لحن، زبان پاسخ و کارهایی که نباید بکند را همان‌جا مشخص کنید.
• از برچسب‌های XML استفاده کنید: وقتی چند بخش متفاوت به مدل می‌دهید (سند، سؤال، نمونه)، هر بخش را داخل برچسبی مثل <document> بگذارید. Claude با این ساختار بهتر از هر مدل دیگری کار می‌کند.
• سند را بالا، سؤال را پایین: در پرامپت‌های طولانی، متن مرجع را اول بیاورید و دستور را در انتها؛ دقت پاسخ محسوس بهتر می‌شود.
• نمونه بدهید: یک یا دو مثال از خروجی مطلوب، بیشتر از ده خط توضیح اثر دارد.
• خروجی ساخت‌یافته بخواهید: اگر قرار است پاسخ را در کد پردازش کنید، قالب JSON را دقیق مشخص کنید و بگویید «فقط JSON، بدون توضیح».

اصول عمومی را در راهنمای پرامپت‌نویسی نوشته‌ایم؛ همهٔ آن‌ها برای Claude هم معتبر است.

کاربردهایی که Claude در آن‌ها می‌درخشد

سه دسته کار هست که در تجربهٔ ما تیم‌ها بعد از یک هفته تست، از Claude برنمی‌گردند. اول، بازبینی و بازنویسی کد: به مدل کل فایل یا حتی چند فایل را بدهید و پیشنهاد اصلاح بخواهید؛ زمینهٔ بزرگ Sonnet یعنی یک پروژهٔ متوسط را یک‌جا می‌بیند. دوم، پرسش و پاسخ روی اسناد طولانی: قرارداد، آیین‌نامه، دفترچهٔ فنی؛ متن را با برچسب XML بفرستید و سؤال بپرسید. سوم، ویرایش و تولید متن فارسی با لحن کنترل‌شده؛ Claude در پیروی از سبک و نگه داشتن لحن در متن‌های بلند، نتایج یکدست‌تری می‌دهد. برای کارهایی مثل تولید تصویر یا جستجوی زنده، Claude انتخاب نیست و باید سراغ مدل‌های دیگر پشت همان کلید بروید.

برآورد هزینه با یک مثال

فرض کنید یک ربات بازبینی کد برای تیم می‌سازید که روزانه حدود ۵۰ درخواست می‌گیرد؛ هر درخواست حدود ۶ هزار توکن ورودی (کد به‌علاوهٔ دستور) و ۱٬۵۰۰ توکن خروجی. مصرف روزانه می‌شود ۳۰۰ هزار توکن ورودی و ۷۵ هزار توکن خروجی؛ ماهانه حدود ۹ میلیون ورودی و ۲٫۲۵ میلیون خروجی. با نرخ رسمی Sonnet، هزینه تقریباً ۹ × ۳ به‌علاوهٔ ۲٫۲۵ × ۱۵ یعنی حدود ۶۱ دلار در ماه می‌شود و با Haiku حدود ۲۰ دلار. این اعداد نرخ رسمی Anthropic است و قیمت تومانی نِت اَرز که هزینهٔ تأمین را هم شامل می‌شود، در صفحهٔ مدل‌ها لحظه‌ای درج شده. روش دقیق محاسبه را در توکن چیست و هزینهٔ API چطور حساب می‌شود بخوانید.

دو راه برای کم کردن این عدد: اول، دستور سیستمی طولانی را کوتاه کنید و کد اضافی نفرستید؛ ورودی بیشترین سهم را دارد. دوم، کارهای ساده (مثلاً تشخیص اینکه یک تغییر اصلاً نیاز به بازبینی دارد یا نه) را به Haiku بدهید و فقط بازبینی واقعی را با Sonnet انجام دهید.

Claude Pro یا API کلود؟

اگر خودتان هر روز با Claude کار می‌کنید و رابط چت، پروژه‌ها و Claude Code را می‌خواهید، اشتراک همچنان ارزان‌تر و راحت‌تر است؛ خرید Claude Pro از ایران و تفاوت Pro و Max را ببینید. اما اگر Claude قرار است داخل محصول شما بنشیند یا اسکریپت‌هایتان آن را صدا بزنند، API تنها راه درست است. برای مقایسهٔ Claude با رقیب اصلی‌اش هم Claude یا ChatGPT را نوشته‌ایم. هر دو مسیر در نِت اَرز باز است: اشتراک‌ها در دستهٔ اکانت هوش مصنوعی و API در صفحهٔ API هوش مصنوعی.