API ReferenceTranslate

Create Document Translation

Start a document translation. Text and transcript documents use paragraph-level translation. **API price:** USD 0.25 per 1,000 billable words, deducted from your API balance. Pricing is prorated to the word: 1,000 billable words costs USD 0.25 and 10,000 billable words costs USD 2.50. Cached current paragraphs are free; stale, missing, failed, forced, or newly added paragraphs are billable. Repeated requests for the same document and translation configuration reuse cached work and the same billing identity, preventing duplicate charges. A document can have multiple translations. Each combination of target language and translation style is stored separately, so the same document can be translated into both English and Hebrew without duplicating the source document.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

document_idUUIDRequired
Stable document ID.

Request

This endpoint expects an object.
target_languageenumOptional

Translation target language. Use en, he, or yi; omit it to use automatic English/Hebrew direction selection. Custom styles and language-specific built-ins require their explicit compatible target language.

Allowed values:
translation_stylestringOptional

Translation style ID. Built-ins are default for a clear natural translation, learning_english for polished Torah-learning English, torah_yiddish for natural beis-medrash Yiddish, and sefer_hebrew for traditional sefer-style Hebrew. Custom style IDs come from /v1/translation-styles. Omit this to use default. learning_english requires target language en, torah_yiddish requires yi, sefer_hebrew requires he, and each custom style declares its compatible language.

forcebooleanOptional
Regenerate the translation even if cached content already exists.

Response

This endpoint returns an object.
document_idUUID
Stable source document ID.
target_languageenum

Requested translation language. With auto, each segment reports its concrete language in its own target_language field.

Allowed values:
translation_stylestring

Translation style ID used for this independently stored target-language translation.

statusstring
Overall translation status.
completed_segmentsinteger
Number of successfully translated paragraphs or pages.
failed_segmentsinteger
Number of failed paragraphs or pages.
source_word_countinteger
Total visible words across the document's current paragraphs or pages, including content that already has a current translation.
billable_word_countinteger

Words in missing, failed, forced, or stale segments that still need translation. Cached current segments are excluded, so this can be zero even when source_word_count is not.

estimated_api_cost_centsdouble

Estimated API balance reservation for the current billable_word_count, in cents, at USD 0.25 per 1,000 words. For example, 25 means USD 0.25 and 250 means USD 2.50. This is an estimate of remaining work, not a historical invoice, and normally becomes zero after all current segments are translated.

segmentslist of objects

Paragraph- or page-level results for this target language and translation style.

total_segmentsintegerOptional
Total paragraphs or pages in the translation job.
created_atdatetimeOptional
When the translation job was created.
updated_atdatetimeOptional
When the translation job was last updated.
errorstringOptional
Overall job error, if any.

Errors

400
Invalid Document
401
Authentication Error
402
Insufficient API Balance
404
Document Not Found
429
Rate Limit Error