در این فصل چه یاد میگیری#
فصلِ قبل فهمیدی API یک در است. حالا میخواهی ببینی از این در دقیقاً چه چیزی رد میشود: وقتی برنامهای مدل را صدا میزند، چه میفرستد و چه پس میگیرد. جوابِ مدل از درِ API یک پنجرهٔ زیبا نیست؛ یک متنِ ساختیافته است که برنامه باید بلد باشد بخواندش. این فصل هنوز کدِ اجراشدنی ندارد — فقط شکلِ رفتوبرگشت را با یک مثالِ ملموس میبینی، تا فصلِ بعد که واقعاً از JavaScript صدایش میزنی، غافلگیر نشوی.

آخر این فصل میتوانی:
- ساختارِ یک درخواستِ
APIرا بخوانی: چه چیزی داخلِ بدنه میرود - پاسخِ خامِ مدل را بشناسی و بفهمی چرا تودرتوست
- متنِ جواب را از مسیرِ
candidates[0].content.parts[0].textبیرون بکشی - بگویی ردهٔ رایگانِ Gemini چه محدودیتهایی دارد و چرا با کلیدِ خودت کار میکنی
قبل از شروع#
- از فصل ۱ همین ترم:
API،API key، و اینکه کلید مالِ خودت است (BYOK). - از تاروپود (ترم ۷، فصل ۸):
JSON— قالبِ متنیِ داده که به مقدار، آرایه و شیء تبدیل میشود و با نقطه و شماره خوانده میشود. اگر تاروپود را نگذراندهای، همینقدر بدان کهJSONیعنی «دادهای که مثلِ جعبههای تودرتو ساختیافته است».
۱. یک فراخوانی از دور چه شکلی است#
هر فراخوانیِ API سه تکه دارد: کجا میفرستی، چه میفرستی، و چه برمیگردد.
«کجا» یک آدرسِ اینترنتی است بهاسمِ endpoint — درست مثلِ آدرسِ یک صفحهٔ وب، ولی بهجای صفحه، داده پس میدهد. endpointِ Gemini آدرسِ مدل است، و کلیدِ تو هم همراهِ همین درخواست میرود تا سرویس بداند چه کسی صدا زده.
«چه میفرستی» یک بدنهٔ درخواست است، نوشتهشده به JSON. «چه برمیگردد» هم یک JSONِ دیگر است: پاسخِ خام. کلِ کاری که برنامهات میکند این است: بدنه را درست بساز، بفرست، و از پاسخِ خام متنِ جواب را بیرون بکش. بیا هر دو تکه را با یک مثالِ واقعی ببینیم.
۲. بدنهٔ درخواست: promptِ تو، بستهبندیشده#
فرض کن میخواهی بپرسی «پایتختِ ژاپن کجاست؟». در درِ chat فقط تایپش میکردی. در درِ API باید همان جمله را در یک ساختارِ مشخص بگذاری تا سرویس بفهمدش. سادهترین بدنهٔ ممکن این است:
{
"contents": [
{ "parts": [{ "text": "پایتختِ ژاپن کجاست؟" }] }
]
}
از بیرون به داخل بخوانش: contents فهرستِ چیزهایی است که میفرستی؛ هر تکه parts دارد؛ و هر part یک text دارد که همان promptِ توست. چرا اینقدر تودرتو؟ چون همین ساختار بعداً جا دارد برای چیزهای بیشتر — چند پیامِ پشتِهم، یا حتی یک تصویر کنارِ متن. فعلاً فقط یک text داریم و همین کافی است.
نکته این است که promptِ تو گم نشده؛ فقط لای چند لایه بستهبندی شده تا برنامه بتواند دقیق بگوید کجای پیام کدام است.
۳. پاسخِ خام: جواب کجا پنهان است#
سرویس جواب را هم به همان سبکِ تودرتو برمیگرداند. هستهٔ پاسخِ خام این است:
{
"candidates": [
{
"content": {
"parts": [
{ "text": "پایتختِ ژاپن، توکیو است." }
]
}
}
]
}
متنی که میخواهی — «پایتختِ ژاپن، توکیو است.» — همان تهِ این جعبههای تودرتوست. چرا مدل جواب را اینقدر بستهبندی میکند؟ چون candidates یعنی «نامزدهای جواب»: مدل میتواند بیش از یک جوابِ ممکن برگرداند، پس آنها را در یک فهرست میگذارد. جوابِ اول نامزدِ شمارهٔ صفر است.
برای رسیدن به متن، لایهبهلایه پایین میروی: اولین نامزد، بعد contentِ آن، بعد partsِ آن، بعد اولین part، بعد textِ آن. در کدِ فصلِ بعد این مسیر دقیقاً اینطور نوشته میشود:
candidates[0].content.parts[0].text
این تنها تکهای است که این فصل باید در ذهنت بماند: مسیرِ رسیدن به جوابِ واقعی. [0] یعنی «اولی» — همانطور که در تاروپود آرایهها را با شماره میخواندی، اینجا هم اولین عضو شمارهٔ صفر است.
قبل از ادامه، جواب بده: اگر بخواهی متنِ جواب را در برنامهات نشان بدهی، از کدام مسیرِ داخلِ پاسخِ خام باید بخوانیاش؟
۴. ردهٔ رایگانِ Gemini: چه میگیری، چه نمیگیری#
سرویسی که استفاده میکنیم یک ردهٔ رایگان دارد که برای یاد گرفتن و ساختنِ یک ابزارِ شخصی کافی است. ولی رایگان یعنی چند مرز:
- سقفِ تعداد. در هر دقیقه و هر روز فقط تا تعدادِ مشخصی میتوانی صدا بزنی. عددش عوض میشود، پس در متن نمینویسمش؛ در جدولِ زیر برچسبِ «در زمان خواندن چک شود» دارد.
- کیفیتِ ردهٔ سبک، نه بهترین مدلِ روز. ردهٔ رایگان معمولاً مدلهای سبکتر و سریعترِ سرویس را میدهد، نه قویترینهایش. کیفیتِ فارسیاش خوب است، ولی نه در حدِ بهترین مدلهای پولی. اسمِ دقیقِ این مدلها را اینجا نمینویسم چون مدام عوض میشود؛ در جدولِ زیر جایش را میگویم. فعلاً فقط انتظارت را واقعی بگذار.
- دادهٔ تو ممکن است برای آموزش برود و شرطِ استفادهٔ تجاری را باید در قراردادِ همان سرویس بخوانی. این دقیقاً همان دلیلی است که فصلِ ۱ گفت: کلید مالِ خودِ کاربر است، و دادهٔ خصوصی را به ردهٔ رایگان نده.
| چیزی که عوض میشود | کجا چکش کنی |
|---|---|
| سقفِ تعدادِ درخواست در دقیقه/روز | مستنداتِ رسمیِ Gemini API — در زمان خواندن چک شود |
| کدام مدلها در ردهٔ رایگاناند | مستنداتِ رسمیِ Gemini API — در زمان خواندن چک شود |
۵. جوابِ خام هم میتواند مطمئن ولی غلط باشد#
مهمترین درسِ کلِ دوره اینجا هم صادق است: اینکه جواب از API و در قالبِ تمیزِ JSON میآید، ذرهای درستترش نمیکند. API فقط لولهٔ انتقال است؛ همان مدلِ ممکنالخطای همیشگی آنطرفِ لوله نشسته.
بیا یک مثالِ واقعی و قابلِامتحان را با هم ببینیم. این را بهعنوانِ text در request بگذار و بفرست:
حاصلِ ۲۳۴۷ × ۸۹۶۱ چند است؟ فقط عدد را بگو.
جوابی که در candidates[0].content.parts[0].text مینشیند ممکن است چیزی شبیهِ این باشد. این یک نمونه است و عددِ تو ممکن است فرق کند:
۲۰۹۹۹۶۷۱
در این نمونه قالب تمیز و لحن مطمئن است، و عدد غلط است. جوابِ درست ۲۱۰۳۱۴۶۷ است. مدل یک عددِ درستنما ساخت، نه یک محاسبهٔ درست؛ و API هم بیسروصدا همان را در یک JSONِ بیعیب تحویلت داد.
بهترین کاری که میتوانی همینجا بکنی این است: همان request را سه بار پشتِسرِهم بفرست. یک ماشینحساب هر سه بار یک عدد میدهد. مدل ممکن است چند عددِ نزدیک ولی متفاوت بدهد. مدلِ تو شاید هر سه بار درست بزند؛ آن هم چیزی را ثابت نمیکند، چون روی کاغذ معلوم نیست این بار کجا غلط میزند. اگر داری برنامهای مینویسی که رویِ این عدد حساب میکند، همینجا فهمیدی که نباید.
✅ وارسی: این را با خودِ مدل «تأیید» نکن — که اگر بپرسی «مطمئنی؟» شاید باز هم اشتباهش را با اطمینان تکرار کند. خودت یک قدمِ مستقل بردار: همان ضرب را در ماشینحساب بزن. سه قانونِ ثابتِ این دوره دقیقاً برای همین لحظهاند: «اول خودت فکر کن» — «وارسی کن، خط به خط» — «مدل مطمئن است؛ دلیل نمیشود درست باشد». قالبِ مرتبِ
JSONهیچ تضمینی برای درستیِ محتوا نیست.
💡 نکته: آن «فقط عدد را بگو» عمدی است و خودش یک درسِ مهندسی دارد. اگر همین ضرب را بدونِ آن قید بفرستی، مدل معمولاً ضرب را ستونبهستون مینویسد و اغلب به جوابِ درست میرسد. یعنی خروجیِ کوتاهتر و تمیزتر — که در کد همیشه راحتتر است — میتواند دقیقاً همان چیزی باشد که دقت را پایین میآورد. این بدهبستان را در طراحیِ هر برنامهای یادت باشد، و برای هر حسابی که واقعاً مهم است، خودِ کدت حساب کند نه مدل.
واژههای تازهٔ این فصل#
| کلمه | تلفظ به حروف فارسی | یعنی چه |
|---|---|---|
| endpoint | اِندپوینت | آدرسِ اینترنتیِ سرویس که بهجای صفحه، داده پس میدهد |
| request / response | ریکوئست / رِسپانس | آنچه برنامه میفرستد / آنچه سرویس برمیگرداند |
| candidates | کَندیدِیتس | فهرستِ نامزدهای جواب در پاسخِ خام؛ اولی شمارهٔ صفر است |
تمرینها
اول خودت فکر کن یا امتحان کن — بعد اینجا را باز کن.
در فصل بعد#
حالا شکلِ کاملِ یک فراخوانی را میشناسی: بدنه را میسازی، میفرستی، و متن را از مسیرِ candidates[0].content.parts[0].text بیرون میکشی. فصلِ بعد این را برای اولین بار زنده میکنیم: با fetch (که از تاروپود قرض میگیریم) همین درخواست را از JavaScript میفرستیم و جواب را روی یک صفحهٔ واقعی نشان میدهیم — و کلید را طبقِ BYOK از یک کادرِ ورودی میخوانیم، نه از کد.
به آخر این فصل رسیدی!
اگر ساختی و جواب داد، این دکمه مال توست.