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

System One API؛ قالب بومی مدل‌های تصمیم‌گیری Jev و Clef

مدل‌های Jev و Clef دو قالب درخواست دارند. [Decisions API](/developers/decisions-api) قالب سازگار با OpenAI است و برای بیشتر برنامه‌ها کافی است. مسیر POST /v1/systemone قالب بومی System One را در وان ای آی (1ai) ارائه می‌کند: شواهد را در state می‌فرستید که می‌تواند متن، شیء یا آرایه‌ی JSON باشد، پرسش‌ها یک شیء با شناسه‌ی دلخواه‌اند و پاسخ هر پرسش زیر همان شناسه برمی‌گردد. اگر کدتان پیش‌تر با System One نوشته شده یا state ساخت‌یافته دارید، این مسیر بدون تبدیل کار می‌کند. هزینه مثل Decisions بر اساس توکن ورودی از اعتبار حساب کم می‌شود.

چرا با 1ai

state ساخت‌یافته

به جای یک متن، شیء JSON بفرستید؛ مثلاً متن تیکت همراه با پلن مشتری و تعداد تیکت‌های باز.

پاسخ با کلید پرسش

answers شیئی است که کلیدهایش همان شناسه‌ی پرسش‌هاست؛ بدون نیاز به نگه‌داشتن ترتیب.

سه نوع پرسش

noul برای بله/خیر با احتمال، choice برای انتخاب و score برای امتیاز روی سطح‌های مرتب.

همان مدل‌ها، همان قیمت

هر مدل تصمیم‌گیری فهرست پایین هم با این مسیر و هم با Decisions API کار می‌کند.

در چند قدم

  1. ۱

    کلید API بسازید

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

  2. ۲

    state را آماده کنید

    متن یا شیء JSON شواهد را در state بگذارید؛ عدد یا بولین تنها پذیرفته نمی‌شود.

  3. ۳

    پرسش‌ها را با شناسه بنویسید

    questions شیئی از ۱ تا ۶۴ پرسش است و شناسه‌ها فقط حرف، عدد، نقطه، خط تیره و زیرخط دارند.

  4. ۴

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

    هر پاسخ را با answers[id] بخوانید و پیش از خواندن فیلدها type را بررسی کنید.

مدل‌های سازگار با System One

همه‌ی مدل‌ها

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/systemone \
  -H "Authorization: Bearer $ONEAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "cloudflare/clef-flash",
    "state": "سفارشم دو بار از کارتم کم شده و هنوز به دستم نرسیده.",
    "questions": {
      "urgent": { "type": "noul", "instructions": "آیا این درخواست فوری است؟" },
      "team": { "type": "choice", "instructions": "کدام تیم باید پاسخ دهد؟",
        "criteria": { "billing": "پرداخت و بازگشت وجه", "shipping": "ارسال و تحویل", "other": null } },
      "anger": { "type": "score", "instructions": "مشتری چقدر ناراضی است؟",
        "criteria": ["آرام", "ناراضی", "خشمگین"] }
    }
  }'

state ساخت‌یافته در Python

python
# pip install requests
import os, requests

res = requests.post(
    "https://1ai.ir/v1/systemone",
    headers={"Authorization": f"Bearer {os.environ['ONEAI_API_KEY']}"},
    json={
        "model": "typesafe/jev-latest",
        "state": {"ticket": "Payment failed twice", "plan": "pro", "open_tickets": 3},
        "questions": {
            "escalate": {"type": "noul", "instructions": "Should this ticket be escalated?"},
        },
    },
    timeout=60,
)
res.raise_for_status()
print(res.json()["answers"]["escalate"]["noul"])

قالب پاسخ

json
{
  "model": "cloudflare/clef-flash",
  "answers": {
    "urgent": { "type": "noul", "noul": 0.96 },
    "team": { "type": "choice", "choice": "billing", "confidence": 0.77,
      "probabilities": { "billing": 0.9 } },
    "anger": { "type": "score", "score": 1.6, "confidence": 0.52,
      "probabilities": { "0": 0.08, "1": 0.24, "2": 0.68 } }
  },
  "usage": { "input_tokens": 199, "output_tokens": 0 }
}
نوعفیلدهامعنی
noulnoulاحتمال درست بودن گزاره
choicechoice، confidence، probabilitiesگزینه‌ی انتخاب‌شده؛ نقشه‌ی احتمال ممکن است همه‌ی گزینه‌ها را نداشته باشد
scorescore، confidence، probabilitiesمیانگین وزنی شماره‌ی سطح (از صفر) و احتمال هر سطح

تفاوت با Decisions API

/v1/decisions/v1/systemone
شواهدinputstate (متن، شیء یا آرایه)
پرسش‌هاآرایه با nameشیء با شناسه
گزارهpredicatenoul
گزینه‌هاchoices: [{ value }]criteria: { گزینه: توضیح }
سطح‌هاlevels: [{ label }]criteria: ["…"]
پاسخآرایه به ترتیب پرسششیء با شناسه
مدل چت gpt-6-lunaداردندارد

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

  • criteria در پرسش choice شیء است (گزینه → توضیح یا null) و در پرسش score آرایه‌ی مرتب؛ برعکس فرستادن آن پاسخ 400 می‌گیرد.
  • choices و levels مال Decisions API است و اینجا پذیرفته نمی‌شود.
  • messages، temperature، tools و stream در این مسیر معنی ندارند.
  • Clef برای instructions مقدار غیرخالی می‌خواهد؛ همیشه آن را پر کنید.

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

System One را انتخاب کنم یا Decisions API؟

اگر کد تازه می‌نویسید یا می‌خواهید gpt-6-luna را هم امتحان کنید، Decisions API ساده‌تر است. اگر state شما شیء JSON است یا کد موجودتان با قالب System One نوشته شده، این مسیر را به کار ببرید.

نقشه‌ی احتمال در پرسش choice چرا همه‌ی گزینه‌ها را ندارد؟

مدل‌ها گاهی فقط بخشی از گزینه‌ها را در probabilities برمی‌گردانند. گزینه‌ی انتخاب‌شده همیشه در choice هست و می‌توانید باقی‌مانده‌ی احتمال را میان گزینه‌های غایب تقسیم کنید.

سقف تعداد پرسش و طول state چقدر است؟

تا ۶۴ پرسش در هر درخواست. طول state به پنجره‌ی متن مدل بستگی دارد؛ Clef-flash پنجره‌ی کوچک‌تری از Clef دارد، پس برای متن‌های بلند مدل بزرگ‌تر را انتخاب کنید.

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

بر اساس توکن ورودی که در usage.input_tokens می‌آید؛ اعتبار کسرشده‌ی هر درخواست در سرآیند x-1ai-credits است.

مطالب مرتبط

استفاده از 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 را امن نگه دارید و هزینه را مهار کنید: مدل‌های مجاز، سقف اعتبار ماهانه، محدودیت نرخ، تاریخ انقضا، کلیدهای تیمی و گزارش مصرف.

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

Decisions API

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

Extraction API

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

OpenAI SDK

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

System One API؛ قالب بومی مدل‌های تصمیم‌گیری Jev و Clef

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

ساخت کلید API