آموزش OpenAI API

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

API چیست؟

پیش از ورود به بحث اصلی، بهتر است مفهوم API (Application Programming Interface) را به زبان ساده مرور کنیم. دیاگرام زیر این فرآیند را به خوبی نشان می‌دهد:

شکل بالا را می‌توان به سه بخش تقسیم کرد:

• کاربر (USER): در سمت چپ، کاربر (مثلا، یک مرورگر وب) قرار دارد که یک درخواست ارسال می‌کند.
• واسط (API): API به عنوان یک واسط عمل می‌کند. این واسط درخواست کاربر را دریافت کرده، قوانین تعامل را تنظیم و انتقال داده را مدیریت می‌کند.
• سرور (SERVER): در سمت راست، سرورها و مدل‌های OpenAI قرار دارند.

مدل‌های OpenAI «بسته و پولی» (Closed-source and Paid) هستند و ما دسترسی مستقیم برای دانلود آن‌ها (مثلا از Hugging Face) نداریم. API واسطی است که به ما اجازه می‌دهد بدون دسترسی مستقیم به مدل‌ها، از آن‌ها استفاده کنیم.

پس به‌صورت خلاصه این شد که، ما یک «پرامپت» یا درخواست را به همراه نام مدل به API می‌دهیم. درخواست به سرورهای OpenAI ارسال شده، مدل آن را پردازش می‌کند و خروجی را تولید می‌نماید. این خروجی دوباره به API بازگشته و در نهایت به ما نمایش داده می‌شود.

با این مقدمه کوتاه از “API چیست؟”، می‌توانیم وارد بحث اصلی خودمان، یعنی OpenAI API شویم…

پلتفرم OpenAI API

برای ورود به پلتفرم OpenAI برای استفاده از API، ابتدا به وب‌سایت openai.com مراجعه کنید. در این سایت، بخشی به نام For Developers (برای توسعه‌دهندگان) وجود دارد که مقصد ما است. پس از ورود به این بخش و لاگین کردن به حساب کاربری خود ، وارد پلتفرم OpenAI می‌شوید. این پلتفرم دارای مستندات (Documentation) بسیار جامعی است که مطالعه آن توصیه می‌شود.

هزینه و شارژ حساب (Billing) استفاده از API OpenAI رایگان نیست و هزینه دارد. برای استفاده از مدل‌ها، باید حساب خود را شارژ کنید. برای این کار مراحل زیر را انجام دهید:

• وارد بخش Billing (صورت‌حساب) شوید.
• در این بخش می‌توانید اعتبار (Credit) فعلی خود را مشاهده کنید. در برخی موارد، OpenAI مقداری اعتبار هدیه یا Grant نیز به کاربران جدید می‌دهد.
• برای شارژ حساب، می‌توانید از گزینه‌های افزودن اعتبار استفاده کنید. (برای کاربرانی که داخل ایران هستند، استفاده از سرویس‌های واسط مانند «ایرانی کارت» یکی از راه‌های موجود برای پرداخت ارزی و شارژ حساب است).

توجه: مصرف شارژ با OpenAI API زیاد نیست، حتی شارژ حساب به میزان کم (مثلا، ۵ دلار یا حتی کمتر) هم امکان‌پذیر هست. پیشنهاد می‌کنیم این کار را انجام دهید، برای کسب تجربه و یادگیری عملی خوب است.

ساخت کلید OpenAI API Key

برای ارسال درخواست به مدل (Call)، ابتدا به یک کلید API یا API Key نیاز دارید. برای ساخت کلید API مراحل زیر را طی کنید:

• در داشبورد پلتفرم، از منوی Get Started وارد بخش Quickstart شوید.
• در این بخش، گزینه Create an API Key را انتخاب کنید.
• با کلیک روی این گزینه، به بخش API Keys در تنظیمات اکانت خود هدایت می‌شوید.
• روی دکمه Create new secret key کلیک کنید.
• یک نام دلخواه برای کلید خود انتخاب کنید. می‌توانید سطح دسترسی (Permissions) کلید را نیز محدود کنید، اما برای شروع می‌توان از دسترسی کامل استفاده کرد.

نکته مهم: کلید API شما بسیار مهم و محرمانه است. پس از ساخت، آن را کپی کرده و در مکانی امن نگهداری کنید. این کلید نباید در اختیار دیگران قرار گیرد یا به صورت آشکار (hard-code) در کدهای شما نوشته شود.

توصیه می‌شود برای پروژه‌های مختلف، کلیدهای مجزا بسازید و پس از اتمام کار، کلیدهای غیرضروری را حذف کنید تا مدیریت آن‌ها از کنترل خارج نشود.

مدیریت امن API Key

همانطور که اشاره شد، کلید API نباید مستقیما در کد نوشته شود. دو روش امن برای مدیریت آن وجود دارد:

• استفاده از متغیرهای محیطی (Environment Variables): این روش استاندارد ذخیره کردن کلید در متغیرهای محیطی سیستم‌عامل است. کتابخانه OpenAI به صورت خودکار به دنبال متغیری با نام OPENAI_API_KEY می‌گردد. مثلا، در سیستم عامل ویندوز می‌توانید از دستور setx در CMD استفاده کنید:

setx OPENAI_API_KEY='your-key-here'

البته، یک راه دیگری برای تعریف Environment Variables در ویندوز وجود دارد؛ با جستجوی “environment variables” در منوی استارت، به صورت گرافیکی متغیر OPENAI_API_KEY را با مقدار کلید خود ایجاد نمایید.

• استفاده در گوگل کولب (Google Colab): اگر از گوگل کولب استفاده می‌کنید، می‌توانید از قابلیت Secrets بهره ببرید؛ در نوت‌بوک کولب، روی آیکون 🔑 (Secrets) در نوار کناری کلیک کنید. یک Secret جدید با نام دلخواه (مثلا OPENAI_API) بسازید و مقدار (Value) آن را برابر با کلید API خود قرار دهید. سپس در کد، می‌توانید به شکل زیر به آن دسترسی پیدا کنید:

from google.colab import userdata
# 'OPENAI_API' نامی است که در بخش Secrets گذاشتید
api_key = userdata.get('OPENAI_API')

این روش باعث می‌شود کلید شما مخفی بماند و در خروجی یا کد نوت‌بوک نمایش داده نشود.

نصب کتابخانه OpenAI

پس از تنظیم کلید API، باید کتابخانه رسمی openai را نصب کنید:

!pip install -U openai

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

توجه: پس از نصب یا آپدیت، بهتر است Runtime (محیط اجرایی) خود را یک بار Restart کنید تا از بروز خطاهای احتمالی جلوگیری شود.

ارسال درخواست به OpenAI API یا OpenAI API Call

اکنون همه‌چیز برای ارسال اولین درخواست آماده است. اولین گام، ایجاد کلاینت (Client) است. ابتدا کلاس OpenAI را از کتابخانه import کرده و یک کلاینت از آن می‌سازیم:

from openai import OpenAI
from google.colab import userdata 

client = OpenAI(api_key=userdata.get('OPENAI_API'))

توجه: اگر کلید API را نه به صورت متغیر محیطی و نه به صورت آرگومان api_key تعریف کرده باشید، کد در این مرحله با خطای OpenAIError مواجه خواهد شد. استفاده از userdata.get (در کولب) یا متغیرهای محیطی، از نوشتن مستقیم کلید در کد جلوگیری کرده و امنیت را حفظ می‌کند.

انواع مدل در OpenAI

پیش از ارسال درخواست، باید بدانیم از کدام مدل می‌خواهیم استفاده کنیم. OpenAI طیف گسترده‌ای از مدل‌ها را ارائه می‌دهد؛ مانند سری GPT-5، نسخه‌های Mini Nano، مدل‌های تصویری، صوتی و مجموعه زیادی مدل دیگر. با مراجعه به بخش Models در مستندات، می‌توان جزئیات هر مدل را بررسی کرد. برای مثال، بیایید مدل GPT-5 Nano را بررسی کنیم:

• قابلیت‌ها: سریع‌ترین و به‌صرفه‌ترین نسخه GPT-5 است. سرعت بسیار بالا و قدرت استدلال (Reasoning) متوسطی دارد.
• ورودی/خروجی: متن و تصویر به عنوان ورودی می‌پذیرد، اما خروجی آن فقط متن است.
• قیمت‌گذاری: (Pricing) هزینه بر اساس تعداد توکن‌های ورودی (Input) و خروجی (Output) محاسبه می‌شود. معمولا، هزینه توکن‌های خروجی گران‌تر است.
• Context Window: حداکثر توکن ورودی (مثلا، ۴۰۰ هزار) و خروجی (مثلا، ۱۲۸ هزار) را مشخص می‌کند.

با توجه به اینکه، این مدل هم جدید هست و هم ارزان، می‌توانیم برای کار آموزشی و یادگیری از این مدل استفاده کنیم.

اندپوینت (Endpoints)

حالا که مدل را انتخاب کردیم، باید با اندپوینت آشنا شوید. اندپوینت‌ها بخش‌های مختلف API هستند که هرکدام وظیفه خاصی دارند. مهم‌ترین اندپوینت‌های فعلی عبارتند از:

• Chat Completions: برای ساخت چت مانند تجربه ChatGPT
• Responses: اندپوینت جدید و قدرتمندی که امکانات زیادی مانند تولید متن، تحلیل تصویر و ایجاد چت را فراهم می‌کند OpenAI اعلام کرده که در آینده تمرکز بیشتری روی این اندپوینت خواهد داشت.
• Fine-tune: برای آموزش (Train) مدل بر اساس داده‌های شخصی.
• و موارد دیگر مانند Audio ،Video و Moderation.

کلاینتی که ساختیم (client)، به تمام این اندپوینت‌ها به عنوان ماژول دسترسی دارد. ما در این راهنما از اندپوینت جدید responses استفاده می‌کنیم.

اندپوینت Responses در OpenAI API

client.responses به ماژول responses دسترسی می‌دهد. حالا به کمک ()create یک درخواست جدید ایجاد می‌کند. بنابراین، با استفاده از ()client.responses.create می‌توانیم اولین درخواست خود را ارسال کنیم. این متد به دو آرگومان اصلی نیاز دارد:

• Model: نام دقیق مدلی که می‌خواهیم استفاده کنیم (این نام از مستندات کپی می‌شود).
• input: پرامپت یا متنی که به عنوان ورودی به مدل می‌دهیم.

به عنوان نمونه:

response = client.responses.create(
    model="gpt-5-nano-2025-08-07"  
    input="یک داستان کوتاه برای کودک ۳ تا ۵ ساله بگو."  
)

نکته: اجرای این کد ممکن است چند ثانیه طول بکشد؛ زیرا درخواست باید از طریق اینترنت به سرورهای OpenAI ارسال، پردازش و بازگردانده شود. این فرآیند از سخت‌افزار محلی مانند GPU کولب استفاده نمی‌کند.

چگونه به خروجی مدل را ببینیم؟ متغیر response حاوی اطلاعات زیادی است. برای دسترسی به متن تمیز خروجی، از output_text استفاده می‌کنیم:

print(response.output_text)

و این هم خروجی کار:

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

امکانات پیشرفته responses API

اندپوینت responses قابلیت‌های بسیار پیشرفته‌تری نیز دارد که در API Reference (مستندات) قابل مشاهده‌اند:

• instructions: برای دادن دستورالعمل‌های سیستمی به مدل.
• max_tokens: برای محدود کردن حداکثر تعداد توکن‌های خروجی.
• Image Input: امکان ارسال تصویر به عنوان ورودی.
• File Input: امکان ارسال فایل مانند PDF به عنوان ورودی.
• Web Search: استفاده از ابزار جستجوی وب.
• Streaming: دریافت خروجی به صورت توکن-به-توکن مانند ChatGPT به جای دریافت یکباره.
• Function Calling: فراخوانی توابعی که شما در کد خود تعریف کرده‌اید.

ایجاد مکالمه با حافظه (Conversation)

یکی از قابلیت‌های کلیدی, responses ایجاد مکالمه با قابلیت حفظ تاریخچه (حافظه) است. در حالت بدون حافظه (مشکل)، اگر دو سوال مرتبط را در دو درخواست جداگانه بپرسیم، مدل سوال دوم را متوجه نمی‌شود:

res1 = client.responses.create(
    model="gpt-5-nano-2025-08-07"
    input="پایتخت ایران کجاست؟"
)
print(res1.output_text )

خروجی:

پایتخت ایران تهران است. تهران بزرگ‌ترین شهر ایران و مرکز سیاسی، اقتصادی و فرهنگی کشور نیز هست. دوست دارید دربارهٔ تهران اطلاعات بیشتری بخواهید؟

res2 = client.responses.create(
    model="gpt-5-nano-2025-08-07"
    input="و جمعیتش چقدره؟"
)
print(res2.output_text)

همان‌طور که مشخص است، مدل در res2 ارتباطی با res1 برقرار نکرده است:

جمعیت شهر تهران تقریباً 9 میلیون نفر است. اگر منظور کلان‌شهر تهران باشد (شامل حومه‌ها)، عدد معمول حدود 14 تا 15 میلیون نفر است که با تعریف‌های مختلف می‌تواند فرق کند. دوست دارید من منابع یا بازه سالی دقیق‌تری بدهَم؟

اما در حالت با حافظه، برای اتصال این دو گفتگو، از آرگومان previous_response_id و ارسال id پاسخ قبلی (res1.id) استفاده می‌کنیم:

res2_with_memory = client.responses.create(
    model="gpt-5-nano-2025-08-07"
    input="و جمعیتش چقدره؟"
    previous_response_id=res1.id # اتصال به پاسخ قبلی 
)
print(res2_with_memory.output_text)

این بار خروجی صحیح خواهد بود:

جمعیت شهر تهران (داخل محدوده شهرداری): حدود ۹ تا ۹.۵ میلیون نفر..." مدل به درستی متوجه شد که منظور از «جمعیتش» جمعیت تهران بوده است.

استفاده از ابزارها (Tools): جستجوی وب با OpenAI API

یکی از جذاب‌ترین قابلیت‌ها، استفاده از ابزارها (Tools) مانند جستجوی وب (web_search) است. با افزودن آرگومان tools، به مدل اجازه می‌دهیم برای پاسخ به سوالاتی که دانش آن را ندارد، در اینترنت جستجو کند.

response = client.responses.create(
  model="gpt-5-nano-2025-08-07" 
    tools=[{"type": "web_search"}] # فعال کردن ابزار وب سرچ 
    input="خلاصه‌ای از آخرین مصاحبه آندره کارپاتی رو بگو"
)
print(response.output_text)

مدل با جستجو در اینترنت، خلاصه‌ای از مصاحبه مورد نظر را ارائه می‌دهد؛ برای مثال، اطلاعاتی درباره تاریخ مصاحبه و مباحث مطرح شده مانند فاصله یک دهه‌ای تا AGI و نام‌گذاری ۲۰۲۵ به عنوان «دهه ایجنت‌ها» را برمی‌گرداند. این اطلاعات در دانش پایه مدل که با آن Train شده، وجود نداشته و به صورت زنده از وب استخراج شده است.

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

نویسنده: آیدا آقائی نیا