مستندات API

API لیمایار با OpenAI سازگار است: در هر کتابخانهٔ سازگار با OpenAI، نشانی پایه را عوض کنید و کلید لیمایار را بدهید. هزینهٔ هر درخواست از اعتبار حساب خود شما کم می‌شود.

شروع سریع

1. وارد اپ لیمایار شوید. دسترسی API به طرح اشتراک شما بستگی دارد.
2. در صفحهٔ تنظیمات، بخش «کلیدهای API»، یک کلید بسازید. کلید فقط همان یک بار نمایش داده می‌شود؛ آن را مثل رمز عبور نگه دارید و در کد سمت مرورگر نگذارید.
3. نشانی پایه را در برنامه‌تان بگذارید و اولین درخواست را بفرستید.

https://api.limayar.com/v1

curl

curl https://api.limayar.com/v1/chat/completions \
  -H "Authorization: Bearer $LIMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "messages": [{"role": "user", "content": "سلام"}]
  }'

Python

from openai import OpenAI

client = OpenAI(base_url="https://api.limayar.com/v1", api_key="YOUR_KEY")

reply = client.chat.completions.create(
    model="MODEL_ID",
    messages=[{"role": "user", "content": "سلام"}],
)
print(reply.choices[0].message.content)

JavaScript

import OpenAI from "openai"

const client = new OpenAI({ baseURL: "https://api.limayar.com/v1", apiKey: process.env.LIMA_API_KEY })

const reply = await client.chat.completions.create({
  model: "MODEL_ID",
  messages: [{ role: "user", content: "سلام" }],
})
console.log(reply.choices[0].message.content)

احراز هویت

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

Authorization: Bearer sk-lima-...

فهرست مدل‌ها

GET /v1/models مدل‌هایی را برمی‌گرداند که همین حالا با این کلید می‌توانید صدا بزنید. مقدار id را در فیلد model بگذارید.

کاتالوگ عمومی مدل‌های متنی و قیمت دقیق اعتبار را پیش از انتخاب مدل ببینید؛ دسترسی نهایی هر حساب را پاسخ احرازشدهٔ همین مسیر تعیین می‌کند.

{
  "object": "list",
  "data": [{ "id": "MODEL_ID", "object": "model", "created": 0, "owned_by": "limayar" }]
}

ساخت پاسخ

POST /v1/chat/completions

حجم بدنهٔ درخواست حداکثر ۱ مگابایت است. پیام‌های system و developer به مدل می‌رسند و دستور پیش‌فرض گفتگوی لیمایار به درخواست‌های API اضافه نمی‌شود.

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1793700000,
  "model": "MODEL_ID",
  "choices": [{
    "index": 0,
    "finish_reason": "stop",
    "message": { "role": "assistant", "content": "سلام! چطور کمکتان کنم؟" }
  }],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 12,
    "total_tokens": 21,
    "completion_tokens_details": { "reasoning_tokens": 0 }
  }
}

• finish_reason یکی از stop، length یا content_filter است. length یعنی پاسخ به سقف max_tokens یا به سقف اعتبار شما رسیده است.
• اگر مدل پس از نوشتن بخشی از پاسخ خطا بدهد، همان بخش با finish_reason برابر length برمی‌گردد، چون هزینه‌اش حساب شده است.
• usage در موارد نادر ممکن است نیاید. اثری بر هزینهٔ درخواست ندارد.
• متن استدلال مدل فرستاده نمی‌شود، ولی توکن‌های آن جزو completion_tokens حساب و مانند خروجی محاسبه می‌شود.

پاسخ تکه‌تکه (stream)

با "stream": true پاسخ به شکل Server-Sent Events می‌آید و با data: [DONE] تمام می‌شود. خط‌هایی که با : شروع می‌شوند فقط اتصال را زنده نگه می‌دارند و باید نادیده گرفته شوند.

stream = client.chat.completions.create(
    model="MODEL_ID",
    messages=[{"role": "user", "content": "سلام"}],
    stream=True,
)
for chunk in stream:
    # The chunk that carries usage has no choices.
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

خطایی که پس از شروع stream رخ بدهد، به شکل یک رویداد {"error": ...} می‌آید و پس از آن [DONE] نمی‌آید. اگر اتصال را قطع کنید، پاسخ متوقف می‌شود و فقط مصرف واقعی تا همان‌جا حساب می‌شود.

آنچه این نسخه ندارد

• این فیلدها خطای 400 می‌گیرند: tools، functions، tool_choice، function_call، response_format، stop، audio، modalities، web_search_options.
• عکس، فایل و صدا در content و پیام‌های نقش tool هم خطای 400 می‌گیرند.
• بقیهٔ پارامترهای OpenAI، مانند temperature، پذیرفته و نادیده گرفته می‌شوند.
• مسیرهای دیگر OpenAI، مانند embeddings، وجود ندارند و خطای 404 می‌گیرند.

اعتبار و هزینه

• پیش از شروع، به اندازهٔ بیشترین هزینهٔ ممکن یا اعتبار موجود شما (هر کدام کمتر باشد) اعتبار کنار گذاشته می‌شود و در پایان فقط مصرف واقعی کم می‌شود. max_tokens کوچک‌تر یعنی مبلغ کمتری کنار گذاشته می‌شود.
• اگر اعتبار کم باشد، پاسخ کوتاه‌تر می‌شود. اگر برای کمترین پاسخ هم کافی نباشد، خطای insufficient_quota می‌گیرید.
• مصرف API و گفتگوهای اپ از یک اعتبار کم می‌شود و سقف‌های طرح شما برای هر دو یکی است.
• قیمت‌ها بر حسب اعتبارند: هر اعتبار برابر ۱٬۰۰۰٬۰۰۰ میکرو‌اعتبار است. نرخ ورودی و خروجی، آستانه‌های بافت و حداقل هزینهٔ هر مدل در کاتالوگ API آمده است. تبدیل ثابت به تومان وجود ندارد؛ مبلغ خرید اعتبار را در حساب خود ببینید.

محدودیت‌ها

• به‌طور پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید، ۱۲۰ درخواست در دقیقه برای هر حساب و ۵ کلید فعال برای هر حساب.
• در هر لحظه دو پاسخ هم‌زمان نوشته می‌شود و گفتگوهای خود شما در اپ هم جزو همین دو تاست.

خطاها

پاسخ خطا هم شکل OpenAI را دارد:

{
  "error": {
    "message": "Invalid API key.",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

نگهداری داده

متن درخواست‌ها ذخیره نمی‌شود و متن پاسخ پس از حدود یکی دو ساعت پاک می‌شود. این درخواست‌ها در فهرست گفتگوهای شما دیده نمی‌شوند.