مستندات توسعه‌دهندگان

API چت

با استفاده از API چت چارتیکال، پیام‌های کاربر را به دستیار هوش مصنوعی ارسال کنید و پاسخ آن را دریافت کنید. می‌توانید دستیار، مدل و ابزارهای موردنیاز را برای هر درخواست مشخص کنید.

نقطه پایانی API

برای احراز هویت، کلید API خود را در هدر x-api-key قرار دهید.

Chat API

متد درخواست

نیازمند کلید API

POSThttps://api.chartical.com/api/v1/chat

برای احراز هویت، کلید API خود را در هدر x-api-key قرار دهید.

ارسال درخواست

درخواست را با فرمت JSON ارسال کنید. در این مثال، یک پیام به دستیار parent-teacher ارسال می‌شود و پاسخ آن دریافت می‌شود.

javascript

const apiKey=process.env.CHARTICAL_API_KEY
if (!apiKey) {
  throw new Error("CHARTICAL_API_KEY is not configured");
}
const headersList = {
  "x-api-key": apiKey,
  "Content-Type": "application/json"
  }

const bodyContent = JSON.stringify({
  "slug":"education-and-research/parent-teacher",
  "model":"smart",
  "tools":{"webSearch":"never"},
  "messages":[{
    "role":"user",
    "content":"Hello!"
  }]
});

const response = await fetch("https://api.chartical.com/api/v1/chat", { 
  method: "POST",
  body: bodyContent,
  headers: headersList
});

const data = await response.text();
console.log(data);

این نمونه برای اجرا در محیط سرور نوشته شده است. متغیر محیطی CHARTICAL_API_KEY را در محیط سرور خود تعریف کنید.

پارامترهای درخواست

بدنه درخواست شامل پارامترهای زیر است. مقادیر نمونه را متناسب با نیاز خود تنظیم کنید.

slugstring

شناسه مسیر دستیار موردنظر را مشخص می‌کند. در این مثال، education-and-research/parent-teacher استفاده شده است.

modelstring

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

toolsobject

تنظیمات ابزارهای قابل استفاده در درخواست را مشخص می‌کند. در این مثال، webSearch روی never تنظیم شده است.

tools.webSearchstring

در نمونه، مقدار never برای این گزینه ارسال می‌شود تا رفتار جست‌وجوی وب مطابق تنظیمات API باشد.

messagesarray

فهرست پیام‌های مکالمه را مشخص می‌کند. هر پیام در این نمونه شامل role برای تعیین نقش فرستنده و content برای متن پیام است.

messages[].rolestring

نقش پیام را مشخص می‌کند. در مثال حاضر از user برای پیام ورودی کاربر استفاده شده است.

messages[].contentstring

متن پیام ارسالی به دستیار است؛ مثلاً Hello! در درخواست نمونه.

پاسخ API

در صورت موفقیت درخواست، پاسخ نمونه شامل وضعیت موفقیت، شناسه درخواست و اطلاعات پیام تولیدشده توسط دستیار است.

json

  "success": true,
  "data": {
    "requestId": "***",
    "messages": {
      "finish_reason": "stop",
      "index": 0,
      "message": {
        "content": "Hello, I am your dedicated assistant. What are we going to do today?",
        "role": "assistant",
        "images": [],
        "thinking_blocks": [],
        "annotations": []
      }
    }
  }
}

فیلدهای پاسخ

مهم‌ترین فیلدهای پاسخ نمونه را در ادامه مشاهده می‌کنید.

success

وضعیت موفقیت درخواست را در پاسخ مشخص می‌کند. در نمونه، مقدار آن true است.

data

اطلاعات اصلی پاسخ API را در خود نگه می‌دارد.

requestId

شناسه مربوط به درخواست را برمی‌گرداند.

messages

اطلاعات پیام خروجی شامل وضعیت پایان تولید، شماره پیام و محتوای پیام دستیار است.

finish_reason

دلیل پایان تولید پاسخ را مشخص می‌کند. در نمونه، مقدار stop است.

message

پیام تولیدشده توسط دستیار را شامل می‌شود. فیلد content متن پاسخ و فیلد role نقش پیام را مشخص می‌کند.

نکات مهم

هنگام استفاده از API این موارد را در نظر داشته باشید.

کلید API را در سمت سرور نگه دارید و آن را در کد فرانت‌اند منتشر نکنید.

مقدار slug را مطابق شناسه دستیار موردنظر تنظیم کنید.

در صورت نیاز به ادامه مکالمه، پیام‌های موردنیاز را در آرایه messages ارسال کنید.

برای بررسی خطاهای درخواست، وضعیت HTTP و بدنه پاسخ را بررسی کنید.

برای یکپارچه‌سازی به راهنمایی نیاز دارید؟

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

ارتباط با پشتیبانی