المصادقة

أنشئ مفتاح API لـHUMAIN Voice، واحتفظ به على خادمك، وأرسله بالشكل الصحيح عبر كل وسيلة نقل.

احصل على مفتاح API

سجّل الدخول إلى لوحة تحكم HUMAIN Voice، وافتح API keys، واختر New key. أدخل Name باسم الخدمة التي ستستخدمه، واختر Create key، ثم انسخ السر. تعرضه لوحة التحكم مرة واحدة فقط. تحصل المفاتيح الجديدة على النطاقات الافتراضية لحسابك، وهي تغطي كل سير عمل عدا Voice Agent: يحتاج بدء الجلسة إلى النطاق الاختياري agent، وتفعّله على المفتاح (افتح المفتاح من API keys). يعمل المفتاح فقط مع API_URL الخاص بالبيئة التي أصدرته.

استخدم المفتاح من كود الخادم فقط؛ فتطبيقات المتصفح والجوال تكشفه. أبقِه خارج التحكم في الإصدارات والعناوين (URLs) والسجلات.

أرسل المفتاح: REST وبث HTTP

أرسل المفتاح في الترويسة x-api-key مع كل طلب REST للنسخ الدفعي وكل طلب بث HTTP. لا حاجة إلى ترويسة Origin.

curl -sS -X POST "$API_URL/v1/transcribe/codeswitch" \
  -H "x-api-key: $API_KEY" \
  -F "[email protected]"

أرسل المفتاح: Socket.IO

يحتاج مصافحة Socket.IO إلى ترويستين: x-api-key، وOrigin مضبوطة على مخطط API_URL ومضيفه. يضبط SDK الاثنتين من api_url وapi_key. أما العميل المباشر فيضبطهما بنفسه:

import { io } from "socket.io-client";

const socket = io(process.env.API_URL!, {
  path: process.env.API_PATH ?? "/socket.io",
  transports: ["websocket"],
  extraHeaders: {
    "x-api-key": process.env.API_KEY!,
    Origin: new URL(process.env.API_URL!).origin,
  },
});

إعدادات الاتصال

المتغيرمطلوبالقيمة
API_URLنعمأصل API لبيئتك: https://api.voice.humain.com.
API_KEYنعممفتاحك من لوحة تحكم HUMAIN Voice.
API_PATHلامسار Socket.IO. الافتراضي /socket.io لكل سير عمل يستخدم Socket.IO. اضبط /realtime/socket.io فقط على نقطة النهاية القديمة sautech.humain.com.
API_VERSIONلاإصدار REST للنسخ الدفعي. الافتراضي v1. يستخدمه عميل النسخ الدفعي في SDK.

تحقق من مفتاحك

لا يرسل هذا الطلب ملفًا، فلا ينشئ مهمة:

curl -sS -X POST "$API_URL/v1/transcribe/codeswitch" \
  -H "x-api-key: $API_KEY" \
  -w '\nHTTP %{http_code}\n'
النتيجةالمعنى
400 مع VALIDATION_INVALID_FORMATالمفتاح يعمل. الخطأ 400 متوقع: لم يُرسل ملف.
401المفتاح مفقود أو مكتوب خطأ أو ملغى أو منتهي أو من بيئة أخرى.
403المفتاح لا يملك صلاحية النسخ الدفعي، أو رفضت بوابة الطلب.
أي حالة أخرىراجع رموز الأخطاء.

أخطاء المصادقة

الاستجابةالمعنىالإصلاح
401 مع AUTH_UNAUTHORIZEDالمفتاح مفقود أو غير صالح.تأكد أن خادمك يرسل API_KEY كـx-api-key، وتحقق من حالة المفتاح في API keys. لا تعد المحاولة دون تغيير.
403 مع AUTH_FORBIDDENالمفتاح لا يملك النطاق اللازم لهذه العملية.افتح المفتاح في API keys وتحقق من Scopes.
403 بلا جسم ErrorResponseرفضت بوابة الطلب.تحقق من API_URL والمسار والترويسات. وعلى Socket.IO تحقق من Origin.

على Socket.IO، يفشل الاتصال (connect_error) أو يصل حدث error عند استخدام مفتاح غير صالح. أوقف إرسال الصوت وأصلح الإعدادات ثم أعد الاتصال. وللرموز الأخرى راجع رموز الأخطاء.

إذا انكشف مفتاح

اعتبر المفتاح منكشفًا إذا ظهر في التحكم في الإصدارات أو كود العميل أو عنوان URL أو سجل أو رسالة. حذف النسخة المرئية لا يجعله آمنًا.

  1. في لوحة تحكم HUMAIN Voice، اذهب إلى API keys، وافتح المفتاح، واختر Revoke، واختر Leaked / compromised سببًا، ثم اختر Revoke key. الإلغاء دائم؛ ويتوقف المفتاح عن العمل خلال نحو دقيقة.
  2. أنشئ مفتاحًا جديدًا، وخزّنه في مدير الأسرار لديك، وأعد نشر كل خدمة استخدمت المفتاح القديم.
  3. في صفحة Usage، افحص جدول كل مفتاح بحثًا عن نشاط لا تعرفه.

لاستبدال مفتاح غير منكشف، اختر Rotate. تعرض لوحة التحكم السر الجديد مرة واحدة؛ ويستمر القديم في العمل لمدة تصل إلى دقيقة.

الخطوات التالية

في هذه الصفحة