Ga naar inhoud

Breng documentworkflows naar uw app

Van het uploaden van één bestand tot het vertalen ervan, het controleren van de voortgang en het downloaden van het resultaat. Elke stap wordt uitgelegd in de volgorde waarin u integreert, met invoerpunten voor bestandsbeheer, documentverwerking en audio- en videodiensten.

Base URL https://omnidoc.top/api/v1 · HTTPS · JSON · API-sleutelauthenticatie · bestandstranslaties worden uitgevoerd als asynchrone taken

Deze site beschrijft de cloud HTTP API.

01 Begin met een verzoek dat geen credits kost

Section titled “01 Begin met een verzoek dat geen credits kost”

Controleer of uw sleutel en netwerk werken voordat u bestanden uploadt. Een saldocontrole kost geen credits en genereert geen vertaalopdracht.

  1. 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.

  2. 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.

    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"

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.

StapMethode en padWat moet behouden blijven
Vraag een upload aanPOST /upload/presignupload_url, upload_headers, finalize_token
Verzend het bestandPUT naar de geretourneerde upload_urlSuccesrespons; dit verzoek bevat geen API-sleutel
Bevestig de uploadPOST /upload/finalizedocument.id
Maak een vertalingPOST /jobsJob id
Controleer de statusGET /jobs/{job_id}completed of failed
Geef de resultaten weerGET /artifacts?job_id={job_id}Artefact-ID’s en -indelingen
Download een resultaatGET /artifacts/{artifact_id}/downloadBestandsbytes 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 .

05 Bouwfoutafhandeling in de integratie opnemen

Section titled “05 Bouwfoutafhandeling in de integratie opnemen”

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.

  • Idempotente creatie : genereer een 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.
  • Asynchrone meldingen : polling is prima voor een eerste integratie; voor continue voortgang gebruik SSE , en om eindstatussen op de achtergrond te ontvangen gebruik je een webhook .
StatusControleer eerstWat te doen
401 / 403Sleutel, machtigingen, eigendom van resourcesLos de inloggegevens of machtigingen op; probeer niet blindelings opnieuw
402Beschikbare tegoedenLaad op en dien vervolgens opnieuw in
409Idempotentiesleutel en -inhoud, resourcestatusQuery de oorspronkelijke bewerking voordat u een nieuwe start
422Veldfouten in de responsLos de parameters of het bestand op
429Zakelijk code en Retry-AfterTarief- en wachtrijlimieten kunnen worden afgewacht; een opgebruikt sleutelbudget moet eerst worden verhoogd.
5xxTijdelijke servicefoutBeperkte 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 .

06 Controleer hoe de facturering werkt voordat u integreert

Section titled “06 Controleer hoe de facturering werkt voordat u integreert”

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.