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.
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.
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.
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.
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.
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"import osimport requests
response = requests.get( "https://omnidoc.top/api/v1/billing/credits/balance", headers={"X-API-Key": os.environ["OMNIDOC_API_KEY"]}, timeout=30,)response.raise_for_status()print(response.json())// Node.js 20+, save as balance.mjsconst apiKey = process.env.OMNIDOC_API_KEY;if (!apiKey) throw new Error('Set OMNIDOC_API_KEY');const response = await fetch('https://omnidoc.top/api/v1/billing/credits/balance', { headers: { 'X-API-Key': apiKey }, signal: AbortSignal.timeout(30_000),});if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);console.log(await response.json());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.
| Passaggio | Metodo e percorso | Cosa mantenere |
|---|---|---|
| Richiedi un caricamento | POST /upload/presign | upload_url, upload_headers, finalize_token |
| Invia il file | PUT al upload_url restituito | Risposta di successo; questa richiesta non contiene alcuna chiave API |
| Conferma il caricamento | POST /upload/finalize | document.id |
| Crea una traduzione | POST /jobs | Lavoro id |
| Verifica lo stato | GET /jobs/{job_id} | completed o failed |
| Elencare i risultati | GET /artifacts?job_id={job_id} | ID e formati degli artifact |
| Scarica un risultato | GET /artifacts/{artifact_id}/download | Byte 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 .
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.
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.| Stato | Verifica prima | Cosa fare |
|---|---|---|
401 / 403 | Chiave, autorizzazioni, proprietà delle risorse | Correggi le credenziali o i permessi; non riprovare in modo indiscriminato |
402 | Crediti disponibili | Ricarica, quindi invia di nuovo |
409 | Chiave e corpo dell’idempotenza, stato della risorsa | Interroga l’operazione originale prima di avviarne una nuova |
422 | Errori di campo nella risposta | Correggi i parametri o il file |
429 | Business code e Retry-After | I limiti di rate e coda possono essere superati attendendo; prima è necessario aumentare il budget della chiave esaurito. |
5xx | Errore temporaneo del servizio | Ritardo 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.
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.