راهنمای اتصال به API

Decisions API؛ پاسخ بله و خیر، انتخاب و امتیاز با احتمال

خیلی از کارهای هوش مصنوعی در محصول، در اصل یک تصمیم‌اند: این تیکت فوری است؟ این نظر مثبت است یا منفی؟ این درخواست به کدام تیم برود؟ با مدل چت باید از مدل بخواهید جواب را در قالبی خاص بنویسد و بعد متن را تجزیه کنید. مسیر POST /v1/decisions در وان ای آی (1ai) این کار را مستقیم انجام می‌دهد: متن یا شواهد را در input می‌فرستید، پرسش‌ها را در questions تعریف می‌کنید و برای هر پرسش پاسخی با نوع مشخص و احتمال می‌گیرید. مدل‌های تصمیم‌گیری مثل Jev از TypeSafe و Clef از Cloudflare و همچنین openai/gpt-6-luna از همین مسیر پاسخ می‌دهند و هزینه بر اساس توکن ورودی از اعتبار حسابتان کم می‌شود.

چرا با 1ai

پاسخ تایپ‌دار، نه متن آزاد

هر پاسخ نوع مشخصی دارد: predicate با احتمال، choice با گزینه و احتمال هر گزینه، score با امتیاز وزنی. نیازی به تجزیه‌ی متن نیست.

چند پرسش در یک درخواست

همه‌ی پرسش‌ها درباره‌ی همان input در یک فراخوانی جواب می‌گیرند و ترتیب پاسخ‌ها همان ترتیب پرسش‌هاست.

هزینه بر اساس ورودی

مدل‌های تصمیم‌گیری بیشتر بر اساس توکن ورودی حساب می‌شوند؛ مصرف هر درخواست در usage و سرآیند x-1ai-credits می‌آید.

اطمینان قابل اندازه‌گیری

احتمال‌ها و confidence را آستانه بگذارید و پاسخ‌های مردد را به بررسی انسانی بفرستید.

در چند قدم

  1. ۱

    کلید API بسازید

    از بخش توسعه‌دهندگان ← کلیدها یک کلید sk-1ai-… بسازید و در متغیر ONEAI_API_KEY نگه دارید.

  2. ۲

    پرسش‌ها را تعریف کنید

    برای هر تصمیم یک پرسش با type، instructions و یک name یکتا بنویسید؛ برای choice فیلد choices و برای score فیلد levels لازم است.

  3. ۳

    درخواست را بفرستید

    بدنه را به https://1ai.ir/v1/decisions بفرستید و شناسه‌ی مدل را از فهرست پایین همین صفحه بردارید.

  4. ۴

    روی احتمال‌ها تصمیم بگیرید

    برای هر پاسخ آستانه بگذارید؛ مثلاً احتمال بالای ۰٫۸ را خودکار اجرا کنید و بقیه را به اپراتور بسپارید.

مدل‌های تصمیم‌گیری در API

همه‌ی مدل‌ها

GPT-6 Luna

اوپن‌ای‌آی
گفتگو

سریع و بسیار ارزان؛ مدل پیش‌فرض و در سهمیه‌ی رایگان روزانه

۰٫۰۷۵ اعتبار / ۱۰۰۰ توکن خروجی
رایگان روزانهAPI

Jev

تایپ‌سیف
تصمیم‌گیری

تصمیم‌گیری سریع و ارزان با احتمال برای هر پاسخ

۰٫۰۰۶۳ اعتبار / ۱۰۰۰ توکن ورودی
API

Jev Preview

تایپ‌سیف
تصمیم‌گیری

نسخه‌ی پیشین Jev برای مقایسه پس از به‌روزرسانی

۰٫۰۰۶۳ اعتبار / ۱۰۰۰ توکن ورودی
API

Clef

کلادفلر
تصمیم‌گیری

تصمیم‌گیری دقیق روی متن‌ها و تصویرهای بلند

۰٫۰۳۶ اعتبار / ۱۰۰۰ توکن ورودی
API

Clef Flash

کلادفلر
تصمیم‌گیری

نسخه‌ی سبک Clef برای حجم بالا

۰٫۰۱۳۷۷ اعتبار / ۱۰۰۰ توکن ورودی
API

Clef Omni

کلادفلر
تصمیم‌گیری

تصمیم‌گیری روی متن، تصویر، صوت و ویدیو

۰٫۰۲۲۵ اعتبار / ۱۰۰۰ توکن ورودی
API

نمونه درخواست با curl

سه نوع پرسش در یک درخواست: یک گزاره‌ی بله/خیر، یک انتخاب از میان گزینه‌ها و یک امتیاز روی مقیاس سه‌سطحی.

bash
curl https://1ai.ir/v1/decisions \
  -H "Authorization: Bearer $ONEAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "typesafe/jev-latest",
    "input": "سفارشم دو بار از کارتم کم شده و هنوز به دستم نرسیده.",
    "questions": [
      { "name": "urgent", "type": "predicate", "instructions": "آیا این درخواست فوری است؟" },
      { "name": "team", "type": "choice", "instructions": "کدام تیم باید پاسخ دهد؟",
        "choices": [
          { "value": "billing", "description": "پرداخت، فاکتور و بازگشت وجه" },
          { "value": "shipping", "description": "ارسال و تحویل" },
          { "value": "other" }
        ] },
      { "name": "anger", "type": "score", "instructions": "مشتری چقدر ناراضی است؟",
        "levels": [ { "label": "آرام" }, { "label": "ناراضی" }, { "label": "خشمگین" } ] }
    ]
  }'

Python و JavaScript

کتابخانه‌ی رسمی openai هنوز متدی برای این مسیر ندارد؛ با requests یا fetch همان بدنه‌ی JSON را بفرستید.

python
# pip install requests
import os, requests

res = requests.post(
    "https://1ai.ir/v1/decisions",
    headers={"Authorization": f"Bearer {os.environ['ONEAI_API_KEY']}"},
    json={
        "model": "cloudflare/clef-flash",
        "input": "Checkout has been failing for every customer for the last hour.",
        "questions": [
            {"name": "urgent", "type": "predicate", "instructions": "Is this support request urgent?"},
            {"name": "team", "type": "choice", "instructions": "Which team should handle it?",
             "choices": [{"value": "billing"}, {"value": "technical"}, {"value": "sales"}]},
        ],
    },
    timeout=60,
)
res.raise_for_status()
for answer in res.json()["answers"]:
    print(answer["name"], answer.get("probability") or answer.get("choice"))
javascript
const res = await fetch("https://1ai.ir/v1/decisions", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.ONEAI_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    model: "openai/gpt-6-luna",
    input: "The app crashes every time I upload a photo.",
    questions: [{ name: "bug", type: "predicate", instructions: "Is this a bug report?" }],
  }),
});
const { answers, usage } = await res.json();
console.log(answers[0].probability, usage.input_tokens);

قالب پاسخ

answers یک آرایه به ترتیب پرسش‌هاست و name هر پرسش را برمی‌گرداند. پیش از خواندن فیلدها، type هر پاسخ را بررسی کنید.

json
{
  "model": "typesafe/jev-latest",
  "answers": [
    { "type": "predicate", "name": "urgent", "probability": 0.95 },
    { "type": "choice", "name": "team", "choice": "billing",
      "probabilities": [
        { "value": "billing", "probability": 0.93 },
        { "value": "shipping", "probability": 0.06 },
        { "value": "other", "probability": 0.01 }
      ],
      "confidence": 0.88 },
    { "type": "score", "name": "anger", "score": 1.4,
      "probabilities": [
        { "value": 0, "label": "آرام", "probability": 0.1 },
        { "value": 1, "label": "ناراضی", "probability": 0.4 },
        { "value": 2, "label": "خشمگین", "probability": 0.5 }
      ],
      "confidence": 0.62 }
  ],
  "usage": { "input_tokens": 337, "output_tokens": 61, "total_tokens": 398 }
}
نوعفیلدهامعنی
predicateprobabilityاحتمال درست بودن گزاره
choicechoice، probabilities، confidenceگزینه‌ی انتخاب‌شده و احتمال هر گزینه
scorescore، probabilities، confidenceمیانگین وزنی شماره‌ی سطح (از صفر)
refusalnameمدل به این پرسش پاسخ نداد؛ بقیه‌ی پرسش‌ها جواب دارند

فیلدهای درخواست

فیلدنوعتوضیح
modelرشتهشناسه‌ی مدل تصمیم‌گیری یا مدل چتی که از decisions پشتیبانی می‌کند
inputرشته یا آرایهشواهدی که همه‌ی پرسش‌ها درباره‌ی آن هستند
questionsآرایه (۱ تا ۴۰۰)پرسش‌های مستقل
questions[].typepredicate، choice، scoreنوع پاسخ
questions[].instructionsرشتهشرط، قاعده‌ی انتخاب یا معیار امتیاز
questions[].nameرشته، اختیارینام یکتای پرسش در پاسخ
questions[].choicesآرایه (۲ تا ۲۵۵)گزینه‌ها با value و description اختیاری
questions[].levelsآرایه (۲ تا ۱۰)سطح‌ها به ترتیب از کم به زیاد، با label

اشتباه‌های رایج

  • در این مسیر گزینه‌ها choices نام دارند، نه options؛ و criteria مال قالب بومی System One است. درخواستی که این دو را قاطی کند پاسخ 400 می‌گیرد و پیام خطا فیلد درست را نام می‌برد.
  • این مسیر استریم ندارد؛ stream: true پذیرفته نمی‌شود.
  • هر مدلی که در فهرست /v1/models?kind=decision نیست، مثل مدل چت معمولی، خطای model_kind_mismatch می‌گیرد.
  • پرسش‌ها را مستقل بنویسید؛ پاسخ یک پرسش روی پرسش دیگر اثر نمی‌گذارد.

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

تفاوت Decisions API با گرفتن خروجی JSON از مدل چت چیست؟

در خروجی JSON مدل چت متنی می‌نویسد که باید معتبر بودنش را بررسی کنید و احتمالی هم کنار جواب نیست. Decisions API پاسخ را از پیش تایپ‌دار برمی‌گرداند و برای هر گزینه یا سطح احتمال می‌دهد، پس می‌توانید روی اطمینان مدل آستانه بگذارید.

کدام مدل‌ها از این مسیر پاسخ می‌دهند؟

مدل‌های تصمیم‌گیری مثل typesafe/jev-latest و خانواده‌ی cloudflare/clef و مدل چت openai/gpt-6-luna. فهرست زنده را از GET /v1/models?kind=decision بگیرید یا در صفحه‌ی مدل‌ها فیلتر «تصمیم‌گیری» را بزنید.

هزینه‌ی هر درخواست چطور حساب می‌شود؟

بر اساس توکن‌هایی که مدل می‌خواند (متن ورودی، پرسش‌ها و دستورالعمل ثابت مدل) و برای بعضی مدل‌ها توکن خروجی. مقدار دقیق در usage پاسخ و اعتبار کسرشده در سرآیند x-1ai-credits می‌آید.

چند پرسش را می‌توانم در یک درخواست بفرستم؟

قالب تا ۴۰۰ پرسش را می‌پذیرد، ولی سقف واقعی به مدل بستگی دارد؛ مثلاً Clef تا ۶۴ پرسش می‌گیرد. برای کارهای پرحجم درخواست‌ها را کوچک نگه دارید و اندازه‌ای را که لازم دارید آزمایش کنید.

آیا می‌توانم تصویر هم در input بفرستم؟

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

مطالب مرتبط

استفاده از API سازگار با OpenAI در 1ai: راهنمای عملی با Python، Node.js و cURL
توسعه‌دهندگان

استفاده از API سازگار با OpenAI در 1ai: راهنمای عملی با Python، Node.js و cURL

چطور پروژه‌ای را که با کتابخانه‌ی OpenAI نوشته شده، فقط با تغییر آدرس پایه و کلید به 1ai وصل کنید؛ با نمونه کد Python، Node.js و cURL، استریم، فهرست مدل‌ها و مدیریت خطا.

۴ دقیقه مطالعه
کلید API در 1ai: امنیت، محدودیت‌ها و کنترل هزینه
توسعه‌دهندگان

کلید API در 1ai: امنیت، محدودیت‌ها و کنترل هزینه

چطور کلیدهای API را امن نگه دارید و هزینه را مهار کنید: مدل‌های مجاز، سقف اعتبار ماهانه، محدودیت نرخ، تاریخ انقضا، کلیدهای تیمی و گزارش مصرف.

۴ دقیقه مطالعه
همه‌ی امکانات

System One API

قالب بومی همان مدل‌های تصمیم‌گیری: state می‌تواند شیء JSON باشد، پرسش‌ها با شناسه کلید می‌خورند و پاسخ‌ها هم با همان شناسه برمی‌گردند.

Extraction API

فیلدهایی را که لازم دارید با نوعشان تعریف کنید و از متن یا تصویر، مقدار هر فیلد را با اطمینان آن بگیرید؛ فیلدی که در متن نیست null برمی‌گردد.

Moderation API

پیش از نمایش یا پردازش محتوای کاربر، آن را بررسی کنید: برای هر ورودی پرچم ناامن، دسته‌های نقض‌شده و امتیاز هر دسته را بگیرید.

OpenAI SDK

کتابخانه‌ی رسمی openai را در Python و Node.js با تغییر آدرس پایه به 1ai وصل کنید و چت، فراخوانی ابزار، بردار متن، تصویر و صدا را از یک کلید بگیرید.

Decisions API؛ پاسخ بله و خیر، انتخاب و امتیاز با احتمال

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

ساخت کلید API