دیالو بوکس مستندات API
پنل

پایگاه دانش کتاب‌ها برای دستیار صوتی

دیالو بوکس یک سرویس مستقل است: شما فایل کتاب را می‌فرستید، سرویس متن را استخراج و بخش‌بندی می‌کند، قطعه‌های ۶۰۰ تا ۷۰۰ نویسه‌ای را نمایه می‌کند و برای هر کتاب یک «کارت» گفتاری می‌نویسد (معرفی، مخاطب، موضوع‌ها، خلاصهٔ بخش‌ها، پرسش‌های محتمل). دستیار صوتی، وقتی مشتری نام کتابی را می‌برد، با یک فراخوانی هم کتاب را پیدا می‌کند و هم بندهای مرتبط با سوالش را می‌گیرد و در دو سه جمله جواب می‌دهد.

احراز هویت

هر درخواست به /v1/… باید هدر Authorization: Bearer bk_live_… داشته باشد. کلید را از دیالو بگیرید؛ کلید به حساب شما محدود است و فقط کتاب‌های خودتان را می‌بیند.

BASE=https://books.dialoai.net
KEY=bk_live_xxx
curl -s $BASE/v1/me -H "Authorization: Bearer $KEY"

کتاب‌ها

POST /v1/books (multipart) — بارگذاری کتاب. فیلدها: file (الزامی؛ pdf/docx/doc/rtf/epub/txt، حداکثر ۱۲۰ مگابایت)، title، author، publisher، translator، isbn، external_id، external_url، tags (با ویرگول). پاسخ: شیء کتاب با status: queued.

curl -s -X POST $BASE/v1/books -H "Authorization: Bearer $KEY" \
  -F "file=@book.docx" -F "title=مرغ سیاه هم تخم سفید می‌کند" -F "author=…" \
  -F "external_url=https://www.faraketab.ir/book/1234"

GET /v1/books?q=&status= — فهرست. GET /v1/books/{id} — یک کتاب با کارت کامل. PATCH /v1/books/{id} — ویرایش مشخصات یا کارت ({"card": {"pitch": "…", "overview": "…", "faq": [...]}}). DELETE /v1/books/{id}. POST /v1/books/{id}/reprocess (بدنهٔ {"rebuild_card": true} کارت را هم از نو می‌نویسد). GET /v1/books/{id}/chunks?chapter=&limit= — قطعه‌های نمایه‌شده.

وضعیت‌ها: queued → extracting → indexing → carding → ready یا failed با error و توضیح فارسی در stage_note.

جست‌وجو و پرسش (آنچه دستیار صدا می‌زند)

GET /v1/find?q= — کتاب را از روی چیزی که مشتری گفته پیدا می‌کند (شباهت سه‌حرفی روی عنوان و نویسنده؛ غلط‌های تشخیص گفتار را تحمل می‌کند). پاسخ: candidates با امتیاز و confident.

POST /v1/ask — یک فراخوانی برای همه‌چیز: {"book": "نام کتاب یا book_id", "question": "…", "k": 4}. اگر کتاب یکتا پیدا شود، found: true با card (چکیدهٔ گفتاری) و passages (بندهای مرتبط با نام بخش) برمی‌گردد؛ اگر چند کتاب نزدیک باشند ambiguous: true و candidates تا دستیار یک سوال بپرسد؛ اگر نباشد found: false.

curl -s -X POST $BASE/v1/ask -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"book":"همیشه مردها مقصرند","question":"این کتاب برای زوج‌های جوان مناسبه؟"}'

{
  "found": true,
  "book": {"book_id": "…", "title": "همیشه مردها مقصرند", "author": "…", "chapters": 14},
  "card": "معرفی دو جمله‌ای…\nمخاطب: …\nموضوع‌ها: …",
  "passages": [{"chapter": "فصل سوم: …", "text": "…", "score": 0.0325}, …],
  "ms": 96
}

POST /v1/books/{id}/ask — همان پرسش برای کتابی که شناسه‌اش را دارید. GET /v1/books/{id}/card — کارت کامل.

گزارش

GET /v1/usage — شمار جست‌وجوها و پرسش‌های ۳۰ روز اخیر و ۵۰ پرسش آخر.

نکته‌ها