تخطَّ إلى المحتوى

البدء السريع

يستخدم التدفق أدناه مفتاح واجهة برمجة التطبيقات لتحميل ملف واحد، وإنشاء مهمة ترجمة، وتنزيل النتائج.

  1. جهّز بيانات الاعتماد والملف

    Terminal window
    export OMNIDOC_API_KEY="sk_your_key"
    BASE="https://omnidoc.top/api/v1"
    FILE="report.docx"
    SIZE=$(wc -c < "$FILE" | tr -d ' ')
  2. اطلب عنوانًا وحمّل الملف

    Terminal window
    PRESIGN=$(curl --fail-with-body -sS "$BASE/upload/presign" \
    -H "X-API-Key: $OMNIDOC_API_KEY" \
    -H "Content-Type: application/json" \
    -d "$(jq -n --arg filename "$(basename "$FILE")" --argjson size "$SIZE" \
    '{filename:$filename,file_size:$size}')")
    UPLOAD_URL=$(printf '%s' "$PRESIGN" | jq -r '.upload_url')
    UPLOAD_TYPE=$(printf '%s' "$PRESIGN" | jq -r '.upload_headers["Content-Type"]')
    FINALIZE_TOKEN=$(printf '%s' "$PRESIGN" | jq -r '.finalize_token')
    curl --fail-with-body -sS -X PUT "$UPLOAD_URL" \
    -H "Content-Type: $UPLOAD_TYPE" \
    -H "If-None-Match: *" \
    --upload-file "$FILE"
  3. أكد التحميل واحصل على معرف المستند

    Terminal window
    DOCUMENT=$(curl --fail-with-body -sS "$BASE/upload/finalize" \
    -H "X-API-Key: $OMNIDOC_API_KEY" \
    -H "Content-Type: application/json" \
    -d "$(jq -n --arg token "$FINALIZE_TOKEN" '{finalize_token:$token}')")
    DOCUMENT_ID=$(printf '%s' "$DOCUMENT" | jq -r '.document.id')
  4. إنشاء مهمة الترجمة

    Terminal window
    JOB=$(curl --fail-with-body -sS "$BASE/jobs" \
    -H "X-API-Key: $OMNIDOC_API_KEY" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: $(uuidgen)" \
    -d "$(jq -n --arg document_id "$DOCUMENT_ID" \
    '{document_id:$document_id,target_lang:"en"}')")
    JOB_ID=$(printf '%s' "$JOB" | jq -r '.id')
  5. انتظر حتى يكتمل التنزيل

    import re
    import time
    from urllib.parse import unquote
    while True:
    response = requests.get(f"{BASE}/jobs/{job_id}", headers=H, timeout=20)
    response.raise_for_status()
    job = response.json()
    if job["status"] in {"completed", "failed"}:
    break
    time.sleep(3)
    if job["status"] == "failed":
    raise RuntimeError(job.get("error_msg") or "translation failed")
    artifacts = requests.get(
    f"{BASE}/artifacts", headers=H, params={"job_id": job_id}, timeout=20
    )
    artifacts.raise_for_status()
    for artifact in artifacts.json():
    download = requests.get(
    f"{BASE}/artifacts/{artifact['id']}/download",
    headers=H,
    timeout=300,
    )
    download.raise_for_status()
    fallback = f"{artifact['id']}.{artifact['format']}"
    disposition = download.headers.get("Content-Disposition", "")
    utf8 = re.search(r"filename\*=UTF-8''([^;]+)", disposition, re.I)
    plain = re.search(r'filename="([^"]+)"', disposition, re.I)
    if utf8:
    name = unquote(utf8.group(1))
    elif plain:
    name = plain.group(1)
    else:
    name = fallback
    safe_name = Path(name).name or fallback
    Path(safe_name).write_bytes(download.content)

يقوم البرنامج النصي أولاً بطباعة job_id. عند نجاح المهمة، يتم تنزيل النتائج إلى الدليل الحالي. يتوقف التحقق الدوري عندما تصل المهمة إلى completed أو failed.

المدة الزمنية اللازمة تعتمد على حجم الملف وطابور المعالجة. في بيئة الإنتاج، استخدم webhook أو SSE بدلاً من الاستعلام الدوري غير المحدود.

المثال لا يعيد محاولات إنشاء الطلبات تلقائيًا. بعد انقضاء وقت انتظار الشبكة، احتفظ بمعرّف المهمة ومفتاح التكرارية ونص الطلب، وتحقق من الحالة أولًا. لا يتم إلغاء مهمة تم إنشاؤها عند خروج البرنامج النصي.

  • 401: تحقق من تعيين متغير البيئة وأن المفتاح صالح.
  • 402، أو quota_exceeded أثناء العمل: تحقق من أن الرصيد الدائن (بعد خصم الدين) يغطي عتبة البداية.
  • 403: تحقق من ميزانية المفتاح والإعدادات المسموح بها ومن يملك المورد.
  • 429: اقرأ رمز خطأ الأعمال للتمييز بين حد السرعة، وامتلاء قائمة الانتظار، واستنفاد الميزانية.
  • انتهت صلاحية عنوان الرفع المباشر أو فشل الرفع: يُرجى طلب عنوان رفع جديد.

سجّل X-Request-Id ومسار الطلب، ولكن لا تسجّل المفتاح الكامل أو بيانات اعتماد الرفع أبداً. جميع الأخطاء وطرق إعادة المحاولة موجودة في مرجع error reference .