Перейти до вмісту

Швидкий старт

Наведений нижче сценарій використовує ключ API для завантаження одного файлу, створення завдання перекладу та завантаження результатів.

  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 та шлях запиту, але ніколи не записуйте повний ключ або дані для завантаження. Усі помилки та способи повторної спроби перераховано в довідці щодо помилок.