گراک (Grok) برای برنامه‌نویس ایرانی؛ از اولین درخواست تا تصویر

گراک (Grok) را در شبکهٔ X دیده‌اید و حالا می‌خواهید همان مدل را در ربات پشتیبانی یا ابزار داخلی شرکتتان به کار ببرید. سری به کنسول xAI می‌زنید، حساب می‌سازید و به صفحهٔ پرداخت می‌رسید: کارت بانکی بین‌المللی. بیشتر برنامه‌نویس‌های ایرانی همین‌جا متوقف می‌شوند.

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

اشتراک SuperGrok یا API گراک؟

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

گراک روی درگاه ما از کدام مسیر می‌آید

اتصال مستقیم به xAI روی درگاه باز نیست. مدل‌های گراک از مسیر OpenRouter می‌آیند و شناسهٔ همه با openrouter/x-ai/ شروع می‌شود. شناسهٔ کوتاه مثل grok-4 خطای ۴۰۴ می‌گیرد. قاعدهٔ این مسیر را در راهنمای OpenRouter در مستندات نوشته‌ایم و این‌جا فقط نتیجه‌اش مهم است: کلید و اعتبار شما مال نِت اَرز است و حساب xAI لازم ندارید.

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

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

کلید را از پنل هوش مصنوعی در نِت اَرز بسازید؛ با sk-ntz-v1- شروع می‌شود. بعد کتابخانهٔ رسمی openai را نصب کنید (pip install openai) و فقط نشانی پایه را عوض کنید:

import os
from openai import OpenAI

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

resp = client.chat.completions.create(
    model="openrouter/x-ai/grok-4.6",
    messages=[
        {"role": "system", "content": "به فارسی روان و کوتاه پاسخ بدهید."},
        {"role": "user", "content": "سه نام پیشنهادی برای یک کافهٔ کوچک در شیراز بنویسید."},
    ],
    max_tokens=600,
)
print(resp.choices[0].message.content)
print(resp.usage)          # prompt, completion and total tokens of this request

همین درخواست با cURL، برای وقتی که فقط می‌خواهید کلید را امتحان کنید:

curl https://netarz.ir/api/ai/v1/chat/completions \
  -H "Authorization: Bearer $NETARZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "openrouter/x-ai/grok-4.6", "messages": [{"role": "user", "content": "Hello"}], "max_tokens": 200}'

مدل‌های گفت‌وگوی گراک تصویر ورودی، فراخوانی ابزار (function calling)، خروجی JSON و پاسخ تکه‌تکه (استریم) را می‌فهمند. پس کدی که برای GPT نوشته‌اید، با عوض کردن شناسهٔ مدل همین‌جا هم کار می‌کند. اگر تازه با پایتون سراغ این کار آمده‌اید، اتصال به API با پایتون استریم و مدیریت خطا را قدم‌به‌قدم گفته است.

پاسخ تکه‌تکه برای ربات و چت

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

stream = client.chat.completions.create(
    model="openrouter/x-ai/grok-4.6",
    messages=[{"role": "user", "content": "یک معرفی سه‌جمله‌ای از شیراز بنویسید."}],
    max_tokens=600,
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

اولین تکه ممکن است با کمی مکث برسد، چون مدل هنوز در حال فکر کردن است؛ در این فاصله یک نشانهٔ «در حال نوشتن» نشان بدهید و اتصال را نبندید. در ربات تلگرام یا ویجت چت سایت، همین الگو تفاوت یک برنامهٔ کند با برنامه‌ای است که زنده به نظر می‌رسد.

گراک در n8n، Cline و ابزارهای آماده

لازم نیست برای هر کاری کد بنویسید. هر ابزاری که اجازه می‌دهد نشانی پایهٔ OpenAI را عوض کنید، با گراک هم کار می‌کند: در تنظیمات مدل، گزینهٔ سازگار با OpenAI را انتخاب کنید، نشانی پایه را https://netarz.ir/api/ai/v1 بگذارید، کلید sk-ntz-v1-… را وارد کنید و نام مدل را دستی بنویسید، مثلاً openrouter/x-ai/grok-4.6. بیشتر ابزارها فهرست مدل را خودشان از مسیر /models می‌خوانند؛ اگر گراک را در فهرست کشویی ندیدید، نام را دستی تایپ کنید. راهنمای قدم‌به‌قدم این تنظیم برای n8n در اتصال n8n و Make به مدل‌های هوش مصنوعی و برای ویرایشگرهای کد در اتصال Cursor و Cline به نشانی دلخواه آمده است.

هزینه: ورودی، خروجی و «فکر کردن» مدل

هزینهٔ هر درخواست از روی تعداد توکن ورودی و خروجی حساب می‌شود و قیمت هر میلیون توکن در فهرست مدل‌ها به دلار نوشته شده. یک نکتهٔ مخصوص مدل‌های تازهٔ گراک این است که مدل استدلالی (reasoning) هستند: پیش از نوشتن جواب، متنی برای خودشان «فکر می‌کنند» و توکن‌های این فکر کردن هم جزو خروجی حساب می‌شود. برای همین یک پرسش کوتاه ممکن است بیش از حد انتظار توکن خروجی مصرف کند.

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

برای مقایسهٔ هزینهٔ گراک با GPT، Claude و DeepSeek در یک کار مشخص، مقایسهٔ قیمت API مدل‌های هوش مصنوعی را ببینید.

تصویر، ویدیو و صدا با گراک

مدل‌های تصویری گراک از مسیر /images/generations کار می‌کنند و پاسخ همیشه base64 است (b64_json)، نه لینک. هر مدل اندازه‌های خودش را دارد و اندازه‌ای را که نشناسد رد می‌کند؛ پس اول بدون size امتحان کنید:

import base64

img = client.images.generate(
    model="openrouter/x-ai/grok-imagine-image-2.0",
    prompt="A minimal poster of a Persian tea glass on a wooden table, warm morning light",
)
raw = base64.b64decode(img.data[0].b64_json)
ext = "png" if raw[:4] == b"\x89PNG" else "jpg"
with open(f"poster.{ext}", "wb") as f:
    f.write(raw)

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

برای صدا، مدل openrouter/x-ai/grok-voice-tts-1.0 از مسیر /audio/speech متن را می‌خواند. صداهایش نام‌های خودشان را دارند (eve، ara، rex، sal و leo)، هر درخواست حداکثر ۳٬۰۰۰ نویسه می‌گیرد و خروجی MP3 است. هزینه‌اش به‌ازای نویسه حساب می‌شود، نه توکن. کیفیت خواندن فارسی را پیش از استفاده در محصول، با یک جملهٔ کوتاه از متن واقعی خودتان بسنجید:

speech = client.audio.speech.create(
    model="openrouter/x-ai/grok-voice-tts-1.0",
    voice="eve",
    input="Welcome to our shop. Your order is on its way.",
)
with open("welcome.mp3", "wb") as f:
    f.write(speech.content)

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

سرورتان در ایران است؟

اگر برنامهٔ شما روی سروری در دیتاسنترهای داخل ایران اجرا می‌شود، درخواست‌های بزرگ به netarz.ir ممکن است بی‌جواب بمانند. در این حالت نشانی پایه را https://gisoo.pro/api/v1 بگذارید؛ کلید و اعتبار همان است و فقط یک خط عوض می‌شود. برای سرورهای بیرون از ایران همان نشانی netarz.ir کافی است.

خطاهایی که روز اول می‌بینید

• model_not_found: نام مدل را تنها فرستاده‌اید، مثل grok-4.6 بدون openrouter/x-ai/، یا نسخه‌ای را نوشته‌اید که دیگر در فهرست نیست. شناسه را از فهرست مدل‌ها کپی کنید.
• insufficient_credit: اعتبار برای مبلغی که پیش از درخواست کنار گذاشته می‌شود کافی نیست. کمی شارژ کنید یا max_tokens را پایین بیاورید.
• پاسخ کند است: مدل استدلالی پیش از جواب فکر می‌کند. برای کارهای سبک مثل دسته‌بندی متن، یک مدل غیراستدلالی و سریع‌تر از فهرست انتخاب کنید یا پاسخ را استریم کنید تا کاربر منتظر صفحهٔ خالی نماند.

بقیهٔ خطاهای رایج و راه‌حلشان در خطاهای رایج API هوش مصنوعی جمع شده است.