البدء

استخدم واجهة برمجة تطبيقات PolyLingo HTTP لترجمة النص العادي، Markdown، JSON، أو HTML مع الحفاظ على الهيكل كما هو. يغطي هذا الدليل نقطة النهاية للإنتاج، والمصادقة، وأول طلب ناجح لك.

عنوان URL الأساسي

جميع الأمثلة تستخدم واجهة برمجة التطبيقات للإنتاج:

كل مسار أدناه نسبي لهذا الأساس (على سبيل المثال، POST /translate يعني POST https://api.usepolylingo.com/v1/translate).

إذا كنت تشغل نسخة خاصة من واجهة برمجة تطبيقات PolyLingo، استبدل المضيف بعنوان نشر الخاص بك واحتفظ بالبادئة /v1 ما لم تقم بتكوين خلاف ذلك.

المصادقة

النقاط المحمية تتوقع مفتاح API الخاص بك في رأس Authorization:

Authorization: Bearer <your_api_key>

الحصول على مفتاح: أنشئ واحدًا في تطبيق PolyLingo تحت مفاتيح API. سترى المفتاح الكامل مرة واحدة فقط—خزنه في مكان آمن (متغير بيئة أو مدير أسرار). يمكن إلغاء المفاتيح من نفس الشاشة.

الأمان: عامل المفتاح مثل كلمة مرور. من الأفضل استدعاء API من الخادم الخاص بك، وليس من كود المتصفح العام، حتى لا يتم كشف المفتاح للمستخدمين.

إذا كان الرأس مفقودًا أو خاطئًا أو المفتاح غير صالح أو ملغى، تستجيب API بـ 401 و error: "invalid_api_key".

النقاط النهائية والمفاتيح

أول طلب (cURL)

export POLYLINGO_API_KEY="pl_your_key_here"

curl -sS -X POST "https://api.usepolylingo.com/v1/translate" \
  -H "Authorization: Bearer $POLYLINGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "# Hello\n\nThis is **bold**.",
    "format": "markdown",
    "targets": ["es", "fr"],
    "model": "standard"
  }'

تتضمن الاستجابة الناجحة كائن translations (مدخل واحد لكل لغة هدف طلبتها) وكائن usage مع عدد الرموز.

أول طلب (Node.js)

Node.js 18+ يتضمن fetch:

const API_KEY = process.env.POLYLINGO_API_KEY
const res = await fetch('https://api.usepolylingo.com/v1/translate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${API_KEY}`,
  },
  body: JSON.stringify({
    content: '# Hello\n\n**Bold** text.',
    format: 'markdown',
    targets: ['de', 'ja'],
    model: 'standard',
  }),
})
const data = await res.json()
if (!res.ok) throw new Error(`${data.error}: ${data.message}`)
console.log(data.translations)

تحقق من أن API متاحة

لا حاجة لمفتاح للصحة:

curl -sS "https://api.usepolylingo.com/v1/health"

يجب أن ترى حمولة JSON صغيرة تشير إلى أن الخدمة متاحة. استخدم GET /languages لقائمة الرموز التي يمكنك تمريرها كـ targets.

CORS وتطبيقات المتصفح

قد تقيد API أي أصول المتصفح يمكنها الاتصال بها مباشرة، حتى لا تُستخدم المفاتيح من مواقع غير موثوقة. المكالمات من جانب الخادم (Node، Python، وظائف الحافة، الخلفية الخاصة بك) غير محدودة بواسطة CORS.

لتطبيق صفحة واحدة، النمط المعتاد هو: الواجهة الأمامية تتحدث إلى الخلفية الخاصة بك، والخلفية تستدعي PolyLingo بمفتاح API.

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

• مرجع API — أشكال الطلب والاستجابة، الصيغ، الأخطاء، والحدود.