وب‌سرویس هوش مصنوعی چیست و کِی از اشتراک به‌صرفه‌تر است؟

چهار نفر در یک دفتر کار می‌کنند و هر چهار نفر یک اشتراک ماهانهٔ ChatGPT دارند. تا دیروز کافی بود؛ امروز سفارشی رسیده که برای هشتصد کالای فروشگاه توضیح فارسی می‌خواهد. هیچ‌کس حاضر نیست هشتصد بار متن را در مرورگر کپی و جای‌گذاری کند، و اگر هم بکنند، لحن خروجی هر نفر با دیگری فرق خواهد داشت. اینجا همان نقطه‌ای است که کار از اشتراک بیرون می‌زند و به وب‌سرویس (API) می‌رسد: به‌جای اینکه یک آدم پشت مرورگر بنشیند، کد شما مستقیم با مدل حرف می‌زند.

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

وب‌سرویس (API) یعنی کد شما به‌جای شما تایپ می‌کند

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

سه تفاوت بنیادی با اشتراک ماهانه دارد و هر سه روی تصمیم کسب‌وکار اثر می‌گذارند:

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

نقطهٔ ضعفش هم روشن است: وب‌سرویس رابط کاربری ندارد. اگر قرار است یک نفر در تیم با دست چت کند و فایل بالا بفرستد، اشتراک برایش ساده‌تر و شفاف‌تر تمام می‌شود. مقایسهٔ عددی این دو را با مثال در تفاوت API و اشتراک نوشته‌ایم.

کالبدشکافی یک درخواست: پنج چیزی که رد و بدل می‌شود

هر درخواست به یک وب‌سرویس هوش مصنوعی پنج جزء دارد. با شناختن همین پنج تا، تقریباً هر نمونه‌کدی در اینترنت برایتان خوانا می‌شود:

• نشانی پایه (base_url): ریشهٔ همهٔ درخواست‌ها. روی نِت اَرز https://netarz.ir/api/ai/v1 و مسیر گفت‌وگو /chat/completions.
• کلید دسترسی (API Key): رشته‌ای که هویت حساب شما را می‌رساند و در سربرگ Authorization: Bearer می‌رود. کلیدهای ما با sk-ntz-v1- شروع می‌شوند.
• نام مدل (model): مثلاً gpt-4o-mini. همین یک رشته تعیین می‌کند کیفیت و قیمت کارتان چقدر باشد.
• پیام‌ها (messages): آرایه‌ای از نوبت‌های گفت‌وگو. نقش system قانون کلی را می‌گوید، user خواستهٔ کاربر را، و assistant پاسخ‌های پیشین مدل را.
• گزارش مصرف (usage): در پاسخ برمی‌گردد و می‌گوید چند توکن ورودی و چند توکن خروجی خرج شده. صورت‌حساب از روی همین ساخته می‌شود، نه از روی تعداد درخواست‌ها.

ساده‌ترین شکل ممکن، با curl:

curl https://netarz.ir/api/ai/v1/chat/completions \
  -H "Authorization: Bearer $NETARZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "system", "content": "you are a concise Persian copywriter"},
      {"role": "user", "content": "یک توضیح ۴۰ کلمه‌ای برای کفش دویدن مردانه بنویس"}
    ],
    "max_tokens": 200
  }'

و پاسخی که برمی‌گردد، دقیقاً همان قالب استاندارد OpenAI:

{
  "id": "req_9f2c1e0b7a6d4c3f8e1a2b3c",
  "object": "chat.completion",
  "model": "gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "…متن تولیدشده…" },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 41, "completion_tokens": 58, "total_tokens": 99 }
}

دو فیلد را همیشه بخوانید. finish_reason اگر length باشد یعنی پاسخ وسط جمله بریده شده و usage تنها جایی است که هزینهٔ واقعی را می‌گوید.

بابت چه چیزی پول می‌دهید: توکن، نه صندلی

واحد شمارش در همهٔ این سرویس‌ها توکن است؛ تکه‌ای از متن که معمولاً کوچک‌تر از یک کلمه درمی‌آید. هم چیزی که می‌فرستید شمرده می‌شود (توکن ورودی) و هم چیزی که مدل می‌نویسد (توکن خروجی)، و نرخ خروجی تقریباً همیشه چند برابر ورودی است. نکته‌ای که برای ما مهم‌تر از بقیه است: متن فارسی به ازای هر کلمه توکن بیشتری از انگلیسی می‌گیرد، پس برآوردهای انگلیسی‌زبان اینترنت برای پروژهٔ فارسی خوش‌بینانه‌اند. روش شمردن و مثال‌های واقعی در توکن چیست و هزینه چطور حساب می‌شود آمده است.

سه قاعده که صورت‌حساب را قابل پیش‌بینی می‌کنند:

• همیشه max_tokens بفرستید. پیش از هر درخواست مبلغی برای بیشترین خروجی ممکن رزرو می‌شود؛ با تعیین سقف، رزرو کوچک‌تر می‌شود و بعد از پاسخ فقط مصرف واقعی کسر می‌شود.
• درخواست ناموفق هزینه ندارد. اگر ارائه‌دهنده خطا بدهد یا پاسخ ندهد، مبلغ رزروشده همان لحظه آزاد می‌شود.
• تاریخچهٔ گفت‌وگو را بی‌حساب نگه ندارید. هر پیام قدیمی در هر نوبت دوباره به‌عنوان ورودی شمرده می‌شود؛ چت طولانی، گران‌ترین اشتباه رایج است.

اشتراک یا وب‌سرویس؟ جدولی که تکلیف را روشن می‌کند

این جدول همان چیزی است که معمولاً در جلسهٔ تصمیم‌گیری روی تخته می‌نویسیم:

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

اولین درخواست، با کتابخانهٔ رسمی

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

# pip install openai
from openai import OpenAI

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

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "system", "content": "you write short Persian product copy"},
        {"role": "user", "content": "کفش دویدن مردانه، سبک، زیره فوم"},
    ],
    max_tokens=200,
)

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

در Node.js هم دقیقاً همین شکل است؛ کافی است baseURL را در سازندهٔ کلاینت بگذارید و کلید را از متغیر محیطی بخوانید. نمونهٔ PHP و لاراول را در استفاده از API هوش مصنوعی در PHP و لاراول آورده‌ایم.

از ایران چه چیزی فرق می‌کند؟

دو مانع عملی وجود دارد و هر دو راه‌حل مشخص دارند. اول اینکه نشانی رسمی بیشتر ارائه‌دهندگان، درخواستی را که از محدودهٔ ایران برسد با خطای ۴۰۳ رد می‌کند؛ این خطا به کلید شما ربطی ندارد و با عوض کردن کد حل نمی‌شود. دوم اینکه پرداخت به حساب خارجی کارت ارزی می‌خواهد.

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

یک نکتهٔ حریم خصوصی هم بگوییم، چون زیاد پرسیده می‌شود: متن پیام‌ها و پاسخ‌ها نزد ما ذخیره نمی‌شود و فقط فراداده (مدل، تعداد توکن، وضعیت، زمان و IP) برای صورت‌حساب و امنیت می‌ماند.

پنج اشتباهی که روز اول هزینه می‌سازد

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

قدم بعدی

اگر تازه شروع کرده‌اید، مسیر کوتاه این است: یک حساب بسازید، اعتبار بخرید، در پنل یک پروژه و یک کلید بسازید و همان نمونهٔ curl بالا را با مدل کوچک اجرا کنید. وقتی اولین پاسخ آمد، سراغ چیزی بروید که واقعاً وقت تیمتان را می‌گیرد؛ معمولاً همان کار تکراری هشتصدتایی است.

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