> ## Documentation Index > Fetch the complete documentation index at: https://docs.camb.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create Document Translation > Translate DOCX or SRT documents while preserving a document-based workflow and optional terminology guidance. Use this endpoint when you want to translate a document file instead of an array of text strings. Submit a document with its source and target languages, and CAMB.AI starts an asynchronous document translation task. The response includes a `task_id`. Poll [Get Document Translation Status](https://docs.camb.ai/api-reference/endpoint/get-doc-translation-status.md) until the task reaches `SUCCESS`, then use the returned `run_id` with [Get Document Translation Result](https://docs.camb.ai/api-reference/endpoint/get-doc-translation-result.md) to retrieve the translated document download URL. ## Response The create response contains only the task identifier: * `task_id`: the identifier for the asynchronous document translation task. It does not return a `run_id` at creation time. The `run_id` is available from [Get Document Translation Status](https://docs.camb.ai/api-reference/endpoint/get-doc-translation-status.md) once the task reaches `SUCCESS`. ```json theme={null} { "task_id": "7f1b7a4c-8e6d-4c1a-9a5d-2f0f9d8c1234" } ``` ## Supported Inputs Provide either: * `media_file`: upload the document directly as multipart form data. * `media_url`: provide a URL to the document file. Supported document formats include DOCX and SRT. DOCX is useful for document workflows where the translated output should remain a downloadable document. SRT is useful when you already have subtitle timing and want the subtitle text translated while keeping the file-based workflow. ## Language and Terminology * `source_language`: the language of the source document. * `target_language`: the language to translate into. * `chosen_dictionaries`: optional dictionary IDs to enforce approved terminology. * `translation_style`: optional guidance for tone, wording, or terminology preferences. Omit this field when you do not need custom style instructions. Use [Get Source Languages](https://docs.camb.ai/api-reference/endpoint/get-source-languages.md) and [Get Target Languages](https://docs.camb.ai/api-reference/endpoint/get-target-languages.md) to find supported language tags and IDs. ## DOCX Example ```python [expandable] theme={null} import requests API_KEY = "your-api-key" BASE_URL = "https://client.camb.ai/apis" headers = {"x-api-key": API_KEY} with open("source.docx", "rb") as document: response = requests.post( f"{BASE_URL}/translate-doc", headers=headers, data={ "source_language": "en-us", "target_language": "fr-fr", }, files={ "media_file": ( "source.docx", document, "application/vnd.openxmlformats-officedocument.wordprocessingml.document", ) }, ) response.raise_for_status() task = response.json() print(task["task_id"]) ``` ## SRT Example ```python [expandable] theme={null} import requests API_KEY = "your-api-key" BASE_URL = "https://client.camb.ai/apis" headers = {"x-api-key": API_KEY} with open("captions.srt", "rb") as subtitles: response = requests.post( f"{BASE_URL}/translate-doc", headers=headers, data={ "source_language": "en-us", "target_language": "es-es", }, files={ "media_file": ( "captions.srt", subtitles, "application/x-subrip", ) }, ) response.raise_for_status() task = response.json() print(task["task_id"]) ``` > [!NOTE] > > Document translation is asynchronous. Store the `task_id` from this response so you can poll task status and fetch the final download URL. ## OpenAPI ````yaml post /translate-doc openapi: 3.1.0 info: title: FastAPI version: 0.1.0 servers: - url: https://client.camb.ai/apis security: [] paths: /translate-doc: post: tags: - Apis - Document Translation summary: Create Document Translation operationId: create_doc_translation_translate_doc_post parameters: [] requestBody: required: true content: multipart/form-data: schema: $ref: >- #/components/schemas/Body_create_doc_translation_translate_doc_post responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/CreateDocTranslationOut' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - APIKeyHeader: [] components: schemas: Body_create_doc_translation_translate_doc_post: allOf: - $ref: '#/components/schemas/CreateTaskWithNameAndDescription' - type: object properties: source_language: $ref: '#/components/schemas/LanguageInput' description: >- Source language of the document. Pass a locale tag (`en-us`, `fr-fr`, `es-es`). Numeric language IDs (`1` or `"1"`) still work but are deprecated. [See all source languages](/api-reference/endpoint/get-source-languages). example: en-us target_language: $ref: '#/components/schemas/LanguageInput' description: >- Target language for the translated document. Pass a locale tag (`fr-fr`, `es-es`, `de-de`). Numeric language IDs still work but are deprecated. [See all target languages](/api-reference/endpoint/get-target-languages). example: fr-fr media_file: type: string format: binary title: Media File description: >- Document file to translate. Supported formats include DOCX and SRT. Leave blank when using `media_url`. media_url: type: string format: uri title: Media URL description: >- URL to a document file for translation. Leave blank when uploading `media_file`. example: '' chosen_dictionaries: $ref: '#/components/schemas/ChosenDictionariesSchema' description: Optional dictionaries to apply during document translation. translation_style: type: string nullable: true title: Translation Style description: Optional free-text guidance for the translation style. required: - source_language - target_language title: Body_create_doc_translation_translate_doc_post CreateDocTranslationOut: type: object properties: task_id: type: string title: Task ID required: - task_id title: CreateDocTranslationOut HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError CreateTaskWithNameAndDescription: properties: project_name: type: string title: Project Name description: >- Enter a distinctive name for your project that reflects its purpose or content. This name will be displayed in your CAMB.AI workspace dashboard and used to organize related assets, transcriptions, etc.. . Choose something memorable that helps you quickly identify this specific project among your other voice, audio and localization tasks. minLength: 3 maxLength: 255 nullable: true example: null project_description: type: string title: Project Description description: >- Provide details about your project's goals and specifications. Include information such as the target languages for translation or dubbing, desired voice characteristics, emotional tones to capture, or specific audio processing requirements, outlining the workflow here can serve as valuable documentation for organizational purposes. minLength: 3 maxLength: 5000 nullable: true example: null LanguageInput: type: string title: Language ChosenDictionariesSchema: type: array nullable: true items: type: integer uniqueItems: true minItems: 1 default: null description: >- An optional list of dictionary IDs selected by the user. Each entry must be an integer corresponding to a valid dictionary ID. If provided, at least one ID is required. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError securitySchemes: APIKeyHeader: type: apiKey in: header name: x-api-key description: >- The `x-api-key` is a custom header required for authenticating requests to our API. Include this header in your request with the appropriate API key value to securely access our endpoints. You can find your API key(s) in the 'API' section of our studio website. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.