Maak een vertaalopdracht aan
POST /api/v1/jobsIdempotency-Key: 7a40d1c7-6ee8-4cc1-b74b-132792bd402fContent-Type: application/jsonVerzoek
Section titled “Verzoek”| Veld | Type | Vereist | Standaard | Beschrijving |
|---|---|---|---|---|
document_id | string | ✅ | — | ID van een bevestigd document |
target_lang | string | ✅ | — | Doeltaalcodel |
source_lang | string | — | Automatisch detecteren | Broncode |
engine | string | — | xr-397b | Vertaalinstelling-ID, zie vertaalinstellingen |
output_mode | string | — | bilingual | single of bilingual |
glossary_id | string | — | — | Een verklarende woordenlijst-ID van dit account. Verklarende woordenlijsten zijn bedoeld voor betalende accounts (minimaal één succesvolle betaling); een onbetaald account dat er één verzendt, krijgt 403 |
include_images | booleaanse waarde | — | false | Vertaal ook de tekst in de afbeeldingen van het document. |
context_translation | booleaanse waarde | — | false | Schakel contextverbetering in |
style_preset | string | — | — | Stijlvoorinstelling |
Een aangemaakte taak komt in de wachtrij. Elk account verwerkt maximaal 5 bestanden tegelijk; verdere taken worden automatisch aangemaakt en in de wachtrij geplaatst, beginnend zodra eerdere taken zijn voltooid. Terwijl een taak wacht, geeft zijn stage_message aan hoeveel taken er vóór staan.
Voordat een taak wordt gestart, wordt het saldo gecontroleerd tegen een drempelwaarde: een PDF vereist een saldo boven “pagina’s × 2 credits”; andere formaten worden beoordeeld op basis van de lengte van de brontekst, minimaal 2 credits. Als het saldo geen bestand kan starten, eindigt die taak met status=failed en quota_exceeded=true, er worden geen kosten in rekening gebracht en andere taken worden niet beïnvloed. Wanneer een taak is voltooid, worden de werkelijke gebruikskosten in rekening gebracht; als de kosten het saldo overschrijden, gaat het saldo in de min, binnenkomende credits worden eerst gebruikt om de schuld af te lossen, en nieuwe taken kunnen niet worden gestart zolang het saldo negatief is, dus vul het saldo aan. Zie credits en gebruik .
Voorbeeld
Section titled “Voorbeeld”curl --fail-with-body -X POST https://omnidoc.top/api/v1/jobs \ -H "X-API-Key: $OMNIDOC_API_KEY" \ -H "Idempotency-Key: 7a40d1c7-6ee8-4cc1-b74b-132792bd402f" \ -H "Content-Type: application/json" \ -d '{"document_id":"4q8mx2q9z1k7p6ra","target_lang":"en"}'Reactie 201 (de stage_message van de server is in het Chinees):
{ "id": "q3f8s6c2a9m1k4tx", "document_id": "4q8mx2q9z1k7p6ra", "source_lang": null, "target_lang": "en", "engine": "xr-397b", "status": "pending", "stage": "queued", "stage_progress": 0, "stage_message": "排队中", "time_cost": 0, "error_msg": null, "quota_exceeded": false, "queue_position": null, "created_at": "2026-10-01T12:01:00Z", "updated_at": "2026-10-01T12:01:00Z"}Fouten
Section titled “Fouten”| Status | Oorzaak |
|---|---|
403 | De sleutel staat de gekozen instelling niet toe, of een onbetaald account heeft glossary_id verzonden |
404 | Het document of de woordenlijst bestaat niet, is verwijderd of behoort toe aan een ander account |
415 | Het bestandsformaat kan niet worden vertaald |
422 | Het bestand is leeg, bevat geen vertaalbare tekst of een parameter is ongeldig. |
429 | Te veel verzoeken, of de wachtrij is vol; probeer het opnieuw na Retry-After |
Idempotentie
Section titled “Idempotentie”Idempotency-Key is optioneel, maar wordt voor elke inzending aanbevolen. Een sleutel bestaat uit 1 tot 128 zichtbare ASCII-tekens en blijft onbeperkt geldig voor dezelfde referentie:
- Zelfde sleutel, zelfde lichaam: retourneert de oorspronkelijke taak (inclusief een mislukte); er wordt niets tweemaal aangemaakt of in rekening gebracht.
- Zelfde sleutel, ander lichaam:
409(idempotency_request_conflict). - De oorspronkelijke taak is verwijderd:
410(idempotency_job_gone).
Gebruik voor elke nieuwe inzending een nieuw UUID en hergebruik de oorspronkelijke sleutel alleen bij het opnieuw proberen van diezelfde inzending.