نِت اَرز · مستندات API هوش مصنوعی
همهٔ مستندات
مدل‌ها و قیمت‌ها مرجع تعاملی دریافت کلید

Chat Completions

اصلی‌ترین endpoint: پیام‌ها، پارامترها، بینایی (تصویر)، ابزارها (function calling)، حالت JSON و مدل‌های استدلالی.

base_url: https://netarz.ir/api/ai/v1 به‌روزرسانی: 1405/06/30
POST /api/ai/v1/chat/completions نیازمند کلید API

اصلی‌ترین endpoint نِت اَرز و سازگار با OpenAI Chat Completions. مدل‌های GPT، Gemini و DeepSeek را مستقیم وصل کرده‌ایم و Claude، Grok، Mistral، Llama، Qwen و بقیه از مسیر OpenRouter می‌آیند؛ برای همهٔ آن‌ها همین endpoint را با همان بدنه صدا می‌زنید و ترجمه به پروتکل هر ارائه‌دهنده در سمت نِت اَرز انجام می‌شود. شکل شناسهٔ مدل در مدل‌ها و قیمت‌ها آمده است.

درخواست پایه

Python 
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "system", "content": "شما دستیار پشتیبانی فروشگاه نِت اَرز هستید؛ کوتاه و دقیق پاسخ بدهید."},
        {"role": "user", "content": "سفارشم کی تحویل داده می‌شود؟"},
    ],
    temperature=0.4,
    max_tokens=300,
)
print(response.choices[0].message.content)
Node.js 
const response = await client.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [
    { role: "system", content: "شما دستیار پشتیبانی فروشگاه نِت اَرز هستید؛ کوتاه و دقیق پاسخ بدهید." },
    { role: "user", content: "سفارشم کی تحویل داده می‌شود؟" },
  ],
  temperature: 0.4,
  max_tokens: 300,
});
console.log(response.choices[0].message.content);
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": "شما دستیار پشتیبانی فروشگاه نِت اَرز هستید؛ کوتاه و دقیق پاسخ بدهید."},
      {"role": "user", "content": "سفارشم کی تحویل داده می‌شود؟"}
    ],
    "temperature": 0.4,
    "max_tokens": 300
  }'
پاسخ 
{
  "id": "req_9f2c1e0b7a6d4c3f8e1a2b3c",
  "object": "chat.completion",
  "created": 1756540800,
  "model": "gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "سفارش‌های دیجیتال معمولاً بلافاصله پس از پرداخت در پنل شما قرار می‌گیرند." },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 58,
    "completion_tokens": 27,
    "total_tokens": 85,
    "prompt_tokens_details": { "cached_tokens": 0 },
    "completion_tokens_details": { "reasoning_tokens": 0 }
  }
}

پارامترها

پارامترنوعتوضیح
model الزامیstringشناسهٔ مدل (فهرست). باید از نوع گفت‌وگو باشد.
messages الزامیarrayآرایهٔ غیرخالی پیام‌ها با role و content (حداکثر ۵۰۰ پیام).
streambooleanپاسخ به‌صورت SSE. استریم
max_tokens / max_completion_tokensintegerسقف توکن خروجی. تعیین آن مبلغ رزرو اعتبار را کوچک می‌کند. بیشتر
temperature، top_pnumberخلاقیت/تنوع پاسخ. عبور مستقیم به ارائه‌دهنده.
nintegerتعداد پاسخ‌های موازی؛ حداکثر ۴. هر پاسخ جداگانه هزینه دارد.
stopstring | arrayرشته‌های توقف.
response_formatobject{"type": "json_object"} یا json_schema برای مدل‌هایی که json را پشتیبانی می‌کنند.
tools، tool_choice، parallel_tool_callsarray | string | objectفراخوانی تابع (function calling) به سبک OpenAI؛ برای Claude و Gemini هم به قالب خودشان ترجمه می‌شود.
reasoning_effortlow | medium | highبرای مدل‌های استدلالی. در Claude به بودجهٔ extended thinking تبدیل می‌شود.
seed، logprobs، frequency_penalty، presence_penalty، logit_bias—عبور مستقیم؛ فقط اگر ارائه‌دهندهٔ زیرین پشتیبانی کند اثر دارد.
userstringپذیرفته می‌شود اما پیش از ارسال با شناسهٔ حساب شما در نِت اَرز جایگزین می‌شود (حریم خصوصی کاربران نهایی شما).

فیلدهای stream_options، store، service_tier و safety_identifier حذف می‌شوند. سایر فیلدهای ناشناخته به همان شکل به ارائه‌دهنده عبور داده می‌شوند (مثلاً فیلدهای اختصاصی DeepSeek یا OpenRouter).

پیام‌ها

نقش‌ها: system یا developer (دستور کلی)، user، assistant (پاسخ‌های قبلی) و tool (خروجی تابع). content می‌تواند رشته یا آرایه‌ای از بخش‌ها باشد:

  • {"type": "text", "text": "…"}
  • {"type": "image_url", "image_url": {"url": "https://… یا data:image/…;base64,…"}} — فقط برای مدل‌های با قابلیت vision. هر تصویر هزینهٔ توکنی دارد که ارائه‌دهنده گزارش می‌کند.

برای Claude، پیام‌های system به فیلد system و نقش tool به بلوک tool_result ترجمه می‌شود؛ شما چیزی متفاوت نمی‌فرستید.

بینایی (ورودی تصویر)

Python 
response = client.chat.completions.create(
    model="gpt-4o-mini",   # یا هر مدلی با capabilities.vision = true
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "مبلغ این رسید چقدر است و به چه تاریخی؟"},
            {"type": "image_url", "image_url": {"url": "https://example.com/receipt.jpg"}},
            # یا تصویر base64:  {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,/9j/4AAQ..."}}
        ],
    }],
    max_tokens=200,
)

ابزارها (function calling)

مدل تصمیم می‌گیرد تابعی را صدا بزند؛ شما تابع را اجرا می‌کنید و نتیجه را با نقش tool برمی‌گردانید:

Python 
tools = [{
    "type": "function",
    "function": {
        "name": "get_order_status",
        "description": "وضعیت یک سفارش را بر اساس شمارهٔ سفارش برمی‌گرداند",
        "parameters": {
            "type": "object",
            "properties": {"order_number": {"type": "string"}},
            "required": ["order_number"],
        },
    },
}]

messages = [{"role": "user", "content": "سفارش NZ-10422 در چه وضعیتی است؟"}]

first = client.chat.completions.create(model="gpt-4o-mini", messages=messages, tools=tools, max_tokens=200)
call = first.choices[0].message.tool_calls[0]
# call.function.name == "get_order_status", call.function.arguments == '{"order_number": "NZ-10422"}'

result = {"status": "delivered", "delivered_at": "2026-08-29"}   # خروجی تابع خودتان

messages += [
    first.choices[0].message,
    {"role": "tool", "tool_call_id": call.id, "content": json.dumps(result, ensure_ascii=False)},
]
final = client.chat.completions.create(model="gpt-4o-mini", messages=messages, tools=tools, max_tokens=200)
print(final.choices[0].message.content)

خروجی JSON

Python 
response = client.chat.completions.create(
    model="gpt-4o-mini",
    response_format={"type": "json_object"},
    messages=[
        {"role": "system", "content": "فقط یک شیء JSON معتبر برگردان."},
        {"role": "user", "content": "برای محصول «کفش دویدن» سه ویژگی کوتاه با کلید features بنویسید."},
    ],
    max_tokens=200,
)
data = json.loads(response.choices[0].message.content)

برای ساختار دقیق‌تر، response_format: {"type": "json_schema", "json_schema": {...}} را با مدل‌های OpenAI به کار ببرید.

مدل‌های استدلالی

Python 
response = client.chat.completions.create(
    # Claude فقط از مسیر OpenRouter صدا زده می‌شود؛ اتصال مستقیم Anthropic باز نیست.
    model="openrouter/anthropic/claude-sonnet-4.5",
    # جایگزین‌ها: o3، o4-mini، openrouter/google/gemini-2.5-pro،
    #             openrouter/deepseek/deepseek-r1، openrouter/x-ai/grok-4.6
    reasoning_effort="medium",          # low | medium | high
    max_tokens=4000,                    # برای Claude باید بزرگ‌تر از بودجهٔ thinking باشد
    messages=[{"role": "user", "content": "سه عدد صحیح متوالی که مجموع‌شان ۹۹ است کدام‌اند؟ گام‌به‌گام حل کنید."}],
)
print(response.choices[0].message.content)
print(response.usage.completion_tokens_details)   # reasoning_tokens

توکن‌های استدلال در usage.completion_tokens_details.reasoning_tokens گزارش و با قیمت خروجی محاسبه می‌شوند. DeepSeek R1 زنجیرهٔ فکر را در فیلد reasoning_content پیام برمی‌گرداند.

Completions (قدیمی)

POST /api/ai/v1/completions نیازمند کلید API

برای ابزارهای قدیمی که هنوز prompt می‌فرستند. متن به یک پیام کاربر تبدیل و پاسخ در قالب text_completion برگردانده می‌شود. استریم پشتیبانی می‌شود.

cURL 
curl https://netarz.ir/api/ai/v1/completions \
  -H "Authorization: Bearer $NETARZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o-mini", "prompt": "یک جملهٔ انگیزشی بنویسید.", "max_tokens": 60}'

نکات

  • هدر X-Request-Id و فیلد id پاسخ، شناسهٔ درخواست در نِت اَرز است؛ در گزارش خطا به پشتیبانی همین را بفرستید.
  • برای ارائه‌دهنده‌هایی که prompt caching دارند (OpenAI، Anthropic، DeepSeek، Gemini)، پیام‌های ثابت (system و اسناد) را ابتدای گفت‌وگو بگذارید تا cached_tokens بالا برود و ارزان‌تر تمام شود.
  • حداکثر اندازهٔ بدنهٔ درخواست ۲۰ مگابایت است؛ برای تصاویر بزرگ به‌جای base64 از URL استفاده کنید.
© 2026 نِت اَرز همهٔ مستندات مدل‌ها و قیمت‌ها صفحهٔ معرفی سرویس پشتیبانی فنی (ورود)