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

API گزارش درخواست

با استفاده از Report API می‌توانید گزارش مصرف توکن، هزینه و اطلاعات دستیار مربوط به یک درخواست Chat API را دریافت کنید. برای دریافت گزارش، به شناسه درخواست و گذشت زمان لازم برای آماده شدن گزارش نیاز دارید.

نقطه پایانی API

برای دریافت گزارش، شناسه درخواست Chat API را در مسیر درخواست قرار دهید.

Report API

متد درخواست

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

GEThttps://api.chartical.com/api/v1/report/{requestId}

کلید API خود را در هدر x-api-key ارسال کنید.

شناسه درخواست (requestId)

پس از ارسال موفق درخواست به Chat API، شناسه requestId را از پاسخ دریافت کنید و برای گرفتن گزارش همان درخواست نگه دارید.

برای مثال، اگر پاسخ Chat API شامل data.requestId باشد، همان مقدار را در انتهای مسیر گزارش قرار دهید.

GET /api/v1/report/YOUR_REQUEST_ID

چه زمانی گزارش آماده است؟

گزارش پس از گذشت زمان مشخصی از دریافت requestId قابل دریافت خواهد بود.

زمان انتظار

۶۰ ثانیه

تعداد دفعات

۵ بار

محدودیت دریافت گزارش

گزارش پس از گذشت ۶۰ ثانیه از دریافت requestId قابل دریافت است و حداکثر ۵ بار ارائه می‌شود. برای جلوگیری از مصرف دفعات دریافت، درخواست گزارش را بلافاصله پس از دریافت requestId ارسال نکنید.

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

درخواست خود را به Chat API ارسال کنید.

ذخیره requestId

شناسه درخواست را از پاسخ موفق دریافت و ذخیره کنید.

انتظار ۶۰ ثانیه

برای آماده شدن گزارش، حداقل ۶۰ ثانیه از دریافت شناسه صبر کنید.

دریافت گزارش

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

ارسال درخواست گزارش

درخواست گزارش با متد GET ارسال می‌شود. مقدار requestId را با شناسه‌ای جایگزین کنید که از پاسخ موفق Chat API دریافت کرده‌اید.

javascript

const requestId = "YOUR_REQUEST_ID";

const response = await fetch(
  `https://api.chartical.com/api/v1/report/${requestId}`,
  {
    method: "GET",
    headers: {
      "x-api-key": process.env.CHARTICAL_API_KEY,
    },
  }
);

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

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

نمونه پاسخ موفق

پاسخ شامل اطلاعات دستیار، دسته‌بندی، تعداد تلاش‌ها، جزئیات مصرف توکن، ابزارها و هزینه درخواست است.

Json

{
  "success": true,
  "data": {
    "attempts": 1,
    "assistant": {
      "fa": "معلم والدین",
      "en": "Parent Teacher"
    },
    "category": {
      "fa": "تحصیل و پژوهش",
      "en": "Education and research"
    },
    "tokens": {
      "total": 12966,
      "prompt": 10826,
      "completion": 2140,
      "reasoning": 920,
      "cached": 0,
      "prompt_details": {
        "text_tokens": 10826,
        "audio_tokens": 0,
        "image_tokens": 0,
        "video_tokens": 0,
        "cached_tokens": 0,
        "audio_input_duration": 0,
        "cache_creation_tokens": 0
      },
      "completion_details": {
        "text_tokens": 1220,
        "audio_tokens": 0,
        "image_tokens": 0,
        "reasoning_tokens": 920,
        "audio_output_duration": 0,
        "accepted_prediction_tokens": 0,
        "rejected_prediction_tokens": 0
      }
    },
    "tools": {},
    "cost": 0.020180625
  }
}

فیلدهای گزارش

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

attempts

تعداد تلاش‌های ثبت‌شده برای درخواست را نشان می‌دهد.

assistant

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

tokens

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

cost

هزینه ثبت‌شده برای درخواست را نمایش می‌دهد.

tools

اطلاعات ابزارهای ثبت‌شده برای درخواست را برمی‌گرداند. ساختار این بخش به اطلاعات موجود در گزارش بستگی دارد.

tokens

tokens.total

مجموع توکن‌های ثبت‌شده در گزارش.

tokens.prompt

تعداد توکن‌های ورودی پردازش‌شده را نشان می‌دهد.

tokens.completion

تعداد توکن‌های خروجی تولیدشده را نشان می‌دهد.

tokens.reasoning

تعداد توکن‌های مربوط به استدلال را گزارش می‌کند.

tokens.cached

تعداد توکن‌های کش‌شده را مشخص می‌کند.

tokens.prompt_details

جزئیات مصرف ورودی شامل text_tokens، audio_tokens، image_tokens، video_tokens و سایر فیلدهای موجود.

tokens.completion_details

جزئیات مصرف خروجی شامل text_tokens، reasoning_tokens و سایر فیلدهای موجود.

نکات مهم

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

requestId را از پاسخ موفق Chat API دریافت کنید؛ شناسه را حدس نزنید یا از شناسه درخواست دیگری استفاده نکنید.

حداقل ۶۰ ثانیه پس از دریافت requestId صبر کنید و سپس برای گزارش درخواست بفرستید.

گزارش حداکثر ۵ بار قابل دریافت است؛ درخواست‌های تکراری را مدیریت کنید.

کلید API را در هدر x-api-key ارسال کنید و آن را در کد فرانت‌اند قرار ندهید.

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

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

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