API هوش مصنوعی چیست و چطور از آن استفاده کنیم؟

API هوش مصنوعی یک رابط برنامه‌نویسی است که برنامه‌ی شما از طریق آن متنی را به یک مدل زبانی مثل GPT یا Claude می‌فرستد و پاسخ مدل را به شکل داده‌ی ساخت‌یافته (معمولاً JSON) پس می‌گیرد. به‌جای اینکه کاربر در یک صفحه‌ی چت تایپ کند، کد شما درخواست می‌سازد، می‌فرستد و پاسخ را هر جا لازم است استفاده می‌کند: در سایت، ربات تلگرام، اپلیکیشن موبایل یا یک اسکریپت پردازش داده. برای استفاده کافی است یک کلید API بگیرید، آدرس سرور را تنظیم کنید و درخواست بفرستید. هزینه هم بر اساس تعداد توکن‌های مصرفی حساب می‌شود.

در این مقاله همه‌ی مفاهیم پایه را از صفر توضیح می‌دهیم تا بتوانید با اطمینان اولین پروژه‌تان را شروع کنید.

API به زبان ساده

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

درخواست و پاسخ

هر تعامل با API دو بخش دارد. در درخواست مشخص می‌کنید کدام مدل، با چه دستورالعملی و چه پیام‌هایی کار کند. در پاسخ متن تولیدشده به همراه اطلاعاتی مثل تعداد توکن‌های مصرفی برمی‌گردد. ارتباط معمولاً با HTTPS انجام می‌شود و کلید API در هدر Authorization فرستاده می‌شود تا سرور بداند درخواست از طرف چه کسی است و هزینه را از کدام حساب کم کند.

مدل چیست؟

مدل همان «مغز» پشت API است. هر شرکت چند مدل با توانایی و قیمت متفاوت دارد: مدل‌های بزرگ برای استدلال پیچیده و کدنویسی، مدل‌های کوچک برای کارهای سریع و پرتکرار، و مدل‌های تخصصی برای تبدیل گفتار به متن، ساخت تصویر یا Embedding. در هوشوانا بیش از ۸۰ مدل از سازنده‌های مختلف با یک API در دسترس است و فهرست کامل را در کاتالوگ مدل‌ها می‌بینید.

توکن چیست؟

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

قیمت‌گذاری API هوش مصنوعی چطور کار می‌کند؟

قیمت تقریباً همه‌ی مدل‌های زبانی به ازای یک میلیون توکن اعلام می‌شود و دو عدد جدا دارد:

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

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

نمونه‌ی یک درخواست Chat Completions

رایج‌ترین endpoint در API هوش مصنوعی، Chat Completions است. شما فهرستی از پیام‌ها با نقش‌های system، user و assistant می‌فرستید و مدل پیام بعدی را تولید می‌کند. این نمونه با کتابخانه‌ی رسمی openai در پایتون نوشته شده است:

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://hooshvana.ir/api/v1",
    api_key=os.environ["HOOSHVANA_API_KEY"],
)

response = client.chat.completions.create(
    model="openai/gpt-4o-mini",
    messages=[
        {"role": "system", "content": "تو دستیار پشتیبانی یک فروشگاه هستی. کوتاه و مؤدبانه جواب بده."},
        {"role": "user", "content": "سفارشم کی می‌رسد؟"},
    ],
    max_tokens=300,
)

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

در خروجی، علاوه بر متن پاسخ، فیلد usage را می‌بینید که شامل prompt_tokens (توکن ورودی) و completion_tokens (توکن خروجی) است. همین اعداد مبنای محاسبه‌ی هزینه‌اند.

کاربردهای رایج

API هوش مصنوعی در پروژه‌های بسیار متنوعی استفاده می‌شود. چند نمونه‌ی پرکاربرد:

• چت‌بات پشتیبانی: پاسخ به سؤال‌های تکراری مشتری با تکیه بر اسناد خود کسب‌وکار.
• تولید و ویرایش محتوا: نوشتن توضیح محصول، خلاصه‌سازی مقاله یا بازنویسی متن.
• استخراج اطلاعات: بیرون کشیدن نام، شماره یا مبلغ از متن آزاد و تبدیل آن به JSON.
• دسته‌بندی: تشخیص موضوع تیکت، احساس نظر کاربر یا اولویت درخواست.
• ترجمه: برگرداندن متن بین فارسی و زبان‌های دیگر.
• دستیار کدنویسی: ابزارهایی مثل Claude Code که مستقیم در ترمینال با کد شما کار می‌کنند. راهنمای اتصال آن را در صفحه‌ی یکپارچه‌سازی Claude Code ببینید.

چطور مدل مناسب را انتخاب کنیم؟

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

1. از مدل ارزان شروع کنید. برای بیشتر کارهای ساده، مدل‌های کوچک مثل GPT-4o Mini کافی‌اند. اگر کیفیت راضی‌کننده نبود، سراغ مدل بزرگ‌تر بروید.
2. با داده‌ی واقعی آزمایش کنید. چند نمونه از ورودی‌های واقعی پروژه را روی دو یا سه مدل امتحان کنید و خروجی‌ها را کنار هم مقایسه کنید.
3. به نیاز خاص توجه کنید. اگر تصویر می‌فرستید، مدل باید ورودی تصویری را پشتیبانی کند. اگر سند طولانی دارید، طول context مهم است.
4. برای کارهای مختلف مدل‌های مختلف بگذارید. لازم نیست همه‌ی درخواست‌ها به یک مدل بروند.

اگر بین GPT و Claude مردد هستید، صفحه‌های API چت‌جی‌پی‌تی و API کلاد تفاوت‌ها را توضیح می‌دهند.

امنیت کلید API

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

• کلید را هرگز در کد فرانت‌اند نگذارید. هر چیزی که در مرورگر یا اپلیکیشن موبایل اجرا شود، قابل استخراج است. درخواست‌ها را از سرور خودتان بفرستید.
• کلید را در متغیر محیطی نگه دارید و فایل‌های حاوی آن را در Git ثبت نکنید.
• برای هر پروژه و هر محیط (توسعه، تست، تولید) کلید جدا بسازید تا اگر یکی لو رفت، فقط همان را باطل کنید.
• در صورت امکان، دسترسی کلید را به IP سرورتان محدود کنید.

کنترل هزینه

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

شروع کار با هوشوانا در چند قدم

1. با شماره‌ی موبایل ثبت‌نام کنید.
2. کیف پول را با کارت بانکی ایرانی شارژ کنید.
3. از بخش کلیدهای داشبورد یک کلید API بسازید و برایش سقف هزینه تعیین کنید.
4. کلید را در متغیر محیطی HOOSHVANA_API_KEY قرار دهید.
5. نمونه‌کد بالا را اجرا کنید یا مدل‌ها را اول در زمین بازی داشبورد امتحان کنید.

جزئیات هر قدم در راهنمای شروع سریع آمده است.

سؤال‌های رایج

برای استفاده از API هوش مصنوعی باید برنامه‌نویس باشم؟

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

تفاوت API با نسخه‌ی وب ChatGPT چیست؟

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

آیا داده‌هایی که می‌فرستم ذخیره می‌شود؟

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

هزینه‌ی شروع چقدر است؟

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