مستندات IranNet AI API

از انتخاب مدل تا ارسال اولین درخواست. اتصال را در سمت سرور آماده کنید و از کلید API و شناسه مدل مجاز حساب خود استفاده کنید.

1. مدل را بررسی کنیدقیمت، ظرفیت زمینه و نوع ورودی مناسب پروژه را در بازار مدل مقایسه کنید.
2. دسترسی حساب را دریافت کنیدآدرس رسمی سرویس، کلید API و شناسه مجاز را از اطلاعات دسترسی حساب دریافت کنید.
3. اتصال سرور را آماده کنیدمقادیر را در متغیر محیطی نگه دارید و نمونه ساده را با داده غیرحساس اجرا کنید.
4. مصرف و کیفیت را بسنجیدپیش از استفاده واقعی، پاسخ، خطا و بودجه مصرف را بررسی کنید.

# IRANNET_AI_ORIGIN: official IranNet origin, no /v1 suffix
# API key and model ID come from your activated account.
curl --fail-with-body "$IRANNET_AI_ORIGIN/v1/models" \
  -H "Authorization: Bearer $IRANNET_API_KEY"

curl --fail-with-body "$IRANNET_AI_ORIGIN/v1/chat/completions" \
  -H "Authorization: Bearer $IRANNET_API_KEY" \
  -H "Content-Type: application/json" \
  --data "$(jq -n --arg model "$IRANNET_MODEL_ID" \
    '{model:$model,messages:[{role:"user",content:"سلام"}]}')"

Python از کتابخانه استاندارد و Node.js از fetch داخلی استفاده می‌کند. نمونه cURL به jq نیاز دارد. هیچ SDK یا نسخه‌ای به‌عنوان سازگاری صددرصد تأیید نشده است.

آدرس سرویس و احراز هویت

متغیر IRANNET_AI_ORIGIN باید آدرس رسمی سرویس ایران‌نت، بدون مسیر /v1 و بدون اسلش انتهایی باشد. آدرس عملیاتی را از اطلاعات دسترسی حساب بگیرید؛ نام دامنه فرضی در نمونه‌ها قرار داده نشده است.

Authorization: Bearer <API_KEY>
Content-Type: application/json

کلید در هدر Authorization ارسال می‌شود؛ آن را در URL، Query String یا کد سمت مرورگر نگذارید. برای آماده‌سازی محیط، سه متغیر IRANNET_AI_ORIGIN، IRANNET_API_KEY و IRANNET_MODEL_ID را تنظیم کنید.

دریافت مدل‌های مجاز

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

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

ارسال درخواست گفتگو

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

{
  "model": "<MODEL_ID_FROM_ACCOUNT>",
  "messages": [{"role": "user", "content": "سلام"}]
}

عبارت OpenAI-compatible API surface فقط برای بخش‌هایی به کار می‌رود که سازگاری آن‌ها در IranNet Core تأیید شده باشد؛ به معنی پوشش همه endpointها، SDKها و قابلیت‌های همه مدل‌ها نیست. قابلیت‌های اختیاری برای هر مدل جداگانه تعیین می‌شوند.

پارامترهای درخواست و حدود پشتیبانی

پارامتر نامعتبر را با حذف خاموش یا تغییر خودکار پنهان نکنید. پیام خطا را مدیریت کنید و پشتیبانی مدل را پیش از تغییر رفتار برنامه بررسی کنید. Streaming و ورودی چندرسانه‌ای قرارداد مستقل دارند و در این نمونه حداقلی فعال نشده‌اند.

فراخوانی ابزار و ادامه گفتگو

مدل فقط درخواست اجرای ابزار را تولید می‌کند. اجرای واقعی، کنترل مجوزها و اعتبارسنجی ورودی وظیفه برنامه شماست. الگوی زیر برای مدلی است که Tool Calling را پشتیبانی می‌کند.

{
  "tools": [{
    "type": "function",
    "function": {
      "name": "lookup_order",
      "description": "Read an order the authenticated user may access",
      "parameters": {
        "type": "object",
        "properties": {"order_id": {"type": "string"}},
        "required": ["order_id"],
        "additionalProperties": false
      }
    }
  }]
}

1. پاسخ دستیار را حفظ کنیدپیام assistant شامل tool_calls و شناسه فراخوانی را به تاریخچه اضافه کنید.
2. ابزار را اعتبارسنجی کنیدنام و آرگومان‌ها را بررسی کنید؛ دسترسی کاربر به سفارش باید در سرور کنترل شود.
3. نتیجه را با همان شناسه برگردانیدپیام role: tool با tool_call_id متناظر بسازید. نتیجه را در content قرار دهید.
4. گفتگو را ادامه دهیدتاریخچه کامل را دوباره به مدل بفرستید. سقف تعداد مراحل، زمان و مصرف تعیین کنید.

// Conditional continuation shape; preserve the actual assistant message.
messages.push(assistantMessage);
messages.push({
  role: "tool",
  tool_call_id: actualToolCallId,
  content: JSON.stringify(validatedToolResult)
});
// Send messages again with the same permitted model.
// Never invent a tool_call_id or run unvalidated arguments.

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

خروجی ساختاریافته

در مدل‌های تأییدشده، response_format می‌تواند قالب JSON Schema را درخواست کند. حالت JSON معتبر با انطباق دقیق با Schema یکسان نیست. الگوی زیر تنها برای قابلیت تأییدشده json_schema است.

{
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "summary_result",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {"summary": {"type": "string"}},
        "required": ["summary"],
        "additionalProperties": false
      }
    }
  }
}

پشتیبانی از strict و زیرمجموعه JSON Schema را جدا بررسی کنید. پاسخ ناقص، امتناع مدل و پایان به علت محدودیت توکن را مدیریت کنید. خروجی نهایی را پیش از ذخیره‌سازی یا استفاده در عملیات، دوباره در سرور اعتبارسنجی کنید.

مصرف توکن و قیمت

گزارش usage در پاسخ، برای پایش مصرف استفاده می‌شود. در صورت ارائه فیلدهای prompt_tokens، completion_tokens و total_tokens، مقدارها را طبق قرارداد همان پاسخ تفسیر کنید. فیلد غایب را صفر فرض نکنید.

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

تعرفه مدل و گزارش مصرف، مرجع محاسبه هزینه در IranNet AI API هستند. حساب مشتری برای پیگیری امور تجاری استفاده می‌شود؛ کلید API نباید برای دریافت تعرفه عمومی در مرورگر قرار گیرد.

مدیریت خطا

پیش از خواندن بدنه پاسخ، وضعیت HTTP و Content-Type را بررسی کنید. دسته‌های زیر راهنمای رسیدگی‌اند، نه اعلام کد اختصاصی یا SLA نهایی سرویس.

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

امنیت کلید API

• کلید فقط در سرور، متغیر محیطی یا مدیریت اسرار نگهداری شود.
• کلید را در Git، مرورگر، اپلیکیشن قابل دانلود یا URL منتشر نکنید.
• در صورت افشا، از مدیریت کلید یا پشتیبانی برای لغو و جایگزینی اقدام کنید.
• در صورت پشتیبانی حساب، کلیدهای محیط توسعه و تولید را جدا کنید.
• بودجه، تعداد مراحل Agent و اندازه ورودی را در برنامه محدود کنید.
• پیش از ارسال داده حساس، شرایط نگهداری و پردازش داده سرویس را بررسی کنید.