Send a translation request
POST /api/v1/translation-requests
Send an EPUB (multipart field file, or the raw file as application/epub+zip with its options in the query string), TXT, DOCX or PDF chapters (multipart, one or more .txt, .docx or .pdf files in file or files, one chapter each, or one TXT or DOCX file split at its chapter headings with split=headings) or a JSON document. One request carries one kind of file.
PDF scans, mixed pages and rotated pages use local OCR. Protected PDFs accept pdf_password; ocr_language chooses a language or automatic script detection. Each PDF remains one chapter; its original page layout is not preserved. OCR warnings travel in intake.decisions.
The request is stored before the answer and its pipeline starts in the worker: 202 Accepted with a Location header. The same content sent again with the same Idempotency-Key or external_id answers 200 with the original request and Idempotent-Replayed: true.
Without the pipeline:start scope, send start=false to import only.
Chapters sent to a volume already translated (volume.latest, or the same volume again) are appended and only they are translated. The request waits its turn in the fair queue at the priority it asks for, and is refused when its token's cost budget is reached.
Scope: content:write, and pipeline:start to start the pipeline.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
Idempotency-Key | header | string | 1–200 printable characters. Sending the same content again with the same key answers |
Request body
application/json · TranslationPayload
Example
{
"external_id": "saga-volume-12",
"series": {
"name": "The Synthetic Saga",
"create_if_missing": true
},
"volume": {
"external_id": "volume-12",
"number": 12,
"title": "Volume 12"
},
"author": "A. Author",
"source_language": "en",
"target_language": "fr",
"chapters": [
{
"external_id": "chapter-001",
"number": 1,
"title": "Chapter 1",
"content": "First paragraph.\n\nSecond paragraph.\n"
}
],
"pipeline": {
"start": true,
"quality": "high",
"context_backend": "hybrid",
"final_review": true
},
"output": {
"format": "json"
},
"callback_url": "https://hooks.example.org/libris"
} multipart/form-data
An EPUB (one file in file), TXT, DOCX or PDF chapters (one or more .txt, .docx or .pdf files in file or files; series or series_id, volume, source_language and target_language required) or one .json document in file with no other field. PDF text is extracted locally, with OCR for scanned, mixed, rotated or undecodable pages. Protected PDFs accept pdf_password; ocr_language defaults to automatic script detection. Each PDF is one chapter without its original layout. Empty fields count as not given; unknown fields are refused.
| Name | Type | Description |
|---|---|---|
file | file | The EPUB, the JSON document or a TXT, DOCX or PDF chapter. |
files | array of file | TXT, DOCX or PDF chapters, one file each, numbered from their names. |
external_id | string | Your identifier of the request (same rules as in the JSON document). Pattern^[A-Za-z0-9][A-Za-z0-9._:/-]{0,199}$. |
series | string | The series by name, created when missing (not with |
series_id | string | The series by id (not with |
volume | integer | string | null | Volume number, 1–10000, or |
volume_external_id | string | Your identifier of the volume. Pattern^[A-Za-z0-9][A-Za-z0-9._:/-]{0,199}$. |
title | string | Volume title (an EPUB keeps its own otherwise). At most 500 characters. |
author | string | Author of the volume. At most 500 characters. |
source_language | string | BCP 47 tag such as |
target_language | string | BCP 47 tag. At most 35 characters. |
provider_id | string | Provider to use; defaults to the volume's, then the series' provider. At most 36 characters. |
quality | string | One of "fast", "normal", "high", "maximum". |
context_backend | string | One of "internal", "openviking", "hybrid". |
start | boolean | Run the whole pipeline (needs the true. |
final_review | boolean | Run the final review (never when the server disables it). Defaulttrue. |
output_format | string | Default format of the result; "json", "txt", "txt-zip", "epub", "epub-bilingual". |
callback_url | string | Webhook called when the request ends; its host must be allowed by an administrator. At most 2000 characters. |
callback_events | string | Comma-separated extra webhooks, for example |
replace_changed_chapters | boolean | Replace chapters already imported with another text (otherwise false. |
discard_human | boolean | With false. |
priority | string | Place in the fair queue: "low", "normal", "high". |
analysis_mode | string |
"parallel", "strict". |
threads | integer | Passages worked on at once, analysis and translation alike (1–64). It can only lower the volume's share of the provider's capacity; default: that share. Minimum 1. Maximum 64. |
escalation_provider_id | string | The volume's stronger model, kept for its hard cases: a passage that comes back to the AI arbitration, and a passage no rung of the recovery could translate. No step of the book moves to it. A setting of the volume: it holds for the requests that follow. Empty string clears it; default: unchanged, then the series', then the server's own choice. |
split | string | TXT or DOCX: "none", "headings". Default "none". |
pdf_password | string | Opening password for protected PDFs. Used only for this import; never stored or returned. The same password applies to the files of the request. At most 1024 characters. |
ocr_language | string | string | null | OCR language as a BCP 47 code (en, fr, ja, zh-Hant…), or |
application/epub+zip · file
Options for a raw EPUB body
With Content-Type: application/epub+zip, the options go in the query string. They are the same as the fields of the multipart upload:
filenameexternal_idseriesseries_idvolumevolume_external_idtitleauthorsource_languagetarget_languageprovider_idqualitycontext_backendstartfinal_reviewoutput_formatcallback_urlcallback_eventsreplace_changed_chaptersdiscard_humanpriorityanalysis_modethreadsescalation_provider_idsplitpdf_passwordocr_language
Responses
| Status | Description | Content |
|---|---|---|
| 200 | Replayed: this content was already sent with this key or Headers: | application/json RequestSummary |
| 202 | Accepted: the request is stored and will run in the worker. Headers: | application/json RequestSummary |
| 401 | A missing, unknown, revoked or expired token, or a disabled account (header Headers: | application/json Error |
| 402 | The token's cost budget is reached ( | application/json Error |
| 403 | The token lacks a scope ( | application/json Error |
| 404 | The series named by | application/json Error |
| 409 | The content cannot be taken as it is. Codes: | application/json Error |
| 413 | The body is above | application/json Error |
| 415 | Neither JSON, EPUB nor multipart. Codes: | application/json Error |
| 422 | The document, the upload or an option is invalid. Codes: | application/json Error |
| 429 | Too many calls for this token (retry after Headers: | application/json Error |
| 500 | Unexpected failure; the message carries a diagnostic reference for the server logs. Codes: | application/json Error |
Example · 200
{
"request_id": "5b1c2d3e-0000-4000-8000-000000000001",
"external_id": "saga-volume-12",
"series_id": "5b1c2d3e-0000-4000-8000-000000000002",
"project_id": "5b1c2d3e-0000-4000-8000-000000000003",
"job_id": "5b1c2d3e-0000-4000-8000-000000000004",
"input": "json",
"status": "pending",
"status_url": "/api/v1/translation-requests/5b1c2d3e-0000-4000-8000-000000000001",
"result_url": "/api/v1/translation-requests/5b1c2d3e-0000-4000-8000-000000000001/result"
} Example · 202
{
"request_id": "5b1c2d3e-0000-4000-8000-000000000001",
"external_id": "saga-volume-12",
"series_id": "5b1c2d3e-0000-4000-8000-000000000002",
"project_id": "5b1c2d3e-0000-4000-8000-000000000003",
"job_id": "5b1c2d3e-0000-4000-8000-000000000004",
"input": "json",
"status": "pending",
"status_url": "/api/v1/translation-requests/5b1c2d3e-0000-4000-8000-000000000001",
"result_url": "/api/v1/translation-requests/5b1c2d3e-0000-4000-8000-000000000001/result"
}