مستنداتمرجع اندپوینت‌ها
مدیریت API
مستندات API / مرجع اندپوینت‌ها

مرجع کامل اندپوینت‌ها

هدرها، پارامترها، فیلدهای اجباری و اختیاری، محدودیت‌ها و نمونهٔ پاسخ تمام مسیرهای REST API v1.

مشترک بین همهٔ مسیرها

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

تمام endpointها به Bearer API Key نیاز دارند. مسیر POST علاوه بر آن باید Content-Type صحیح داشته باشد.
Authorizationheaderاجباری
کلید API فعال. فاصلهٔ بین Bearer و کلید الزامی است.
Bearer kc_live_...
Content-Typeheaderاجباری
نوع بدنهٔ درخواست چت.
پیش‌فرض: application/jsonفقط برای POST
POST/chat/completions

ساخت پاسخ چت

از یک پیام ساده یا تاریخچهٔ کامل گفتگو، پاسخ متنی تولید می‌کند.

Request body

modelstringاختیاری
شناسهٔ مدل. مقدارهای مجاز را از GET /models بخوانید.
پیش‌فرض: gpt
messagesMessage[]شرطی
تاریخچهٔ مرتب گفتگو. پیام‌های نامعتبر یا خالی حذف می‌شوند.
در نبود prompt / message / input اجباری است.
promptstringشرطی
ورودی تک‌پیامی جایگزین messages. فیلدهای message و input نیز همین نقش را دارند.
حداکثر ۱۲٬۰۰۰ کاراکتر
streambooleanاختیاری
streaming در REST API عمومی v1 فعال نیست.
پیش‌فرض: falsetrue باعث خطای 400 می‌شود.

ساختار هر Message

rolestringاجباری
system رفتار پاسخ را تنظیم می‌کند، user ورودی کاربر و assistant پاسخ‌های قبلی را مشخص می‌کند.
system | user | assistant
contentstringاجباری
متن غیرخالی پیام. فضای ابتدا و انتها حذف می‌شود.
حداکثر ۱۲٬۰۰۰ کاراکتر برای هر پیام
نمونهٔ درخواست
curl -X POST https://kujichat.com/api/v1/chat/completions \
  -H "Authorization: Bearer $KUJICHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kuji-v0",
    "messages": [
      {"role": "system", "content": "کوتاه و دقیق پاسخ بده."},
      {"role": "user", "content": "REST API چیست؟"}
    ]
  }'

Response · 200

پاسخ موفقJSON
{
  "id": "chatcmpl_4a2f...",
  "object": "chat.completion",
  "created": 1786642500,
  "model": "kuji-v0",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "REST API روشی استاندارد برای ارتباط سرویس‌ها از طریق HTTP است."
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 21,
    "total_tokens": 39,
    "credits": 2,
    "billing_source": "plan"
  }
}
فیلدهای پاسخ
idstring
شناسهٔ یکتای completion با پیشوند chatcmpl_.
objectstring
همیشه chat.completion است.
creatednumber
زمان ساخت پاسخ به‌صورت Unix timestamp.
modelstring
شناسهٔ مدل استفاده‌شده.
choicesarray
آرایهٔ خروجی؛ در نسخهٔ فعلی پاسخ اصلی در عضو اول است.
choices[].message.contentstring
متن تولیدشده توسط مدل.
choices[].finish_reasonstring
دلیل پایان پاسخ؛ در نسخهٔ فعلی stop.
usage.prompt_tokensnumber
برآورد توکن‌های ورودی.
usage.completion_tokensnumber
برآورد توکن‌های خروجی.
usage.total_tokensnumber
مجموع برآورد توکن‌های ورودی و خروجی.
usage.creditsnumber
اعتبار کسرشده بر اساس مدل.
usage.billing_sourcestring
منبع کسر هزینه: plan یا api_balance.
GET/models

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

فقط مدل‌هایی را برمی‌گرداند که برای پلن و کلید فعلی قابل استفاده‌اند.

RequestcURL
curl https://kujichat.com/api/v1/models \
  -H "Authorization: Bearer $KUJICHAT_API_KEY"
Response · 200JSON
{
  "object": "list",
  "data": [{
    "id": "kuji-v0",
    "object": "model",
    "display_name": "Kuji v0",
    "provider": "kujichat",
    "type": "chat",
    "description": "مدل عمومی گفتگو",
    "credits_per_request": 2,
    "capabilities": {
      "chat": true,
      "reasoning": false,
      "vision": false,
      "streaming": false,
      "tools": false,
      "json_output": false
    },
    "pricing": {
      "billing_unit": "request",
      "credits": 2,
      "payg_amount": 200,
      "currency": "IRT"
    },
    "available": true,
    "status": "available"
  }]
}
فیلدهای هر مدل
idstring
شناسه‌ای که باید در فیلد model درخواست چت بفرستید.
display_namestring
نام مناسب نمایش در رابط کاربری.
providerstring
شناسهٔ سرویس‌دهندهٔ مدل.
descriptionstring
توضیح کوتاه کاربرد مدل.
credits_per_requestnumber
هزینهٔ ثابت هر درخواست برحسب اعتبار.
capabilitiesobject
وضعیت chat، reasoning، vision، streaming، tools و json_output.
pricing.payg_amountnumber
هزینهٔ pay-as-you-go به تومان.
availableboolean
آماده‌بودن مدل برای کلید فعلی.
GET/models/{model_id}

جزئیات یک مدل

همان ساختار مدل را برای یک شناسهٔ مشخص برمی‌گرداند؛ پاسخ داخل data قرار نمی‌گیرد.

RequestcURL
curl https://kujichat.com/api/v1/models/kuji-v0 \
  -H "Authorization: Bearer $KUJICHAT_API_KEY"
GET/usage

مصرف و محدودیت فعلی

وضعیت سهمیهٔ ماهانه، موجودی pay-as-you-go، پنجرهٔ rate limit و کلید فعال را برمی‌گرداند.

RequestcURL
curl https://kujichat.com/api/v1/usage \
  -H "Authorization: Bearer $KUJICHAT_API_KEY"
Response · 200JSON
{
  "object": "usage",
  "plan": "pro",
  "period": "2026-08",
  "api_credits": {
    "used": 128,
    "limit": 1000,
    "remaining": 872
  },
  "pay_as_you_go": { "balance": 2400 },
  "rate_limit": {
    "limit_per_minute": 240,
    "remaining": 238,
    "resets_at": "2026-08-13T18:32:00.000Z"
  },
  "key": { "id": "...", "name": "Production" }
}
فیلدهای مصرف
periodstring
دورهٔ ماهانه با فرمت YYYY-MM.
api_credits.usednumber
اعتبار مصرف‌شده در دورهٔ جاری.
api_credits.limitnumber
سهمیهٔ ماهانهٔ پلن.
api_credits.remainingnumber
سهمیهٔ ماهانهٔ باقی‌مانده؛ منفی نمی‌شود.
pay_as_you_go.balancenumber
موجودی جداگانهٔ API برای مصرف پس از سهمیه.
rate_limit.limit_per_minutenumber
سقف درخواست در یک دقیقه.
rate_limit.remainingnumber
تعداد درخواست باقی‌مانده در پنجرهٔ فعلی.
rate_limit.resets_atstring
زمان ISO بازنشانی پنجرهٔ فعلی.
key.namestring
نام کلیدی که درخواست را ارسال کرده است.
نمای کلی مستنداتمدیریت کلید API