> ## 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.

# End to End Image Translation

> Creates a task to translate the text in an image or PDF into one or more target languages while keeping the original design. Send a multipart form with a source language, target languages, and a media URL.

## Localizing Images and PDFs

Our image translation service localizes your images and PDFs by translating the text inside them while keeping the original design. It works on posters, signage, screenshots, menus, comics, and multi-page documents, in as many target languages as you need in a single call. This endpoint initiates an image translation task and returns a `run_id` and a `task_id` that allow you to track and retrieve your results.

## Language Selection

Image translation needs `source_language` and `target_languages` in the form body:

* **`source_language`**: the language of the text in your image. Locale tag (e.g. `en-us`) or numeric ID.
* **`target_languages`**: one or more output languages as a comma-separated string, for example `es-es` or `es-es,pt-br`. The SDKs accept an array and join it for you.

> [card]
>
> For a complete list of supported languages and their locale tags, see [source languages](https://docs.camb.ai/api-reference/endpoint/get-source-languages.md) and [target languages](https://docs.camb.ai/api-reference/endpoint/get-target-languages.md).
>
> [Open](https://docs.camb.ai/api-reference/endpoint/get-target-languages.md)

### Supported Media Formats

Provide a publicly accessible `media_url`. For optimal results, we recommend using high-resolution images with clearly legible text. Our service accepts the following formats:

* PNG (`.png`)
* JPG / JPEG (`.jpg`, `.jpeg`)
* WEBP (`.webp`)
* PDF (`.pdf`)
* ZIP of page images (`.zip`), for multi-page sources

> [!NOTE]
>
> PDF and ZIP inputs are split into pages automatically.

## Export Format

The result is always delivered as a ZIP. The optional `export_format` field controls what is inside it:

* **`ZIP`** (default): the translated page images.
* **`PDF`**: one PDF per target language.

Omit the field to use `ZIP`. You can also change the format later with the [export endpoint](https://docs.camb.ai/api-reference/endpoint/export-image-translation.md).

## Request Example

Create an image translation task by sending a multipart form. Here's how to request a Spanish translation of a hosted image using Python with the `requests` library:

```python [expandable] theme={null}
import os
import requests

def create_image_translation(
    api_key,
    media_url,
    source_language="en-us",
    target_languages="es-es",
    export_format="ZIP",
):
    """
    Initiates an image translation task from a media URL.

    Args:
        api_key (str): API authentication key
        media_url (str): Public URL of the image, PDF, or ZIP of page images
        source_language (str): Locale tag like "en-us"
        target_languages (str): Comma-separated locale tags, e.g. "es-es,pt-br"
        export_format (str): "ZIP" (page images) or "PDF" (one PDF per language)

    Returns:
        dict: Response containing run_id and task_id for tracking
    """
    url = "https://client.camb.ai/apis/image-translation"
    headers = {"x-api-key": api_key}
    data = {
        "source_language": source_language,
        "target_languages": target_languages,
        "export_format": export_format,
        "media_url": media_url,
    }

    response = requests.post(url, headers=headers, data=data)

    if response.ok:
        return response.json()
    print(f"Error {response.status_code}: {response.text}")
    return None

# Translate a poster from English into Spanish
result = create_image_translation(
    api_key=os.environ["CAMB_API_KEY"],
    media_url="https://example.com/image.png",
    source_language="en-us",
    target_languages="es-es",
)
```

Optional form fields include `project_name`, `project_description`, and `folder_id`.

## Next Steps: Monitoring Your Image Translation Task

After submitting your request, you'll want to monitor its progress and retrieve the results once processing completes:

1. Use the [`/image-translation/{task_id}`](get-end-to-end-image-translation-status) endpoint to check your task's status
2. Poll the status endpoint at reasonable intervals (we recommend 5-15 second intervals for most cases)
3. Once the status shows as `SUCCESS`, retrieve your translated pages from [`/image-translation/result/{run_id}`](get-image-translation-result)

> [!NOTE]
>
> Want to review individual text regions or adjust a translation? Use [Get Image Translation Project](https://docs.camb.ai/api-reference/endpoint/get-image-translation-project.md) to inspect the regions, then [Fine-Tune Image Translation](https://docs.camb.ai/api-reference/endpoint/fine-tune-image-translation.md) to refine one.


## OpenAPI

````yaml post /image-translation
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers:
  - url: https://client.camb.ai/apis
security: []
paths:
  /image-translation:
    post:
      tags:
        - Apis
        - Image Translation
      summary: End To End Image Translation
      description: >-
        Translate the text in an image or PDF into one or more target languages
        while keeping the original design. Returns `run_id` and `task_id`.
      operationId: create_image_translation_image_translation_post
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: >-
                #/components/schemas/Body_create_image_translation_image_translation_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageTextEditCreateOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
components:
  schemas:
    Body_create_image_translation_image_translation_post:
      allOf:
        - $ref: '#/components/schemas/CreateTaskWithNameAndDescription'
        - type: object
          properties:
            source_language:
              $ref: '#/components/schemas/LanguageInput'
              description: >-
                Language of the text in the source image. Pass a locale tag
                (`en-us`) or a numeric language ID. [See all source
                languages](/api-reference/endpoint/get-source-languages).
              example: en-us
            target_languages:
              type: string
              title: Target Languages
              description: >-
                Comma-separated target languages as locale tags or language IDs
                (e.g. `es-es` or `es-es,pt-br`). The SDKs take an array and join
                it. [See all target
                languages](/api-reference/endpoint/get-target-languages).
              example: es-es
            media_url:
              type: string
              title: Media URL
              description: URL of the image, PDF, or ZIP of page images.
              example: null
            export_format:
              $ref: '#/components/schemas/ImageTextEditExportFormat'
              description: >-
                `ZIP` (default) is a ZIP of page images. `PDF` is a ZIP of
                per-language PDFs. The download is always a ZIP.
              default: ZIP
            folder_id:
              type: integer
              title: Folder Id
              description: >-
                Optional Studio folder to store the run in. Must belong to the
                API key's team.
              nullable: true
              example: null
          required:
            - source_language
            - target_languages
            - media_url
      title: Body_create_image_translation_image_translation_post
    ImageTextEditCreateOut:
      type: object
      title: ImageTextEditCreateOut
      required:
        - run_id
        - task_id
      properties:
        run_id:
          type: integer
          title: Run ID
          description: >-
            Stable identifier for this image translation run. Use it with
            result, project, export, and fine-tune.
        task_id:
          type: string
          title: Task ID
          description: >-
            Poll `GET /image-translation/{task_id}` until status is SUCCESS or
            ERROR.
    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
    ImageTextEditExportFormat:
      type: string
      enum:
        - ZIP
        - PDF
      default: ZIP
      title: ImageTextEditExportFormat
      description: >-
        `ZIP` of page images (default) or `PDF` (a ZIP of per-language PDFs).
        The result download is always a ZIP.
    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.