آموزش Claude API: از نصب SDK تا اولین درخواست و مکالمه چندمرحله‌ای

آموزش Claude API را می‌توان در یک جمله خلاصه کرد: یک کلید می‌گیرید، SDK رسمی را نصب می‌کنید و با چند خط کد به مدل‌های Claude از شرکت Anthropic پیام می‌فرستید. در این راهنما قدم‌به‌قدم می‌بینیم اولین درخواست چطور نوشته می‌شود، مکالمه چندمرحله‌ای چطور ساخته می‌شود، پیام سیستم کجا قرار می‌گیرد و چه نکته‌هایی را باید از ابتدا بدانید. مطالب بر پایه مستندات رسمی Anthropic نوشته شده‌اند.

پیش‌نیازها برای شروع کار با Claude API

طبق مستندات رسمی، برای اولین درخواست به دو چیز نیاز دارید: یک حساب در کنسول Claude و یک کلید API. کلید را مثل رمز عبور نگه دارید و داخل کد یا مخزن Git قرار ندهید. بهتر است آن را در متغیر محیطی ذخیره کنید؛ SDK رسمی به‌صورت پیش‌فرض متغیر ANTHROPIC_API_KEY را می‌خواند.

اگر دسترسی مستقیم به حساب و پرداخت بین‌المللی برای شما مشکل است، می‌توانید کلید را از فروشگاه‌هایی مثل الین‌لند با پرداخت ریالی تهیه کنید. فقط توجه کنید که هر سرویس‌دهنده ممکن است راهنمای اتصال مخصوص خودش (مثل آدرس پایه یا Base URL) داشته باشد و باید طبق همان راهنما تنظیم کنید.

نصب SDK و تنظیم کلید

مستندات پیشنهاد می‌کند یک پوشه پروژه و یک محیط مجازی پایتون بسازید و بسته anthropic را نصب کنید:

mkdir claude-quickstart && cd claude-quickstart
python3 -m venv .venv && source .venv/bin/activate
pip install anthropic

export ANTHROPIC_API_KEY="your-api-key-here"

در ویندوز به‌جای export می‌توانید از دستور setx یا تنظیمات متغیرهای محیطی سیستم استفاده کنید.

اولین درخواست به Claude API

ساده‌ترین درخواست از طریق Messages API انجام می‌شود. سه پارامتر اصلی لازم است: نام مدل (model)، سقف توکن خروجی (max_tokens) و فهرست پیام‌ها (messages).

import anthropic

client = anthropic.Anthropic()

message = client.messages.create(
    model="MODEL_NAME",   # نام مدل را از صفحه Models overview بردارید
    max_tokens=1000,
    messages=[
        {"role": "user", "content": "سلام! خودت را در دو جمله معرفی کن."}
    ],
)

for block in message.content:
    if block.type == "text":
        print(block.text)

نام مدل‌ها در طول زمان عوض می‌شود، برای همین در مثال بالا MODEL_NAME گذاشتیم. نام دقیق و به‌روز مدل‌ها را همیشه از صفحه Models overview در مستندات Anthropic بردارید.

ساختار پاسخ را بشناسید

پاسخ API یک شیء پیام است که چند بخش مهم دارد:

• content: فهرستی از بلوک‌ها. متن پاسخ داخل بلوک‌هایی با type برابر text است، برای همین در مثال بالا روی بلوک‌ها حلقه زدیم.
• stop_reason: دلیل پایان پاسخ، مثلاً end_turn وقتی مدل خودش پاسخ را تمام کرده یا max_tokens وقتی به سقف شما رسیده و جواب نیمه‌کاره مانده است.
• usage: تعداد توکن‌های ورودی (input_tokens) و خروجی (output_tokens) همین درخواست. با ثبت این دو عدد می‌توانید هزینه مصرف را زیر نظر داشته باشید.

اگر درباره توکن و محاسبه هزینه سؤال دارید، مقاله توکن و هزینه API هوش مصنوعی در همین بلاگ را ببینید.

مکالمه چندمرحله‌ای: API حافظه ندارد

یکی از نکات مهم مستندات این است که Messages API «بدون حالت» (stateless) است. یعنی سرور چیزی از درخواست قبلی شما به یاد نمی‌آورد و هر بار باید کل تاریخچه گفتگو را دوباره بفرستید. نوبت‌های قبلی را به ترتیب با نقش‌های user و assistant در فهرست messages بگذارید:

history = [
    {"role": "user", "content": "سلام"},
    {"role": "assistant", "content": "سلام! چطور می‌توانم کمک کنم؟"},
    {"role": "user", "content": "مدل‌های زبانی را در یک پاراگراف توضیح بده."},
]

reply = client.messages.create(
    model="MODEL_NAME",
    max_tokens=1000,
    messages=history,
)

نتیجه عملی این ویژگی: هرچه گفتگو طولانی‌تر شود، توکن ورودی هر درخواست بیشتر می‌شود. در چت‌بات‌های واقعی معمولاً تاریخچه قدیمی را خلاصه یا کوتاه می‌کنند.

پیام سیستم برای تعیین نقش و لحن

برای تعیین نقش، لحن و قواعد کلی از فیلد system در سطح بالای درخواست استفاده کنید، نه از داخل فهرست پیام‌ها. دستورهایی که از همان ابتدای گفتگو باید برقرار باشند اینجا جا می‌گیرند:

message = client.messages.create(
    model="MODEL_NAME",
    max_tokens=800,
    system="تو دستیار پشتیبانی یک فروشگاه اینترنتی هستی. کوتاه، مؤدب و به فارسی پاسخ بده.",
    messages=[{"role": "user", "content": "سفارشم را چطور پیگیری کنم؟"}],
)

نوشتن پرامپت‌های بهتر موضوع جداگانه‌ای است که در راهنمای پرامپت نویسی به آن پرداخته‌ایم.

نکات مهم هنگام کار با مدل‌های جدید

• پارامترهای نمونه‌گیری: طبق مستندات، temperature، top_p و top_k روی مدل‌های Claude نسخه 4.7 به بعد پشتیبانی نمی‌شوند و مقدار غیرپیش‌فرض آن‌ها خطای 400 برمی‌گرداند. اگر کد قدیمی دارید که این پارامترها را می‌فرستد، آن‌ها را حذف کنید و رفتار مدل را با پرامپت هدایت کنید.
• Prefill: پر کردن ابتدای پاسخ مدل (prefill) روی مدل‌های 4.6 به بعد خطای 400 می‌دهد. برای کنترل قالب خروجی از خروجی ساختاریافته (Structured Outputs) یا دستور در پیام سیستم استفاده کنید.
• سقف خروجی: همیشه max_tokens را آگاهانه تنظیم کنید و stop_reason را بررسی کنید تا پاسخ نیمه‌کاره را به‌عنوان جواب کامل به کاربر نشان ندهید.
• تصویر: Claude علاوه بر متن، تصویر هم می‌خواند. تصویر را می‌توانید به‌صورت base64، آدرس URL یا فایل آپلودشده بفرستید.

قدم بعدی: ابزارها و خروجی ساختاریافته

بعد از تسلط بر درخواست پایه، مستندات سه مسیر مهم را معرفی می‌کند: استفاده از ابزارها (Tool Use) برای اینکه مدل بتواند سرویس‌ها و APIهای بیرونی را صدا بزند، خروجی ساختاریافته برای دریافت JSON مطابق یک اسکیما و جریانی‌کردن پاسخ (Streaming) برای نمایش تدریجی متن در رابط کاربری. هرکدام صفحه آموزشی جداگانه در مستندات رسمی دارند.

جمع‌بندی

برای شروع با Claude API فقط به کلید، بسته anthropic و یک درخواست messages.create نیاز دارید. به یاد داشته باشید که API حافظه ندارد، نام مدل و پارامترهای پشتیبانی‌شده با نسخه‌ها تغییر می‌کنند و کلید باید همیشه خارج از کد بماند. اگر برای پروژه‌تان کلید API مدل‌های Claude، GPT، Gemini و دیگر مدل‌ها لازم دارید، از فروشگاه الین‌لند با پرداخت ریالی و تحویل فوری تهیه کنید.