البدء السريع
يستخدم التدفق أدناه مفتاح واجهة برمجة التطبيقات لتحميل ملف واحد، وإنشاء مهمة ترجمة، وتنزيل النتائج.
-
جهّز بيانات الاعتماد والملف
Terminal window export OMNIDOC_API_KEY="sk_your_key"BASE="https://omnidoc.top/api/v1"FILE="report.docx"SIZE=$(wc -c < "$FILE" | tr -d ' ')import uuidfrom pathlib import Pathimport requestsAPI_KEY = "sk_your_key"BASE = "https://omnidoc.top/api/v1"FILE = Path("report.docx")H = {"X-API-Key": API_KEY}import axios from 'axios';import fs from 'node:fs';import path from 'node:path';const API_KEY = 'sk_your_key';const BASE = 'https://omnidoc.top/api/v1';const filePath = 'report.docx';const apiHeaders = { 'X-API-Key': API_KEY }; -
اطلب عنوانًا وحمّل الملف
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"presign = requests.post(f"{BASE}/upload/presign",headers=H,json={"filename": FILE.name,"file_size": FILE.stat().st_size,},timeout=20,)presign.raise_for_status()ticket = presign.json()with FILE.open("rb") as stream:put_headers = {**ticket["upload_headers"],"Content-Length": str(FILE.stat().st_size),}uploaded = requests.put(ticket["upload_url"], headers=put_headers, data=stream, timeout=300)uploaded.raise_for_status()const stat = fs.statSync(filePath);const { data: ticket } = await axios.post(`${BASE}/upload/presign`,{filename: path.basename(filePath),file_size: stat.size,},{ headers: apiHeaders });await axios.put(ticket.upload_url, fs.createReadStream(filePath), {headers: { ...ticket.upload_headers, 'Content-Length': stat.size },maxBodyLength: Infinity,}); -
أكد التحميل واحصل على معرف المستند
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')finalized = requests.post(f"{BASE}/upload/finalize",headers=H,json={"finalize_token": ticket["finalize_token"]},timeout=30,)finalized.raise_for_status()document_id = finalized.json()["document"]["id"]const { data: finalized } = await axios.post(`${BASE}/upload/finalize`,{ finalize_token: ticket.finalize_token },{ headers: apiHeaders });const documentId = finalized.document.id; -
إنشاء مهمة الترجمة
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')job_response = requests.post(f"{BASE}/jobs",headers={**H, "Idempotency-Key": str(uuid.uuid4())},json={"document_id": document_id, "target_lang": "en"},timeout=30,)job_response.raise_for_status()job_id = job_response.json()["id"]const { data: job } = await axios.post(`${BASE}/jobs`,{ document_id: documentId, target_lang: 'en' },{ headers: { ...apiHeaders, 'Idempotency-Key': crypto.randomUUID() } });const jobId = job.id; -
انتظر حتى يكتمل التنزيل
import reimport timefrom urllib.parse import unquotewhile 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"}:breaktime.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 = fallbacksafe_name = Path(name).name or fallbackPath(safe_name).write_bytes(download.content)
ما تحصل عليه
Section titled “ما تحصل عليه”يقوم البرنامج النصي أولاً بطباعة job_id. عند نجاح المهمة، يتم تنزيل النتائج إلى الدليل الحالي. يتوقف التحقق الدوري عندما تصل المهمة إلى completed أو failed.
المدة الزمنية اللازمة تعتمد على حجم الملف وطابور المعالجة. في بيئة الإنتاج، استخدم webhook أو SSE بدلاً من الاستعلام الدوري غير المحدود.
المثال لا يعيد محاولات إنشاء الطلبات تلقائيًا. بعد انقضاء وقت انتظار الشبكة، احتفظ بمعرّف المهمة ومفتاح التكرارية ونص الطلب، وتحقق من الحالة أولًا. لا يتم إلغاء مهمة تم إنشاؤها عند خروج البرنامج النصي.
عندما يفشل شيء ما
Section titled “عندما يفشل شيء ما”401: تحقق من تعيين متغير البيئة وأن المفتاح صالح.402، أوquota_exceededأثناء العمل: تحقق من أن الرصيد الدائن (بعد خصم الدين) يغطي عتبة البداية.403: تحقق من ميزانية المفتاح والإعدادات المسموح بها ومن يملك المورد.429: اقرأ رمز خطأ الأعمال للتمييز بين حد السرعة، وامتلاء قائمة الانتظار، واستنفاد الميزانية.- انتهت صلاحية عنوان الرفع المباشر أو فشل الرفع: يُرجى طلب عنوان رفع جديد.
سجّل X-Request-Id ومسار الطلب، ولكن لا تسجّل المفتاح الكامل أو بيانات اعتماد الرفع أبداً. جميع الأخطاء وطرق إعادة المحاولة موجودة في مرجع error reference .