Zum Inhalt springen

Schnellstart

Der folgende Ablauf verwendet einen API-Schlüssel, um eine Datei hochzuladen, einen Übersetzungsauftrag zu erstellen und die Ergebnisse herunterzuladen.

  1. Bereiten Sie die Anmeldedaten und die Datei vor

    Terminal-Fenster
    export OMNIDOC_API_KEY="sk_your_key"
    BASE="https://omnidoc.top/api/v1"
    FILE="report.docx"
    SIZE=$(wc -c < "$FILE" | tr -d ' ')
  2. Fordern Sie eine Adresse an und laden Sie die Datei hoch

    Terminal-Fenster
    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. Bestätigen Sie den Upload und erhalten Sie die Dokument-ID

    Terminal-Fenster
    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. Erstellen Sie den Übersetzungsauftrag

    Terminal-Fenster
    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. Warten Sie auf den Abschluss und laden Sie herunter

    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)

Das Skript gibt zunächst die job_id aus. Wenn der Auftrag erfolgreich ist, werden die Ergebnisse in das aktuelle Verzeichnis heruntergeladen. Die Abfrage wird beendet, sobald der Auftrag completed oder failed erreicht.

Wie lange es dauert, hängt von der Dateigröße und der Warteschlange ab. Verwenden Sie in der Produktion einen webhook oder SSE anstelle eines unbegrenzten Pollings.

Das Beispiel führt keine automatischen Wiederholungsversuche für Erstellungsanfragen durch. Nach einem Netzwerk-Timeout sollten die Job-ID, der Idempotenzschlüssel und der Anfragetext beibehalten und zunächst der Status überprüft werden. Ein bereits erstellter Job wird beim Beenden des Skripts nicht abgebrochen.

  • 401: Überprüfen Sie, ob die Umgebungsvariable gesetzt ist und der Schlüssel gültig ist.
  • 402 oder quota_exceeded im Einsatz: Prüfen Sie, ob der Guthabenstand (nach Abzug von Schulden) den Startschwellenwert deckt.
  • 403: Überprüfen Sie das Budget des Schlüssels, seine zulässigen Einstellungen und den Eigentümer der Ressource.
  • 429: Lesen Sie den Geschäftsfehlercode, um zwischen einer Rate-Limit-Verletzung, einer vollen Warteschlange und einem erschöpften Budget zu unterscheiden.
  • Die Direkt-Upload-Adresse ist abgelaufen oder der Upload ist fehlgeschlagen: Bitte fordern Sie eine neue Upload-Adresse an.

Protokollieren Sie X-Request-Id und den Anfragepfad, jedoch niemals den vollständigen Schlüssel oder die Upload-Anmeldedaten. Alle Fehler und Wiederholungsverfahren finden Sie in der Fehlerreferenz.