Equalang
ملاحظات Equalang

مرجع Equalang API والبدء السريع

Equalang

باختصار

دليل المطوّر لدمج Equalang API: ترجمة النصوص أو معالجة المستندات والوسائط بشكل غير متزامن، مع أمثلة لنقاط النهاية العشر.

الكلمات المفتاحية: دمج API؛ API ترجمة الملفات؛ الترجمة الآلية؛ دليل المطوّر؛ مرجع API

عند دمج Equalang في لوحة الإدارة أو سير العمل لديك، يمكنك ترجمة النصوص فورًا أو معالجة ملفات كاملة — مثل المستندات والصوت والفيديو — مع الحفاظ على تنسيقها الأصلي حيثما كان ذلك مدعومًا.

يقدّم هذا الدليل بداية سريعة لسير عمل ترجمة الملفات باستخدام cURL وPython، يليها مرجع كامل لنقاط النهاية (endpoints) العامة العشر في API.

المصادقة والاستجابة القياسية

يتوفّر Equalang API على العنوان https://equalang.com/v1. صدّق كل طلب بتمرير مفتاح API الخاص بك في ترويسة HTTP باسم Authorization:

Authorization: Bearer el_your_api_key_here

يجب أن يمتلك مفتاح API الخاص بك النطاقات (scopes) الصحيحة: مثلًا translations:document للمهام، وtranslations:text للنصوص، وfiles:read للتنزيل المباشر للملفات.

مغلّف الاستجابة القياسي: تستخدم جميع استجابات JSON الناجحة بنية قياسية على المستوى الأعلى. ولأجل الاختصار، تحذف الأمثلة البنيوية أدناه بعض الحقول غير الأساسية، لكنها تبقى كائنات JSON صالحة تمامًا. المعرّفات وعناوين URL وأرقام الأرصدة الواردة فيها هي لأغراض التوضيح فقط، لذا استخدم القيم الفعلية التي تعود بها استجاباتك.

{
  "code": "OK",
  "message": "ok",
  "data": {},
  "request_id": "req_example_id"
}

البدء السريع: ترجمة الملفات بشكل غير متزامن

معالجة مستند كامل تتطلّب سير عمل غير متزامن: ارفع الملف لبدء مهمة، وتتبّع حالتها، ثم نزّل النتيجة. يمكنك استخدام ملفك الخاص، أو تنزيل ملفنا التجريبي supply-confirmation.zh-CN.docx للاختبار.

الطريقة 1: باستخدام cURL

أولًا، صدّر مفتاح API (يمكنك إنشاؤه على https://equalang.com/api-keys):

export EQUALANG_API_KEY="el_your_api_key_here"

1. رفع الملف وبدء المهمة

أرسل الملف مباشرة. يحجز API الاعتمادات اللازمة ويعيد job_id. أدرج مفتاح Idempotency-Key فريدًا (مثل UUID) لمنع إنشاء مهام مكرّرة إذا حدث انقضاء مهلة (timeout). أعد استخدام المفتاح نفسه إذا احتجت إلى تكرار الإرسال ذاته، وأنشئ مفتاحًا جديدًا للمهام الجديدة. (تأكد من وجود ملف محلي باسم report.docx قبل التشغيل، أو غيّر الاسم في الكود.)

curl --fail-with-body -X POST "https://equalang.com/v1/jobs/translate" \
  -H "Authorization: Bearer $EQUALANG_API_KEY" \
  -H "Idempotency-Key: a-unique-uuid-here" \
  -F "file=@report.docx" \
  -F "target_language=en"

استخرج job_id من كائن data في الاستجابة لتستخدمه في الخطوة التالية. لا تنسخ معرّفات مأخوذة من أمثلة سابقة.

2. تتبّع حالة المهمة

استخدم job_id الخاص بك لمتابعة التقدّم. انتظر المدة التي يوصي بها ترويسة Retry-After بين الطلبات. أوقف التتبّع عندما تصبح قيمة finished هي true.

curl --fail-with-body "https://equalang.com/v1/jobs/your_actual_job_id" \
  -H "Authorization: Bearer $EQUALANG_API_KEY"

3. تنزيل النتيجة

بمجرد أن تصبح الحالة SUCCEEDED، تتضمّن الاستجابة رابط download_url مؤقتًا. يستخدم هذا الرابط تفويضًا مؤقتًا بالتوقيع، لذا لا تحتاج — ولا ينبغي — أن ترسل رمز Bearer الخاص بـ API عند التنزيل منه. استخدم راية مثل -f للفشل بصمت عند أخطاء HTTP، حتى لا تحفظ صفحة الخطأ بوصفها ملفك.

curl -f -o report_translated.docx "https://example.com/download/your_temporary_signature_url"

الطريقة 2: باستخدام Python (requests)

ملاحظة: يتطلّب الأمر مكتبة requests (pip install requests).

import os
import time
import requests

API_KEY = os.environ.get("EQUALANG_API_KEY")
# Provide a stable key for the same request, change it for new tasks
IDEMPOTENCY_KEY = os.environ.get("IDEMPOTENCY_KEY", "your-unique-uuid-here")

HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Idempotency-Key": IDEMPOTENCY_KEY
}
BASE_URL = "https://equalang.com/v1"

# 1. Create Job
# Ensure you have a local file named report.docx before running
with open("report.docx", "rb") as f:
    files = {"file": f}
    data = {"target_language": "en"}
    response = requests.post(
        f"{BASE_URL}/jobs/translate",
        headers=HEADERS,
        files=files,
        data=data,
        timeout=30
    )
    response.raise_for_status()
    job_id = response.json()["data"]["job_id"]
    print(f"Job created: {job_id}")

# 2. Poll Job
while True:
    res = requests.get(f"{BASE_URL}/jobs/{job_id}", headers={"Authorization": f"Bearer {API_KEY}"}, timeout=30)
    res.raise_for_status()
    job_data = res.json()["data"]

    if job_data["finished"]:
        if job_data["status"] == "SUCCEEDED":
            download_url = job_data["download_url"]
            print(f"Success! Downloading result...")

            # 3. Download Result (No API key needed for the temporary URL)
            dl_res = requests.get(download_url, timeout=30)
            dl_res.raise_for_status()
            with open("report_translated.docx", "wb") as out:
                out.write(dl_res.content)
            print("Download complete.")
        else:
            print(f"Job ended with status: {job_data['status']}")
        break

    retry_after = int(res.headers.get("Retry-After", 5))
    time.sleep(retry_after)

للحالات المتقدّمة (مثل التحقق من التكلفة أولًا أو استعادة حالات التتبّع المفقودة)، يمكنك تنزيل السكربت المتقدّم translate_file.py.

مرجع نقاط النهاية

فيما يلي تفاصيل نقاط النهاية العامة العشر وأمثلة على بنية الحمولة (payload) لكل منها.

راجع التعدادات (enumerations) DocumentLanguage وTextLanguage في مخطّط OpenAPI أو في دليل المطوّرين لمعرفة الرموز الدقيقة للغات المدعومة (مثل zh-CN وen). رمز auto مخصّص لـ source_language فقط.

1. ترجمة النص

POST /v1/text/translate

ترجمة سلاسل نصية بشكل متزامن. تُحاسب النصوص فقط إذا نُجحت ترجمتها. تكون قيمة detected_source_language مساوية لـ null إذا لم يتم التعرّف تلقائيًا على لغة محدّدة.

curl --fail-with-body -X POST "https://equalang.com/v1/text/translate" \
  -H "Authorization: Bearer $EQUALANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"texts": ["您的订单已发货。"], "target_language": "en"}'
{
  "code": "OK",
  "message": "ok",
  "data": {
    "translations": [
      {
        "translated_text": "Your order has been shipped.",
        "detected_source_language": null,
        "error": null
      }
    ],
    "usage": {
      "credits_charged": 0.07
    }
  },
  "request_id": "dd0b35ce1b52474faad670a33a9fc62d"
}

2. رفع ملف لعرض التكلفة

POST /v1/files

إذا كنت بحاجة إلى عرض التكلفة القصوى المحتملة قبل الترجمة، فارفع الملف هنا. يعيد الطلب file_id وquote (الاعتمادات المطلوبة).

curl --fail-with-body -X POST "https://equalang.com/v1/files" \
  -H "Authorization: Bearer $EQUALANG_API_KEY" \
  -F "file=@report.docx"
{
  "code": "OK",
  "message": "ok",
  "data": {
    "file_id": "a132cf83-e641-41a3-9220-dfefb0e3d2a6",
    "quote": {
      "translate": 0.59,
      "transcribe": null
    }
  },
  "request_id": "e81b9f386ace4a82b63dc292c9cff669"
}

3. إنشاء مهمة ترجمة مستند

POST /v1/jobs/translate

ينشئ مهمة ترجمة غير متزامنة. يقبل file (multipart) أو file_url أو file_id.

# Using a previously uploaded file_id
curl --fail-with-body -X POST "https://equalang.com/v1/jobs/translate" \
  -H "Authorization: Bearer $EQUALANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"file_id": "a132cf83-e641-41a3-9220-dfefb0e3d2a6", "target_language": "en"}'
{
  "code": "OK",
  "message": "ok",
  "data": {
    "job_id": "e861014d-72a1-4e2a-bfa3-36fa10d9978e",
    "status": "INIT",
    "credits_reserved": 0.59
  },
  "request_id": "36c7dc43855b4e9eae553e7fd656788c"
}

4. إنشاء مهمة تفريغ صوتي

POST /v1/jobs/transcribe

يستخرج النص المنطوق من ملف صوتي أو مرئي ويعيده على شكل ترجمة نصية موقّتة بالزمن، دون ترجمته.

curl --fail-with-body -X POST "https://equalang.com/v1/jobs/transcribe" \
  -H "Authorization: Bearer $EQUALANG_API_KEY" \
  -F "file=@interview.mp3" \
  -F 'options={"output_formats": ["srt", "txt"]}'
{
  "code": "OK",
  "message": "ok",
  "data": {
    "job_id": "b1a23c45-1234-5678-90ab-cdef12345678",
    "status": "INIT",
    "credits_reserved": 1.848
  },
  "request_id": "req_12345"
}

5. الاستعلام عن حالة المهمة

GET /v1/jobs/{job_id}

يعيد تقدّم المهمة وروابط التنزيل لمهمة نشطة أو مكتملة. استبدل {job_id} في المسار بمعرّف UUID الفعلي الخاص بك.

curl --fail-with-body "https://equalang.com/v1/jobs/e861014d-72a1-4e2a-bfa3-36fa10d9978e" \
  -H "Authorization: Bearer $EQUALANG_API_KEY"
{
  "code": "OK",
  "message": "ok",
  "data": {
    "job_id": "e861014d-72a1-4e2a-bfa3-36fa10d9978e",
    "status": "SUCCEEDED",
    "finished": true,
    "progress_percent": 100,
    "download_url": "https://example.com/download/download_url",
    "outputs": [
      {
        "kind": "translation",
        "format": "docx",
        "filename": "supply-terms.zh-cn-equalang-en.docx",
        "download_url": "https://example.com/download/download_url"
      }
    ]
  },
  "request_id": "7c7621312ab04f3da3492db98945e597"
}

6. تنزيل بايتات الملف

GET /v1/files/{file_id}

بعكس رابط download_url المؤقت (الذي لا يتطلّب مفتاح API)، يتيح لك هذا المدخل تنزيل البايتات الخام لأي ملف مصدر أو مترجم مخزّن في حسابك مباشرةً باستخدام file_id الخاص به. يتطلّب الأمر مفتاح API يمتلك نطاق files:read.

curl -f "https://equalang.com/v1/files/2282396e-2b5e-43d9-853a-072c48b4d860" \
  -H "Authorization: Bearer $EQUALANG_API_KEY" \
  -o translated_result.docx

(يعيد بيانات ثنائية مباشرة، دون مغلّف JSON)

7. إلغاء المهمة

POST /v1/jobs/{job_id}/cancel

يلغي مهمة. إذا كانت المهمة في حالة INIT أو QUEUED، فإنها تصبح CANCELLED فورًا. وإذا كانت RUNNING، فإنها تدخل حالة CANCELLING حتى تتوقف تمامًا.

curl --fail-with-body -X POST "https://equalang.com/v1/jobs/e861014d-72a1-4e2a-bfa3-36fa10d9978e/cancel" \
  -H "Authorization: Bearer $EQUALANG_API_KEY"
{
  "code": "OK",
  "message": "ok",
  "data": {
    "job_id": "e861014d-72a1-4e2a-bfa3-36fa10d9978e",
    "status": "CANCELLED",
    "finished": true,
    "usage": {
      "credits_reserved": 0,
      "credits_charged": 0
    }
  },
  "request_id": "502c12dff71149f588620e96b07769fb"
}

8. إعادة محاولة المهمة

POST /v1/jobs/{job_id}/retry

يعيد محاولة المهمة. يمكنك إعادة المحاولة إذا كانت المهمة FAILED وكان حقل error.retryable فيها بقيمة true، أو إذا كانت قد أصبحت CANCELLED. تُحجز الاعتمادات من جديد عند إعادة المحاولة. لاحظ أنه إذا فشل تسليم النتيجة (RESULT_DELIVERY_FAILED)، فإن إعادة المحاولة ستحاول التسليم مرة أخرى، لكنها لن تحسب عليك تكلفة الترجمة للمرة الثانية.

curl --fail-with-body -X POST "https://equalang.com/v1/jobs/e861014d-72a1-4e2a-bfa3-36fa10d9978e/retry" \
  -H "Authorization: Bearer $EQUALANG_API_KEY"
{
  "code": "OK",
  "message": "ok",
  "data": {
    "job_id": "e861014d-72a1-4e2a-bfa3-36fa10d9978e",
    "status": "INIT",
    "finished": false,
    "usage": {
      "credits_reserved": 0.59,
      "credits_charged": 0
    }
  },
  "request_id": "497c3794b0a4497e890f64cc8b7d6d27"
}

9. قائمة المهام

GET /v1/jobs

يعيد قائمة مُصفّحة بمهام الترجمة والتفريغ الصوتي، بدءًا من الأحدث. مرّر limit وcursor (أو offset) كمعاملات استعلام للتنقّل بين الصفحات.

curl --fail-with-body "https://equalang.com/v1/jobs?limit=10" \
  -H "Authorization: Bearer $EQUALANG_API_KEY"
{
  "code": "OK",
  "message": "ok",
  "data": {
    "items": [
      {
        "job_id": "e861014d-72a1-4e2a-bfa3-36fa10d9978e",
        "status": "SUCCEEDED",
        "task": "translate"
      }
    ],
    "limit": 10,
    "offset": 0,
    "total": 39,
    "next_cursor": "MjAyNi0xMC0wOVQxOD..."
  },
  "request_id": "e79cd556afe94424a558e12ca7c2aed8"
}

10. التحقق من رصيد الاعتمادات

GET /v1/credits/balance

يعيد الاعتمادات المتاحة والمجمّدة في حسابك.

curl --fail-with-body "https://equalang.com/v1/credits/balance" \
  -H "Authorization: Bearer $EQUALANG_API_KEY"
{
  "code": "OK",
  "message": "ok",
  "data": {
    "total_credits": 125.50,
    "frozen_credits": 1.50,
    "available_credits": 124.00
  },
  "request_id": "req_bal_123"
}

التعامل مع الأخطاء

تعيد طلبات API الفاشلة حالات خطأ HTTP قياسية، مصحوبة ببيانات استجابة خطأ توضّح السبب وما إذا كانت العملية قابلة لإعادة المحاولة (retryable).

{
  "code": "INVALID_JOB_ID",
  "message": "Invalid job id",
  "data": null,
  "request_id": "9e97df047da640f7b60e10cfbc571711",
  "retryable": false
}

المصادر