Ga naar inhoud

Snelstart

De onderstaande workflow maakt gebruik van een API-sleutel om één bestand te uploaden, een vertaalopdracht aan te maken en de resultaten te downloaden.

  1. Bereid de inloggegevens en het bestand voor

    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. Vraag een adres aan en upload het bestand

    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. Bevestig de upload en verkrijg de document-ID

    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. Maak de vertaalopdracht aan

    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. Wacht op voltooiing en download

    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)

Het script drukt eerst de job_id af. Wanneer de taak succesvol is, worden de resultaten naar de huidige map gedownload. Het polling stopt wanneer de taak completed of failed bereikt.

Hoe lang het duurt, hangt af van de bestandsgrootte en de wachtrij. In productie gebruikt u een webhook of SSE in plaats van onbeperkt polling.

Het voorbeeld voert geen automatische opnieuw poging uit voor aanmaakverzoeken. Na een netwerktime-out behoudt u de taak-ID, de idempotentiesleutel en de verzoektekst, en controleert u eerst de status. Een aangemaakte taak wordt niet geannuleerd wanneer het script afsluit.

  • 401: controleer of de omgevingsvariabele is ingesteld en de sleutel geldig is.
  • 402, of quota_exceeded tijdens de taak: controleer of het krediettegoed (na schulden) de startdrempel dekt.
  • 403: controleer het budget van de sleutel, de toegestane instellingen en wie de eigenaar is van de resource.
  • 429: lees de bedrijfsfoutcode om een snelheidslimiet, een volle wachtrij en een opgebruikt budget van elkaar te onderscheiden.
  • Het directe uploadadres is verlopen of de upload is mislukt: vraag een nieuw uploadadres aan.

Log de X-Request-Id en het verzoekpad, maar nooit de volledige sleutel of uploadreferenties. Alle fouten en herprobeermethoden staan in de foutverwijzing .