مدل‌ها

استاندارد API مدل‌ها

API مدل‌های ما، مهم‌ترین اطلاعات همهٔ LLMها را همین که تأیید کنیم، به‌صورت رایگان در دسترس قرار می‌دهد.

شکل پاسخ API

API مدل‌ها شکل پاسخ JSON استانداردی برمی‌گرداند که فرادادهٔ کاملی برای هر مدل موجود فراهم می‌کند. این schema در edge کش می‌شود و برای یکپارچگیِ قابل اعتماد با اپلیکیشن‌های production طراحی شده است.

شیء ریشهٔ پاسخ (Root Response Object)

{
  "object": "list",
  "data": [
    /* Array of Model objects */
  ]
}

فهرست، کامل و بدون صفحه‌بندی برگردانده می‌شود و همهٔ مدل‌ها در آرایهٔ data قرار دارند.

Schema شیء Model

هر مدل در آرایهٔ data شامل فیلدهای استاندارد زیر است:

شیء Architecture

{
  "input_modalities": string[], // Supported input types: ["file", "image", "text"]
  "output_modalities": string[], // Supported output types: ["text"]
  "tokenizer": string,          // Tokenization method used
  "instruct_type": string | null // Instruction format type (null if not applicable)
}

شیء Pricing

همهٔ قیمت‌ها به دلار برای هر توکن/درخواست/واحد است.

{
  "prompt": string,           // Cost per input token
  "completion": string,       // Cost per output token
  "request": string,          // Fixed cost per API request
  "image": string,           // Cost per image input
  "web_search": string,      // Cost per web search operation
  "internal_reasoning": string, // Cost for internal reasoning tokens
  "input_cache_read": string,   // Cost per cached input token read
  "input_cache_write": string,  // Cost per cached input token write
  "overrides": PricingOverride[] // Optional conditional pricing overrides (see below)
}

تغییرات قیمت (Pricing Overrides)

برخی از endpointها در شرایط خاص نرخ متفاوتی دارند؛ مانند قیمت‌گذاریِ context طولانی بالای یک آستانهٔ توکن، یا قیمت‌گذاری زمانی که ساعات پیک گران‌تر است. این موارد در آرایهٔ اختیاری pricing.overrides ظاهر می‌شوند:

{
  // Condition: applies when total prompt tokens are strictly greater than this threshold
  "min_prompt_tokens": 200000,

  // Condition: applies when current UTC time is within this daily window
  "utc_start": 1630,  // Inclusive start as HHMM clock (16:30 UTC)
  "utc_end": 30,      // Exclusive end as HHMM clock (00:30 UTC; the window may wrap past midnight)

  // Overridden prices, same keys and units as the base pricing object
  "prompt": "0.000005",
  "completion": "0.00002",
  "input_cache_read": "0.0000005",
  "input_cache_write": "0.00000625"
}

یک ورودی زمانی اعمال می‌شود که همهٔ فیلدهای شرطش با درخواست مطابقت داشته باشند. وقتی چند ورودی اعمال شوند، ورودی‌های بعدی به‌ازای هر کلید برندهٔ نهایی‌اند. کلیدهای قیمتی که در یک ورودی غایب‌اند، قیمت پایه را ارث می‌برند. کلیدهای سطح بالای pricing همیشه قیمتی را نشان می‌دهند که در شرایط پیش‌فرض برای درخواست اعمال می‌شود؛ overrides استثناهای شرطی را حمل می‌کند.

برای نمونه، مدلی که به‌طور عادی ۲٫۵۰ دلار به‌ازای هر میلیون توکن ورودی هزینه دارد و بالای ۲۰۰٬۰۰۰ توکن ورودی ۵ دلار:

"pricing": {
  "prompt": "0.0000025",
  "completion": "0.00001",
  "overrides": [
    {
      "min_prompt_tokens": 200000,
      "prompt": "0.000005",
      "completion": "0.00002"
    }
  ]
}

شرط‌های پنجرهٔ زمانی، قیمت‌گذاری پیک/غیرپیک را بیان می‌کنند. آرایهٔ overrides همیشه همهٔ پنجره‌ها (پیک و غیرپیک) را فهرست می‌کند و کل ۲۴ ساعت شبانه‌روز را می‌پوشاند؛ یعنی برنامهٔ کامل قیمت‌گذاری همواره قابل بازیابی است، حتی مدتی پس از تولید پاسخ. مثلاً مدلی که بین ۱۶:۳۰ تا ۰۰:۳۰ به وقت UTC با نصف قیمت فروخته می‌شود:

"pricing": {
  // Top-level prices always reflect the window that applies right now
  // (here: the current UTC time is between 00:30 and 16:30)
  "prompt": "0.00000028",
  "completion": "0.00000042",
  "overrides": [
    {
      "utc_start": 30,
      "utc_end": 1630,
      "prompt": "0.00000028",
      "completion": "0.00000042"
    },
    {
      "utc_start": 1630,
      "utc_end": 30,
      "prompt": "0.00000014",
      "completion": "0.00000021"
    }
  ]
}

شیء Top Provider

{
  "context_length": number,        // Provider-specific context limit
  "max_completion_tokens": number, // Maximum tokens in response
  "is_moderated": boolean         // Whether content moderation is applied
}

شیء Benchmarks

فقط روی مدل‌هایی وجود دارد که در بنچمارک‌های شخص ثالث ارزیابی شده‌اند. در حال حاضر شامل رتبه‌بندی‌های Design Arena است.

{
  "design_arena": [
    {
      "arena": string,    // Arena type (e.g. "models", "builders", "agents")
      "category": string, // Category within the arena (e.g. "website", "gamedev")
      "elo": number,      // ELO rating from head-to-head arena battles
      "win_rate": number,  // Win rate percentage
      "rank": number      // Rank within this arena+category (1 = highest ELO)
    }
  ]
}

رتبه‌بندی‌ها از ارائه‌دهنده‌های بالا‌دستی دریافت می‌شوند و فقط روی مدل‌های دارای دادهٔ بنچمارک حاضرند؛ مدل‌های بدون داده، فیلد benchmarks را کلاً حذف می‌کنند.

# Find models with benchmark data
curl -s "https://app.asha-ai.ir/v1/models" | jq '.data[] | select(.benchmarks) | {id, benchmarks}'

پارامترهای پشتیبانی‌شده

آرایهٔ supported_parameters مشخص می‌کند کدام پارامترهای سازگار با OpenAI با هر مدل کار می‌کنند:

• tools — قابلیت فراخوانی تابع
• tool_choice — کنترل انتخاب ابزار
• max_tokens — محدودکردن طول پاسخ
• temperature — کنترل تصادف
• top_p — نمونه‌گیری هسته (nucleus sampling)
• reasoning — حالت استدلال داخلی
• include_reasoning — درج استدلال در پاسخ
• structured_outputs — اعمال schema JSON
• response_format — مشخص‌کردن قالب خروجی
• stop — دنباله‌های توقف سفارشی
• frequency_penalty — کاهش تکرار
• presence_penalty — تنوع موضوعی
• seed — خروجی‌های قطعی

توکنایز کردن متن در مدل‌های مختلف

مدل‌های مختلف متن را به شیوه‌های متفاوتی توکنایز می‌کنند؛ برخی متن را به تکه‌های چند کاراکتری می‌شکنند (GPT، Claude، Llama و…) و برخی دیگر به‌صورت کاراکتری توکنایز می‌کنند (PaLM). یعنی شمارش توکن (و در نتیجه هزینه) بین مدل‌ها متفاوت خواهد بود، حتی وقتی ورودی و خروجی یکسان باشند. هزینه‌ها بر اساس توکن‌سازِ مدلِ مورد استفاده نمایش داده و محاسبه می‌شوند. می‌توانید از فیلد usage در پاسخ، شمار توکن‌های ورودی و خروجی را بگیرید.

اگر مدل یا ارائه‌دهنده‌ای مورد نظر دارید که در آشا وجود ندارد، لطفاً از صفحهٔ پشتیبانی به ما اطلاع دهید.