Aller au contenu

Démarrage rapide

Le flux ci-dessous utilise une clé API pour télécharger un fichier, créer une tâche de traduction et télécharger les résultats.

  1. Préparez les informations d’identification et le fichier

    Fenêtre de terminal
    export OMNIDOC_API_KEY="sk_your_key"
    BASE="https://omnidoc.top/api/v1"
    FILE="report.docx"
    SIZE=$(wc -c < "$FILE" | tr -d ' ')
  2. Demander une adresse et téléverser le fichier

    Fenêtre de terminal
    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. Confirmez le téléchargement et obtenez l’ID du document

    Fenêtre de terminal
    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. Créer la tâche de traduction

    Fenêtre de terminal
    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. Attendez la fin et téléchargez

    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)

Le script affiche d’abord le job_id. Lorsque la tâche aboutit, les résultats sont téléchargés dans le répertoire courant. Le polling s’arrête lorsque la tâche atteint completed ou failed.

Le temps nécessaire dépend de la taille du fichier et de la file d’attente. En production, utilisez un webhook ou SSE au lieu d’un polling sans limite.

L’exemple ne réessaie pas automatiquement les requêtes de création. Après un délai d’attente réseau, conservez l’ID de la tâche, la clé d’idempotence et le corps de la requête, puis vérifiez d’abord l’état. Une tâche déjà créée n’est pas annulée à la sortie du script.

  • 401 : vérifiez que la variable d’environnement est définie et que la clé est valide.
  • 402, ou quota_exceeded en cours d’exécution : vérifiez que le solde créditeur (après déduction des dettes) couvre le seuil de démarrage.
  • 403 : vérifiez le budget de la clé, ses paramètres autorisés et le propriétaire de la ressource.
  • 429 : lire le code d’erreur métier pour distinguer une limite de débit, une file d’attente pleine et un budget épuisé.
  • L’adresse de téléchargement direct a expiré ou le téléchargement a échoué : demandez une nouvelle adresse de téléchargement.

Enregistrez le X-Request-Id et le chemin de la requête, mais jamais la clé complète ni les informations d’authentification du téléchargement. Toutes les erreurs et les méthodes de réessai sont répertoriées dans la référence des erreurs.