Grok API: فراخوانی Grok در کدهای شما

دو روش برای دسترسی به Grok از طریق کدنویسی

توسعه‌دهندگان می‌توانند به دو روش اصلی مدل‌های Grok را فراخوانی کنند. روش اول استفاده از API شرکت xAI است که مستقیماً توسط خود این شرکت (با برند فعلی SpaceXSI) ارائه می‌شود و کلیدهای آن از طریق console.x.ai دریافت می‌شود. روش دوم استفاده از یک مسیریاب مدل (model router) مانند OpenRouter است که مدل‌های ارائه‌دهندگان مختلف را با یک کلید و یک صورت‌حساب تجمیع می‌کند. هر دو سرویس از فرمت Chat Completions شرکت OpenAI پشتیبانی می‌کنند؛ بنابراین SDK‌های رسمی OpenAI پس از تغییر آدرس پایه (base URL) و نام مدل، بدون مشکل کار خواهند کرد.

کدام مسیر را انتخاب کنیم؟

• API شرکت xAI را انتخاب کنید اگر می‌خواهید زودتر از همه به تمام قابلیت‌های Grok دسترسی داشته باشید: لیست کامل مدل‌ها، Responses API، ابزارهای جستجوی سرورساید وب و جستجو در X، تولید تصویر و ویدیو با Grok Imagine، قابلیت صوتی، پردازش دسته‌ای (batch jobs) و تخفیف‌های پرامپت کش‌شده. آدرس پایه: https://api.x.ai/v1.
• OpenRouter را انتخاب کنید اگر می‌خواهید بدون نیاز به قراردادهای جداگانه، بین Grok و مدل‌های سایر شرکت‌ها جابه‌جا شوید، یا از قبل حساب کاربری OpenRouter دارید. آدرس پایه: https://openrouter.ai/api/v1، همراه با شناسه مدل‌ها با پیشوند x-ai/. راهنمای راه‌اندازی در بخش شروع سریع OpenRouter در دسترس است.

در هر دو حالت، کلید دسترسی (API Key) را روی سرور یا در یک متغیر محیطی ذخیره کنید. هرگز آن را داخل کدهای فرانت‌اند وب یا اپلیکیشن موبایل قرار ندهید، چرا که برای همه قابل مشاهده خواهد بود.

اولین درخواست شما به xAI API

یک کلید در کنسول بسازید، آن را با نام XAI_API_KEY ذخیره کنید و پیامی به Grok 4.7 بفرستید:

curl

curl https://api.x.ai/v1/chat/completions \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.7",
    "reasoning_effort": "low",
    "messages": [
      {"role": "system", "content": "You are a concise assistant."},
      {"role": "user", "content": "Give me three tips for a first marathon."}
    ]
  }'

پایتون با استفاده از کتابخانه OpenAI

import os
from openai import OpenAI

grok = OpenAI(
    api_key=os.environ["XAI_API_KEY"],
    base_url="https://api.x.ai/v1",
)

answer = grok.chat.completions.create(
    model="grok-4.3",
    reasoning_effort="medium",
    messages=[{"role": "user", "content": "Is 391 a prime number? Show your check."}],
)
print(answer.choices[0].message.content)

پارامتر reasoning_effort مدت‌زمان تفکر مدل پیش از پاسخ‌دهی را مشخص می‌کند. مدل Grok 4.3 گزینه‌های none، low، medium، high و xhigh را می‌پذیرد و به‌طور پیش‌فرض روی low تنظیم شده است؛ Grok 4.7 مقادیر low، medium، high و xhigh را می‌پذیرد و پیش‌فرض آن high است. برای Grok 4.20، شرکت xAI شناسه‌های جداگانه‌ای منتشر کرده است: grok-4.20-0309-reasoning و grok-4.20-0309-non-reasoning.

انجام همین کار از طریق OpenRouter

در OpenRouter، کلید را در OPENROUTER_API_KEY قرار دهید و از شناسه‌های دارای پیشوند x-ai/ استفاده کنید. OpenRouter فرایند تفکر مدل را با یک آبجکت reasoning کنترل می‌کند. این کد جاوااسکریپت در Node.js نسخه 18 یا بالاتر اجرا می‌شود:

const endpoint = "https://openrouter.ai/api/v1/chat/completions";

const reply = await fetch(endpoint, {
  headers: {
    Authorization: `Bearer ${process.env.OPENROUTER_API_KEY}`,
    "Content-Type": "application/json",
  },
  method: "POST",
  body: JSON.stringify({
    model: "x-ai/grok-4.20",
    reasoning: { enabled: false },
    stream: false,
    messages: [{ role: "user", content: "Rewrite this headline in a calmer tone: PRICES EXPLODE AGAIN" }],
  }),
});
const json = await reply.json();
console.log(json.choices[0].message.content);

برای فعال‌سازی حالت تفکر مدل، به‌جای آن از reasoning: { effort: "low" } (یا medium، high) استفاده کنید. اگر می‌خواهید فرایند استدلال به کار گرفته شود اما در خروجی برگردانده نشود، مقدار exclude: true را اضافه کنید. با تنظیم stream: true پاسخ به صورت لحظه‌ای و به محض تولید دریافت می‌شود که در رابط‌های چت سرعت بسیار بالاتری را القا می‌کند.

ارسال تصویر

مدل‌های Grok 4.20، 4.3 و 4.7 همگی قابلیت درک تصویر را دارند. کافی است از ساختار پیام استاندارد OpenAI با آرایه‌ای از بخش‌های مختلف استفاده کنید. طبق مستندات xAI، تصاویر JPEG و PNG تا سقف ۲۰ مگابایت پذیرفته می‌شوند و می‌توانید از لینک عمومی یا دیتای Base64 استفاده کنید.

{
  "model": "grok-4.20-0309-non-reasoning",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "image_url", "image_url": {"url": "https://example.com/receipt.png"}},
      {"type": "text", "text": "List the items and the total on this receipt."}
    ]
  }]
}

شناسه‌های مدل‌های Grok و قیمت‌ها

لیست زیر شامل مدل‌های متنی فعلی SpaceXAI در OpenRouter، به همراه ظرفیت کانتکست و قیمت هر یک میلیون توکن است (تعرفه رسمی OpenRouter، اکتبر ۲۰۲۶). در xAI API نیز برای پرامپت‌های کمتر از ۲۰۰,۰۰۰ توکن همین نرخ‌های پایه اعمال می‌شود.

چند نکته مهم بر اساس صفحه مدل‌ها و قیمت‌گذاری xAI (تعرفه رسمی xAI، اکتبر ۲۰۲۶):

• پرامپت‌های طولانی هزینه بیشتری دارند. اگر پرامپت به ۲۰۰,۰۰۰ توکن برسد، کل درخواست با نرخ بالاتری محاسبه می‌شود: ۴ دلار / ۱۲ دلار برای Grok 4.7، و ۲.۵۰ دلار / ۵ دلار برای Grok 4.3 و 4.20.
• ورودی‌های کش‌شده ارزان‌تر هستند: برای بخش‌های تکراری پرامپت‌ها، این رقم ۰.۵۰ دلار به ازای هر میلیون برای Grok 4.7 و ۰.۲۰ دلار برای Grok 4.3 و 4.20 است.
• پردازش‌های دسته‌ای (Batch) که نیازی به دریافت پاسخ آنی ندارند، شامل تخفیف می‌شوند؛ OpenRouter نیز مدل x-ai/grok-4.3:batch را با قیمت ۱ دلار / ۲ دلار ارائه می‌دهد.
• تفاوت کانتکست در منابع مختلف: OpenRouter کانتکست Grok 4.20 را ۲,۰۰۰,۰۰۰ توکن ذکر کرده، در حالی که در صفحه رسمی مدل‌های xAI مقدار ۱,۰۰۰,۰۰۰ توکن درج شده است.

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

نکات کاربردی

• برای چت، بازنویسی و استخراج متن، کار را با Grok 4.20 non-reasoning آغاز کنید. این مدل سریع و اقتصادی است. زمانی به سراغ Grok 4.3 یا 4.7 بروید که کیفیت انجام تسک‌های پیچیده اولویت بالاتری نسبت به سرعت داشته باشد.
• به محدودیت زمانی دانش مدل‌ها توجه کنید. طبق اعلام xAI، داده‌های Grok 4.7 تا مه ۲۰۲۶ به‌روز است. برای اطلاعات جدیدتر، حقایق لازم را در پرامپت قرار دهید یا از ابزارهای جستجوی وب و X در سمت سرور xAI استفاده کنید که به ازای هر فراخوانی هزینه دارند.
• یک System Message دقیق بنویسید و در آن نقش، لحن و فرمت خروجی مورد نظر را مشخص کنید؛ اگر کد شما قرار است خروجی را پردازش کند، خروجی JSON همراه با Schema بخواهید.
• محدودیت تعداد درخواست (Rate Limits) را مدیریت کنید. در صورت دریافت خطای 429، پس از وقفه‌ای کوتاه درخواست را مجدداً ارسال کنید.
• قوانین را رعایت کنید. قوانین استفاده مجاز xAI بر مصرف API حاکم است و با استفاده از فیلد safety_identifier می‌توانید درخواست‌ها را به ازای هر کاربر نهایی نشانه‌گذاری کنید.

رفع مشکلات رایج

• خطای 401 یا 403: کلید API وارد نشده، منقضی شده یا در محیط نادرستی فراخوانی شده است. برای اطمینان از وجود آن، چند کاراکتر ابتدایی کلید را در سمت سرور لاگ بگیرید.
• خطای Model not found: پیشوند مدل را بررسی کنید. OpenRouter نیاز به ساختار x-ai/grok-4.7 دارد، در حالی که در xAI نام ساده grok-4.7 استفاده می‌شود.
• پاسخ‌های خالی یا بسیار کند در مدل‌های استدلالی معمولاً به این معنی است که سقف توکن‌های خروجی صرف فرایند تفکر شده است. مقدار effort را کاهش دهید یا پارامتر max_tokens را افزایش دهید.
• عدم پذیرش تصویر: فرمت آن را به JPEG یا PNG تغییر داده و از رعایت سقف حجم فایل اطمینان حاصل کنید.

سؤالات متداول

آیا API مدل Grok با SDK اختصاصی OpenAI سازگار است؟

بله. کافی است آدرس SDK را روی https://api.x.ai/v1 با کلید xAI، یا روی OpenRouter با کلید اختصاصی آن تنظیم کرده و شناسه مدل Grok را وارد کنید.

آیا API رایگان برای Grok وجود دارد؟

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

آیا می‌توان با Grok API تصویر تولید کرد؟

بله، از طریق مدل‌های Grok Imagine شرکت xAI روی اندپوینت اختصاصی تصاویر. صفحه Grok Imagine ما را مشاهده کنید. سیستم چت وب‌سایت ما تصویر تولید نمی‌کند.

سایت Grok.Online از کدام مدل Grok استفاده می‌کند؟

بخش چت ما مدل‌های Grok 4.20 بدون استدلال، Grok 4.3 با استدلال پایین (low)، و Grok 4.7 را تا سقف ۱۰ پیام در روز، همگی از طریق OpenRouter ارائه می‌دهد.