Saltearse al contenido

Inicio rápido

El flujo a continuación utiliza una clave API para cargar un archivo, crear un trabajo de traducción y descargar los resultados.

  1. Prepare las credenciales y el archivo

    Ventana 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. Solicitar una dirección y cargar el archivo

    Ventana 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. Confirme la carga y obtenga el ID del documento

    Ventana 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. Crear el trabajo de traducción

    Ventana 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. Esperar la finalización y la descarga

    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)

El script primero imprime el job_id. Cuando la tarea se completa con éxito, los resultados se descargan en el directorio actual. La consulta se detiene cuando la tarea alcanza completed o failed.

El tiempo que tarda depende del tamaño del archivo y de la cola. En producción, utilice un webhook o SSE en lugar de realizar consultas sin límite.

El ejemplo no reintentará automáticamente las solicitudes de creación. Tras un tiempo de espera de red, conserve el ID del trabajo, la clave de idempotencia y el cuerpo de la solicitud, y compruebe primero el estado. Un trabajo creado no se cancela cuando el script finaliza.

  • 401: verifique que la variable de entorno esté definida y que la clave sea válida.
  • 402, o quota_exceeded en el trabajo: verifique que el saldo a favor (después de las deudas) cubra el umbral inicial.
  • 403: verifique el presupuesto de la clave, sus configuraciones permitidas y quién es el propietario del recurso.
  • 429: lea el código de error comercial para distinguir entre límite de tasa, cola llena y presupuesto agotado.
  • La dirección de carga directa ha caducado o la carga falló: solicite una nueva dirección de carga.

Registre el X-Request-Id y la ruta de la solicitud, pero nunca la clave completa ni las credenciales de carga. Todos los errores y métodos de reintento se encuentran en la referencia de error . .