Get Document Translation | SoferAi

from soferai import SoferAI
import uuid
client = SoferAI(
    api_key="YOUR_TOKEN_HERE",
)
client.documents.get_document_translation(
    document_id=uuid.UUID("d5e9c84f-c2b2-4bf4-b4b0-7ffd7a9ffc32"),
    target_language="auto",
)

{
  "document_id": "d5e9c84f-c2b2-4bf4-b4b0-7ffd7a9ffc32",
  "target_language": "auto",
  "translation_style": "translation_style",
  "status": "status",
  "completed_segments": 1,
  "failed_segments": 1,
  "source_word_count": 1,
  "billable_word_count": 1,
  "estimated_api_cost_cents": 1.1,
  "segments": [
    {
      "segment_id": "segment_id",
      "segment_index": 1,
      "source_hash": "source_hash",
      "status": "status",
      "is_stale": true,
      "source_text": "source_text",
      "source_language": "source_language",
      "target_language": "target_language",
      "start_time": 1.1,
      "end_time": 1.1,
      "speaker": "speaker",
      "content": "content",
      "error": "error"
    },
    {
      "segment_id": "segment_id",
      "segment_index": 1,
      "source_hash": "source_hash",
      "status": "status",
      "is_stale": true,
      "source_text": "source_text",
      "source_language": "source_language",
      "target_language": "target_language",
      "start_time": 1.1,
      "end_time": 1.1,
      "speaker": "speaker",
      "content": "content",
      "error": "error"
    }
  ],
  "total_segments": 1,
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z",
  "error": "error"
}

Get the translation for a target language and style, including current status, remaining billable words, estimated API cost, and translated content.

The service rebuilds the document's current paragraphs or pages and compares their hashes with the hashes stored during translation. Changed source content is returned as stale and becomes billable again when translation is requested.

Authentication

AuthorizationBearer

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

Path parameters

document_idUUIDRequired

Stable document ID.

target_languageenumRequired

Target language used when the translation was created, or auto for automatic direction selection.

Allowed values:

Query parameters

translation_stylestringOptional

Translation style ID. Built-ins are default, learning_english for an English target, and sefer_hebrew for a Hebrew target. Omit this to use default. Custom style IDs come from /v1/translation-styles.

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

401

Authentication Error

404

Document Not Found

429

Rate Limit Error