المصادقة
أنشئ مفتاح 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 أو سجل أو رسالة. حذف النسخة المرئية لا يجعله آمنًا.
- في لوحة تحكم HUMAIN Voice، اذهب إلى API keys، وافتح المفتاح، واختر Revoke، واختر Leaked / compromised سببًا، ثم اختر Revoke key. الإلغاء دائم؛ ويتوقف المفتاح عن العمل خلال نحو دقيقة.
- أنشئ مفتاحًا جديدًا، وخزّنه في مدير الأسرار لديك، وأعد نشر كل خدمة استخدمت المفتاح القديم.
- في صفحة Usage، افحص جدول كل مفتاح بحثًا عن نشاط لا تعرفه.
لاستبدال مفتاح غير منكشف، اختر Rotate. تعرض لوحة التحكم السر الجديد مرة واحدة؛ ويستمر القديم في العمل لمدة تصل إلى دقيقة.