Verzoekheader
Gebruik X-API-Key: sk_… of Authorization: Bearer sk_…, één van de twee per verzoek. Stuur Content-Type: application/json met JSON-lichamen.
Base URL https://omnidoc.top/api/v1 · HTTPS · JSON · API-sleutelauthenticatie · bestandstranslaties worden uitgevoerd als asynchrone taken
Deze site beschrijft de cloud HTTP API.
Controleer of uw sleutel en netwerk werken voordat u bestanden uploadt. Een saldocontrole kost geen credits en genereert geen vertaalopdracht.
Verkrijg een API-sleutel
Meld u aan bij de API-console en maak een sleutel aan die begint met sk_. Gebruik voor elke applicatie een aparte sleutel en wijs hieraan een budget toe.
Een sleutel is geldig voor het account dat deze heeft aangemaakt. Bewaar hem op de server en lees hem uit een omgevingsvariabele; plaats hem nooit in de broncode van een webpagina of in een openbaar repository.
Controleer het saldo
Stel de omgevingsvariabele OMNIDOC_API_KEY in en voer vervolgens een van de onderstaande voorbeelden uit. Succes retourneert JSON; 401 betekent dat er een probleem is met de sleutel en deze moet worden gecontroleerd. Toon nooit de volledige sleutel in tickets, schermafbeeldingen of logbestanden.
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());Een geslaagde upload betekent alleen dat het bestand is opgeslagen. Nadat u een taak hebt aangemaakt, wacht u totdat deze een definitieve status heeft bereikt, en list dan de resultaten en download ze.
| Stap | Methode en pad | Wat moet behouden blijven |
|---|---|---|
| Vraag een upload aan | POST /upload/presign | upload_url, upload_headers, finalize_token |
| Verzend het bestand | PUT naar de geretourneerde upload_url | Succesrespons; dit verzoek bevat geen API-sleutel |
| Bevestig de upload | POST /upload/finalize | document.id |
| Maak een vertaling | POST /jobs | Job id |
| Controleer de status | GET /jobs/{job_id} | completed of failed |
| Geef de resultaten weer | GET /artifacts?job_id={job_id} | Artefact-ID’s en -indelingen |
| Download een resultaat | GET /artifacts/{artifact_id}/download | Bestandsbytes en de bestandsnaam van de respons |
Voor de directe upload, verzend de upload_headers vanaf de server precies zoals deze wordt geretourneerd, en verzend nooit X-API-Key naar het opslagadres. Als het uploadadres verloopt of de overdracht mislukt, vraag dan een nieuw adres aan. Details: uploadprotocol , snelstart , volledige Node.js workflow en velden voor vertaalverzoek .
Elke vermelding geeft de paden, verzoekvelden en voorbeelden weer. De servicestatus van uw account en de limieten van uw sleutel zijn op alle items van toepassing.
Een API-sleutel identificeert een account. Het is geen openbaar downloadwachtwoord voor een bestand.
Verzoekheader
Gebruik X-API-Key: sk_… of Authorization: Bearer sk_…, één van de twee per verzoek. Stuur Content-Type: application/json met JSON-lichamen.
Wat een sleutel kan bereiken
Een sleutel heeft alleen toegang tot de resources die zijn account mag gebruiken; de servicestatus, het budget van de sleutel en de toegestane vertaalinstellingen blijven van kracht. Wijzigingen in het account en het aanmaken, roteren of intrekken van sleutels gebeuren in de console.
Zie authenticatie, budgetten en rotatie en diensten en machtigingen .
Een time-out betekent niet dat de taak niet is aangemaakt. Maak onderscheid tussen herhaalbare fouten en verzoeken die moeten worden gecorrigeerd, zodat niets dubbel wordt ingediend of verwerkt.
Idempotency-Key voor elke nieuwe aanmaakbewerking; wanneer u dezelfde bewerking opnieuw probeert, hergebruikt u de oorspronkelijke sleutel en exact dezelfde verzoekbody. Documentbewerkingen, mediataken en spraakaanmaak vereisen de sleutel; voor andere aanmaak-eindpunten zie hun referentiepagina’s.| Status | Controleer eerst | Wat te doen |
|---|---|---|
401 / 403 | Sleutel, machtigingen, eigendom van resources | Los de inloggegevens of machtigingen op; probeer niet blindelings opnieuw |
402 | Beschikbare tegoeden | Laad op en dien vervolgens opnieuw in |
409 | Idempotentiesleutel en -inhoud, resourcestatus | Query de oorspronkelijke bewerking voordat u een nieuwe start |
422 | Veldfouten in de respons | Los de parameters of het bestand op |
429 | Zakelijk code en Retry-After | Tarief- en wachtrijlimieten kunnen worden afgewacht; een opgebruikt sleutelbudget moet eerst worden verhoogd. |
5xx | Tijdelijke servicefout | Beperkte exponentiële backoff; behoud de idempotentiesleutel voor aanmaakverzoeken |
Behoud de X-Request-Id responsheader, het verzoekmoment en het pad voor probleemoplossing; log nooit de volledige sleutel. Alle foutcodes en retry-voorbeelden staan in de foutreferentie .
Geen credits
Het uploaden, controleren van taken, downloaden van resultaten en lezen van het saldo en de afrekeningsgegevens kosten geen credits; evenmin kost dit voor woordenlijsten, projecten, tags, zoeken en delen.
Gefactureerd op basis van gebruik
Bestandstranslatie, documenttools, directe vertaling en audio- en videodiensten worden tegen hun tarieven afgerekend op basis van het daadwerkelijke gebruik; het aanmaken van een taak is niet de uiteindelijke kostenpost.
Voordat een taak start, wordt alleen de saldodrempel gecontroleerd; na afloop wordt het werkelijke gebruik in rekening gebracht. Als het saldo onvoldoende is, wordt het verschil als schuld geregistreerd, en later binnenkomende tegoeden worden eerst hiervoor gebruikt. U kunt kosten en terugbetalingen per taak of per tegoedtransactie reconciliëren. Wanneer het budget van een sleutel op is, kunt u nog steeds de taken, resultaten en records onder die sleutel opvragen.