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

API هوش مصنوعی دقیقاً چیست؟

API یک درِ ورودی استاندارد برای برنامه‌هاست. شما در کد خود یک درخواست می‌فرستید که در آن پیام کاربر و نام مدل آمده است و در پاسخ، متن تولیدشده را تحویل می‌گیرید. در API هوش مصنوعی هزینه به‌اندازهٔ مصرف حساب می‌شود، نه به‌صورت اشتراک ماهانه. واحد این مصرف «توکن» است؛ تکه‌های کوچک متن که هم پیام شما و هم پاسخ مدل به آن‌ها شکسته می‌شوند.

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

پیش از شروع چه لازم دارید؟

  • پایتون ۳ و کتابخانهٔ رسمی openai که با دستور pip install openai نصب می‌شود.
  • یک حساب در یک سرویس واسط سازگار با OpenAI. در این راهنما از هیبانا استفاده می‌کنیم؛ پرداخت ریالی است و برای شارژ حساب کارت ارزی لازم نیست.
  • یک کلید API که در گام بعد می‌سازیم.

چون این سرویس با ساختار API شرکت OpenAI سازگار است، همان کتابخانه‌ها و همان کدها کار می‌کنند و فقط دو چیز عوض می‌شود: آدرس پایه و کلید.

گام اول؛ ساخت کلید API

پس از ورود به حساب با شمارهٔ موبایل، این مسیر را بروید:

  • از منوی «حساب کاربری» بخش «کلیدهای وب‌سرویس» را باز کنید.
  • روی «کلید جدید» بزنید، یک نام برای کلید انتخاب کنید و دکمهٔ ساخت را بزنید.
  • کلید را همان لحظه کپی کنید و در جای امنی مثل فایل .env نگه دارید.

راهنمای تصویری همین مراحل در صفحهٔ ساخت کلید API آمده است. کلید را هرگز داخل کدی که منتشر می‌کنید ننویسید و آن را با کسی به اشتراک نگذارید. اگر شک کردید که کلید فاش شده، آن را حذف کنید و کلید تازه بسازید.

گام دوم؛ اولین درخواست با پایتون

کد زیر یک پیام کوتاه به مدل GPT-5 nano می‌فرستد، پاسخ را چاپ می‌کند و تعداد توکن‌ها و هزینهٔ درخواست را هم نشان می‌دهد. به جای YOUR_API_KEY کلید خودتان را بگذارید:

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="
)

response = client.chat.completions.create(
    model="openai/gpt-5-nano",
    messages=[
        {"role": "system", "content": "You are a helpful assistant. Answer briefly, in Persian."},
        {"role": "user", "content": "Explain in two sentences what an API is."},
    ],
    reasoning_effort="low",
)

print(response.choices[0].message.content)
u = response.usage
print("input:", u.prompt_tokens, "| output:", u.completion_tokens, "| cost (rial):", u.cost_rial)

خروجی واقعی این کد در اجرای ما:

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

input: 31 | output: 150 | cost (rial): 305

یعنی این درخواست ۳۱ توکن ورودی و ۱۵۰ توکن خروجی مصرف کرد و ۳۰۵ ریال، حدود ۳۰ تومان، هزینه داشت. پیام سیستمی از مدل خواسته است پاسخ را فارسی بنویسد؛ برای همین، با این‌که متن درخواست انگلیسی است، جواب فارسی است. چند نکته دربارهٔ این کد:

  • base_url تنها تفاوت این کد با نمونه‌های رسمی OpenAI است. اگر پروژه‌ای دارید که با کتابخانهٔ openai نوشته شده، معمولاً با عوض کردن همین آدرس و کلید کار می‌کند.
  • پیام سیستمی (نقش system) رفتار کلی مدل را تعیین می‌کند؛ مثل زبان پاسخ، لحن و طول جواب.
  • reasoning_effort در مدل‌هایی مثل GPT-5 nano که پیش از پاسخ استدلال می‌کنند، مقدار این استدلال را کم نگه می‌دارد. توکن‌های استدلال هم جزو خروجی حساب می‌شوند؛ برای همین تعداد توکن خروجی از طول ظاهری پاسخ بیشتر است.
  • پاسخ و تعداد توکن‌ها از یک اجرا تا اجرای بعد کمی فرق می‌کند؛ برای برآورد هزینه، چند درخواست واقعی بفرستید و میانگین بگیرید.

گام سوم؛ انتخاب مدل بر اساس کار و قیمت

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

مدل ورودی / خروجی (تومان) حداکثر طول متن ورودی (توکن)
GPT-5 nano ۲۸٬۰۰۰ / ۱۹۷٬۰۰۰ ۴۰۰٬۰۰۰
Qwen3.8 Flash ۵۴٬۰۰۰ / ۱۶۹٬۰۰۰ ۱٬۰۰۰٬۰۰۰
DeepSeek V4.1 Flash ۹۸٬۰۰۰ / ۳۹۳٬۰۰۰ ۱٬۰۰۰٬۰۰۰
Gemini 3.7 Flash ۲۶۹٬۰۰۰ / ۱٬۳۴۵٬۰۰۰ ۱٬۰۴۸٬۵۷۶
Claude Haiku 4.5 ۳۹۳٬۰۰۰ / ۱٬۹۶۶٬۰۰۰ ۲۰۰٬۰۰۰
GPT-6 Sol ۷۸۶٬۰۰۰ / ۳٬۹۳۱٬۰۰۰ ۱٬۰۵۰٬۰۰۰

قیمت‌ها ممکن است تغییر کنند؛ قیمت روز و مشخصات هر مدل در لیست مدل‌ها و قیمت‌ها آمده است. برای عوض کردن مدل کافی است مقدار model را در کد بالا تغییر دهید؛ بقیهٔ کد همان می‌ماند.

خطاهای رایج و راه‌حل هر کدام

هر خطا یک کد وضعیت HTTP و یک شناسه دارد و از روی همین دو می‌شود فهمید مشکل از کجاست:

  • ۴۰۱؛ کلید پذیرفته نشد. کلید اشتباه یا ناقص کپی شده یا حذف شده است. تلاش دوباره فایده ندارد؛ اول کلید را بررسی کنید. با کتابخانهٔ openai هدر Authorization را خود کتابخانه می‌سازد و فقط باید کلید درست را به api_key بدهید.
  • ۴۰۲؛ موجودی یا سقف بودجه. اگر شناسهٔ خطا insufficient_funds باشد، موجودی کیف پول برای این درخواست کافی نیست؛ حساب را شارژ کنید یا مدل ارزان‌تری انتخاب کنید. اگر budget_exceeded باشد، سقف بودجهٔ ماهانهٔ همان کلید سازمانی پر شده است.
  • ۴۲۹؛ درخواست‌ها از سقف نرخ گذشته‌اند. کمی صبر کنید و دوباره بفرستید؛ هدر Retry-After می‌گوید چند ثانیه. کتابخانهٔ رسمی openai خطاهای ۴۲۹ و ۵۰۰ به بالا را به‌طور پیش‌فرض دو بار با فاصله دوباره امتحان می‌کند. حلقه‌ای که بی‌وقفه دوباره می‌فرستد مشکل را بدتر می‌کند.

قاعدهٔ کلی ساده است: ۴۰۱ و ۴۰۲ با تلاش دوباره درست نمی‌شوند و چیزی باید عوض شود، اما ۴۲۹ و خطاهای ۵۰۰ با صبر و تلاش دوباره برطرف می‌شوند.

نکته؛ اگر مدل خودش را با اسم دیگری معرفی کرد

ممکن است از یک مدل بپرسید «تو کی هستی؟» و جواب بشنوید «من ChatGPT هستم»، در حالی که مدل دیگری را انتخاب کرده‌اید. این رفتار شناخته‌شده‌ای در صنعت است و نشانهٔ عوض شدن مدل نیست:

  • در آزمایش ما روی ۲۴ مدل چت چینی در ۲۳ آبان ۱۴۰۵، DeepSeek V4 Flash در هر ۱۰ پاسخ خودش را ساخت OpenAI معرفی کرد و Seed 2.1 Turbo در هر ۳ پاسخ فارسی‌اش با پیام سیستمی گفت Gemini است، در حالی که به انگلیسی اسم خودش را درست گفت.
  • تک‌کرانچ در دسامبر ۲۰۲۴ گزارش داد که DeepSeek V3 هم در بسیاری از آزمایش‌ها خودش را ChatGPT معرفی می‌کرد.
  • یک پژوهش روی ۲۷ مدل زبانی، حدود ۲۶ درصد آن‌ها را دچار «سردرگمی هویت» دانست و بررسی دیگری روی حدود ۱۹۰ مدل نشان داد حدود ۶۰ درصدشان دست‌کم یک بار با اسمی غیر از اسم رسمی خود جواب داده‌اند.

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

جمع‌بندی

اتصال به API هوش مصنوعی از ایران با چند قدم ساده انجام می‌شود: کلید را بسازید، آدرس پایه و کلید را در کتابخانهٔ openai قرار دهید، با مدل ارزان شروع کنید و هزینهٔ هر درخواست را از فیلد مصرف ببینید. با شناختن معنی خطاهای ۴۰۱، ۴۰۲ و ۴۲۹ هم بیشتر مشکلات رایج را بدون اتلاف وقت برطرف می‌کنید. برای مقایسهٔ دقیق‌تر مدل‌ها و قیمت روز، به سایت هیبانا سر بزنید.