البدء

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

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

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

URL
الإنتاجhttps://api.usepolylingo.com/v1

كل مسار أدناه نسبي لهذا الأساس (على سبيل المثال، 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".

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

لا حاجة لمفتاحGET /health — فحص سريع لتوافر الخدمة
GET /languages — رموز اللغات المدعومة
مفتاح مطلوبPOST /translate — ترجمة المحتوى
POST /translate/batch — ترجمة عدة عناصر
POST /jobs — إدراج ترجمة طويلة الأمد (يرجع 202 فورًا)
GET /jobs/:id — استعلام حالة الوظيفة؛ يتضمن queue_position أثناء الانتظار
GET /usage — الاستخدام للحساب المصادق عليه

أول طلب (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 — أشكال الطلب والاستجابة، التنسيقات، الأخطاء، والحدود.
البدء | بولي لينغو | PolyLingo