Salta ai contenuti

Integra i flussi di lavoro documentali nella tua app

Dal caricamento di un file alla sua traduzione, dal controllo dell’avanzamento al download del risultato. Ogni fase è illustrata nell’ordine in cui si integra il sistema, con punti di accesso per la gestione dei file, l’elaborazione dei documenti e i servizi audio e video.

Base URL https://omnidoc.top/api/v1 · HTTPS · JSON · Autenticazione tramite chiave API · le traduzioni dei file vengono eseguite come job asincroni

Questo sito descrive l’API cloud HTTP.

01 Inizia con una richiesta che non consuma crediti

Sezione intitolata “01 Inizia con una richiesta che non consuma crediti”

Verifica che la tua chiave e la rete funzionino correttamente prima di caricare i file. Un controllo del saldo non consuma crediti né genera alcun lavoro di traduzione.

  1. Ottieni una chiave API

    Accedi alla API console e crea una chiave che inizi con sk_. Utilizza una chiave separata per ogni applicazione e assegnale un budget.

    Una chiave è valida per l’account che l’ha creata. Conservala sul server e leggila da una variabile d’ambiente; non inserirla mai nel codice sorgente di una pagina web o in un repository pubblico.

  2. Verifica il saldo

    Imposta la variabile d’ambiente OMNIDOC_API_KEY, quindi esegui uno qualsiasi degli esempi riportati di seguito. Un esito positivo restituisce JSON; 401 indica che la chiave presenta un problema e deve essere verificata. Non mostrare mai la chiave completa in ticket, schermate o log.

    Terminal window
    export OMNIDOC_API_KEY="sk_your_key"
    curl --fail-with-body --silent --show-error \
    'https://omnidoc.top/api/v1/billing/credits/balance' \
    -H "X-API-Key: $OMNIDOC_API_KEY"

Un caricamento riuscito significa solo che il file è stato memorizzato. Dopo aver creato un job, attendi che raggiunga uno stato finale, quindi elenca e scarica i relativi risultati.

PassaggioMetodo e percorsoCosa mantenere
Richiedi un caricamentoPOST /upload/presignupload_url, upload_headers, finalize_token
Invia il filePUT al upload_url restituitoRisposta di successo; questa richiesta non contiene alcuna chiave API
Conferma il caricamentoPOST /upload/finalizedocument.id
Crea una traduzionePOST /jobsLavoro id
Verifica lo statoGET /jobs/{job_id}completed o failed
Elencare i risultatiGET /artifacts?job_id={job_id}ID e formati degli artifact
Scarica un risultatoGET /artifacts/{artifact_id}/downloadByte del file e nome del file di risposta

Per il caricamento diretto, invia upload_headers dal server esattamente come restituito e non inviare mai X-API-Key all’indirizzo di archiviazione. Se l’indirizzo di caricamento scade o il trasferimento fallisce, richiedi uno nuovo. Dettagli: protocollo di caricamento, avvio rapido, flusso di lavoro completo Node.js e campi della richiesta di traduzione.

Ogni voce elenca i percorsi, i campi della richiesta e gli esempi. Lo stato del servizio del tuo account e i limiti della tua chiave si applicano a tutti.

Una chiave API identifica un account. Non è una password pubblica per il download di un file.

Intestazione della richiesta

Utilizzare X-API-Key: sk_… o Authorization: Bearer sk_…, uno dei due per richiesta. Inviare Content-Type: application/json con corpi JSON.

Cosa può raggiungere una chiave

Una chiave accede solo alle risorse che il relativo account può utilizzare; restano in vigore lo stato del servizio, il budget della chiave e le impostazioni di traduzione consentite. Le modifiche all’account e la creazione, la rotazione o la revoca delle chiavi vengono eseguite nella console.

Vedi autenticazione, budget e rotazione e servizi e autorizzazioni .

05 Incorporare la gestione dei failure di build nell’integrazione

Sezione intitolata “05 Incorporare la gestione dei failure di build nell’integrazione”

Un timeout non significa che il lavoro non sia stato creato. Distingui gli errori riprovabili dalle richieste che necessitano di correzione, in modo che nulla venga inviato o elaborato due volte.

  • Creazione idempotente : genera un Idempotency-Key per ogni nuova operazione di creazione; quando riprovi la stessa operazione, riutilizza la chiave originale e lo stesso identico corpo della richiesta. Le operazioni sui documenti, i lavori multimediali e la creazione vocale richiedono la chiave; per gli altri endpoint di creazione, consulta le relative pagine di riferimento.
  • Notifiche asincrone : il polling va bene per una prima integrazione; per monitorare i progressi in modo continuo utilizzare SSE , e per ricevere gli stati finali in background usare un webhook .
StatoVerifica primaCosa fare
401 / 403Chiave, autorizzazioni, proprietà delle risorseCorreggi le credenziali o i permessi; non riprovare in modo indiscriminato
402Crediti disponibiliRicarica, quindi invia di nuovo
409Chiave e corpo dell’idempotenza, stato della risorsaInterroga l’operazione originale prima di avviarne una nuova
422Errori di campo nella rispostaCorreggi i parametri o il file
429Business code e Retry-AfterI limiti di rate e coda possono essere superati attendendo; prima è necessario aumentare il budget della chiave esaurito.
5xxErrore temporaneo del servizioRitardo esponenziale limitato; mantenere la chiave di idempotenza per le richieste di creazione

Mantieni l’intestazione di risposta X-Request-Id, l’ora della richiesta e il percorso per la risoluzione dei problemi; non registrare mai la chiave completa. Tutti i codici di errore e gli esempi di retry sono disponibili nel riferimento agli errori.

06 Verifica il funzionamento della fatturazione prima di procedere all’integrazione

Sezione intitolata “06 Verifica il funzionamento della fatturazione prima di procedere all’integrazione”

Nessun credito

Il caricamento, la verifica dei lavori, il download dei risultati e la consultazione del saldo e dei registri di regolamento non consumano crediti; lo stesso vale per glossari, progetti, tag, ricerca e condivisione.

Fatturato in base all'utilizzo

La traduzione di file, gli strumenti per documenti, la traduzione istantanea e i servizi audio e video sono tariffati in base all’utilizzo effettivo; la creazione di un lavoro non rappresenta l’addebito finale.

Prima dell’inizio di un job, viene verificata solo la soglia di saldo; al termine, viene addebitato l’utilizzo effettivo. Se il saldo risulta insufficiente, la differenza viene registrata come debito e i crediti successivi vengono utilizzati per saldarlo in via prioritaria. È possibile riconciliare addebiti e rimborsi per singolo job o per operazione di credito. Quando il budget di una chiave è esaurito, è comunque possibile consultare i job, i risultati e i record associati a quella chiave.