API تشخیص موسیقی ملویاب

کلید مشتری را از مدیر بگیرید. فایل را مستقیماً در بدنهٔ درخواست بفرستید. کلید را در URL نگذارید.

curl --fail-with-body -X POST 'https://YOUR_DOMAIN/v1/recognize-clip?mode=auto' \
  -H "Authorization: Bearer $MELOYAB_API_KEY" \
  -H 'Content-Type: application/octet-stream' \
  --data-binary @clip.mp4

برای فایل صوتی، /v1/recognize هم موجود است. mode می‌تواند auto یا chromaprint باشد. تمام جست‌وجوها با Chromaprint انجام می‌شوند؛ نام‌های قدیمی sequential و adaptive فقط سازگاری رابط را حفظ می‌کنند. ورودی URL و multipart/form-data در این قرارداد پشتیبانی نمی‌شود.

GET /v1/capabilities محدودیت‌های این نصب و GET /v1/tracks/{track_id} اطلاعات و لینک آهنگ را با همان کلید برمی‌گردانند. کلیدها سقف‌های قراردادی دقیقه و هم‌زمانی جداگانه دارند؛ اعمال آن‌ها در کنترل مشترک قابل انتخاب است. هدر X-Meloyab-Delivery مشخص می‌کند فایل از disk_cache، telegram_cache_fill یا telegram_stream آمده است. تعویض کلید از پنل، کلید قبلی را نامعتبر می‌کند.

کنترل ظرفیت در نسخهٔ ۰.۹.۲۰

پیش‌فرض، مصرف واقعی منابع است: سقف فنی worker، رزرو فرضی حافظه و مهلت ۸ ثانیه‌ای شروع جست‌وجو اعمال نمی‌شوند. آستانه‌های CPU و RAM در پنل کنترل مشترک تنظیم می‌شوند. سقف دقیقه و هم‌زمانی مشتری فقط با فعال‌کردن گزینهٔ قراردادی آن اعمال می‌شود. در capabilities مقدار null برای سقف یعنی سقف عددی تنظیم‌شده اعمال نمی‌شود؛ منابع فیزیکی همچنان محدودند. جست‌وجوی ایندکس در این حالت کامل است. هدر X-Concurrency-Enforced و فیلدهای customer_rpm_enforced و customer_concurrency_enforced سیاست فعال را مشخص می‌کنند.

ترتیب و تعداد نتایج

نتایج بر اساس امتیاز شباهت Chromaprint از زیاد به کم مرتب می‌شوند. در تنظیمات هسته‌ها حالت top و max_results تعداد نتایج خروجی را پس از ادغام بخش‌ها و حذف شناسه‌های تکراری محدود می‌کند. match_count تعداد نمایش و total_match_count تعداد کل تطابق معتبر است. results_truncated محدودشدن نمایش را مشخص می‌کند؛ جست‌وجو به علت این سقف زودتر متوقف نمی‌شود. سیاست all_unique هر کلید، همچنان همهٔ نتایج متمایز را درخواست می‌کند؛ برای پیروی از سقف پنل، results کلید باید configured باشد.

جواب

status وضعیت تشخیص، method هستهٔ واقعی، match اطلاعات آهنگ و quality معیار تطابق همان هسته است. elapsed_ms مدت پردازش فعلی سرور و request_id شناسهٔ پیگیری است. cache.hit استفاده از کش معتبر را نشان می‌دهد؛ زمان تلاش‌های کش‌شده در source_elapsed_ms می‌آید.

match_percent برای Chromaprint شباهت بیت‌های فینگر، احتمال صحیح بودن جواب نیست؛ confidence_percent برابر null است.

match.track_id شناسهٔ ثابت آهنگ در ملویاب است. match.archive نشانی فایل در تلگرام را می‌دهد: chat_id، message_id، kind و در صورت دریافت از ربات، file_id، bot_id و file_unique_id. file_id فقط برای bot_id مربوطه قابل استفاده است؛ file_unique_id برای دانلود نیست. ربات پاسخ‌دهنده پس از مشاهدهٔ پست آرشیو، اولین آپلود یا فوروارد اول فایل بزرگ، file_id مخصوص خودش را ثبت و استفاده می‌کند؛ حالت copyMessage نیز قابل انتخاب است. post_url لینک پست کانال است؛ کانال خصوصی نیازمند عضویت است. دریافت با حساب خواننده به ربات قدیمی وابسته نیست.

در توافق، method برابر consensus و match.quality برابر null است؛ معیار و offset هر هسته در match.evidence گزارش می‌شود. attempts نتیجهٔ هر هسته، candidates نامزدهای پذیرفته‌شده و complete کامل بودن بررسی را نشان می‌دهند. امتیاز هسته‌ها جمع نمی‌شود.

دانلود آهنگ

match.download_url یک لینک امضاشده با اعتبار پنج دقیقه است. همان لینک را می‌توان به مرورگر داد؛ در حالت پیش‌فرض فایل از کش دیسکی محدود پاسخ داده می‌شود؛ اولین دریافت فایل کامل را از تلگرام می‌گیرد و صحت آن را بررسی می‌کند. برای ساخت لینک تازه GET /v1/tracks/{track_id}/download-link را با کلید مشتری صدا بزنید. GET /v1/tracks/{track_id}/download نیز مستقیماً با Bearer کار می‌کند. Range تک‌بازه برای ادامهٔ دانلود پشتیبانی می‌شود. ابطال یا چرخش کلید، لینک‌های قبلی همان مشتری را نامعتبر می‌کند. لینک را مانند کلید موقت محافظت کنید.

اختلاف هسته‌ها

conflict_policy از تنظیمات مدیر می‌آید: reject نتیجهٔ منتخب نمی‌دهد؛ priority با selection_reason=configured_engine_priority پاسخ هستهٔ مقدم را انتخاب می‌کند و agreement.conflict=true باقی می‌ماند؛ all با status=multiple_matches پاسخ‌ها را در matches و نام هر هسته برمی‌گرداند. در حالت all هیچ آهنگ واحدی به‌عنوان قطعی انتخاب نشده است.

نگهداری داده

فایل صوتی درخواست پس از عملیات پاک می‌شود. گزارش درخواست با request_id در پنل قابل پیگیری است؛ مدت پیش‌فرض نگهداری برای موفق یک ساعت و خطا ۲۴ ساعت است. بدنه، توکن و لینک امضاشده ثبت نمی‌شوند. دانلودهای فعال قطعه‌ای خوانده می‌شوند؛ فایل‌های کش روی دیسک‌اند.

وضعیت‌ها

matched: پیدا شد؛ no_match: نتیجهٔ پذیرفته‌شده نیست؛ search_limited: بودجهٔ پردازش کافی نبود؛ not_ready: ایندکس/سرویس قابل استفاده نیست؛ conflict: هسته‌ها آهنگ‌های متفاوت یافته‌اند؛ inconclusive: توافق یا بررسی کافی نیست؛ result_reason دلیل را مشخص می‌کند. engine_unavailable یعنی خطای هسته و insufficient_agreement یعنی توافق ناکافی پس از بررسی. در دو حالت آخر match برابر null است و ارسال خودکار انجام نمی‌شود.

401: کلید نامعتبر یا غیرفعال؛ 413: فایل بزرگ؛ 422: صوت نامعتبر یا مدت بیش از حد؛ 408: مهلت دریافت بدنه؛ 429: سقف دقیقه یا هم‌زمانی مشتری؛ 503: ظرفیت پر، نگهداری یا ایندکس آماده نیست. برای تلاش مجدد Retry-After را رعایت کنید و retry نامحدود نکنید. خطاها detail، error.code، error.retryable و request_id دارند. هدرهای X-Request-ID، X-RateLimit-Reset و Server-Timing برای پیگیری در دسترس‌اند. X-Meloyab-Version نسخهٔ سرویس است. در تشخیص، X-Concurrency-Limit سقف مشتری و X-Concurrency-Active تعداد فعال همان مشتری در لحظهٔ پذیرش یا رد است. customer_concurrency_exceeded محدودیت خود API ملویاب است و با ۴۲۹ تلگرام فرق دارد. سقف دقیقه و هم‌زمانی مستقل‌اند؛ در حالت بودجه‌ای، سقف مشتری و ظرفیت کل workerها جداگانه اعمال می‌شوند؛ در حالت مصرف واقعی، قرارداد مشتری اختیاری است و سقف فنی ثابت ندارد.

پیش‌فرض نصب ورودی ۲۵۶ MiB، کلیپ حداکثر ۱۸۰ ثانیه و نمونه‌برداری حداکثر سه بخش است؛ مدیر می‌تواند محدودیت‌های نصب را تغییر دهد. کل فیلم بلند اسکن نمی‌شود. تشخیص تنها برای فایل‌های موجود و ایندکس‌شدهٔ آرشیو است.

دانلود قرارداد OpenAPI · پنل مدیریت

انتخاب هسته و محدودیت جست‌وجو

در auto و adaptive، هسته‌های فعال تنظیم‌شدهٔ مدیر اجرا می‌شوند. روش اختصاصی مثل mode=chromaprint فقط همان هسته را بررسی می‌کند. /v1/capabilities فهرست search_engines و sample_seconds واقعی را برمی‌گرداند. در attempts، limited_reason علت رسیدن به بودجه یا مهلت جست‌وجو را نشان می‌دهد؛ projected_hits، hit_budget و candidate_count برای بررسی در دسترس‌اند. HTTP 200 به‌تنهایی به معنی پیدا شدن آهنگ نیست.

اطلاعات ربات مالک فایل — ۰٫۹٫۴۲

در «دسترسی API»، مجوز «توکن آرشیو» را فقط برای کلید سرور مورد اعتماد روشن کنید. توکن، کنترل کامل ربات را می‌دهد. سپس match.telegram و matches[].telegram شامل bot_id، file_id، bot_token، available و reason هستند. مسیرهای GET /v1/tracks/{track_id} و GET /v1/tracks/{track_id}/download-link نیز همین شیء را در telegram برمی‌گردانند. ورودی تشخیص همچنان بایت خام فایل است.

در زمان تغییر وضعیت ربات، reason=archive_bot_busy است و تشخیص موفق همچنان برمی‌گردد. وقتی available=false است، bot_token برابر null است؛ از لینک دانلود استفاده کنید. شناسهٔ فایل مختص همان ربات است. بازنشستگی، حذف شناسه یا نبود توکن ممکن است این مسیر را غیرفعال کند. available=true بیانگر موجودبودن اطلاعات ثبت‌شده است؛ تست آنلاین در هر درخواست انجام نمی‌شود. توکن در کش تشخیص ذخیره نمی‌شود و در گزارش درخواست مخفی است. خاموش‌کردن مجوز، توکن قبلاً تحویل‌شده را باطل نمی‌کند؛ برای آن باید توکن در تلگرام تعویض شود.