1  ---
  2  title: "Image Converters"
  3  id: image-converters-api
  4  description: "Various converters to transform image data from one format to another."
  5  slug: "/image-converters-api"
  6  ---
  7  
  8  <a id="document_to_image"></a>
  9  
 10  ## Module document\_to\_image
 11  
 12  <a id="document_to_image.DocumentToImageContent"></a>
 13  
 14  ### DocumentToImageContent
 15  
 16  Converts documents sourced from PDF and image files into ImageContents.
 17  
 18  This component processes a list of documents and extracts visual content from supported file formats, converting
 19  them into ImageContents that can be used for multimodal AI tasks. It handles both direct image files and PDF
 20  documents by extracting specific pages as images.
 21  
 22  Documents are expected to have metadata containing:
 23  - The `file_path_meta_field` key with a valid file path that exists when combined with `root_path`
 24  - A supported image format (MIME type must be one of the supported image types)
 25  - For PDF files, a `page_number` key specifying which page to extract
 26  
 27  ### Usage example
 28      ```python
 29      from haystack import Document
 30      from haystack.components.converters.image.document_to_image import DocumentToImageContent
 31  
 32      converter = DocumentToImageContent(
 33          file_path_meta_field="file_path",
 34          root_path="/data/files",
 35          detail="high",
 36          size=(800, 600)
 37      )
 38  
 39      documents = [
 40          Document(content="Optional description of image.jpg", meta={"file_path": "image.jpg"}),
 41          Document(content="Text content of page 1 of doc.pdf", meta={"file_path": "doc.pdf", "page_number": 1})
 42      ]
 43  
 44      result = converter.run(documents)
 45      image_contents = result["image_contents"]
 46      # [ImageContent(
 47      #    base64_image='/9j/4A...', mime_type='image/jpeg', detail='high', meta={'file_path': 'image.jpg'}
 48      #  ),
 49      #  ImageContent(
 50      #    base64_image='/9j/4A...', mime_type='image/jpeg', detail='high',
 51      #    meta={'page_number': 1, 'file_path': 'doc.pdf'}
 52      #  )]
 53      ```
 54  
 55  <a id="document_to_image.DocumentToImageContent.__init__"></a>
 56  
 57  #### DocumentToImageContent.\_\_init\_\_
 58  
 59  ```python
 60  def __init__(*,
 61               file_path_meta_field: str = "file_path",
 62               root_path: Optional[str] = None,
 63               detail: Optional[Literal["auto", "high", "low"]] = None,
 64               size: Optional[tuple[int, int]] = None)
 65  ```
 66  
 67  Initialize the DocumentToImageContent component.
 68  
 69  **Arguments**:
 70  
 71  - `file_path_meta_field`: The metadata field in the Document that contains the file path to the image or PDF.
 72  - `root_path`: The root directory path where document files are located. If provided, file paths in
 73  document metadata will be resolved relative to this path. If None, file paths are treated as absolute paths.
 74  - `detail`: Optional detail level of the image (only supported by OpenAI). Can be "auto", "high", or "low".
 75  This will be passed to the created ImageContent objects.
 76  - `size`: If provided, resizes the image to fit within the specified dimensions (width, height) while
 77  maintaining aspect ratio. This reduces file size, memory usage, and processing time, which is beneficial
 78  when working with models that have resolution constraints or when transmitting images to remote services.
 79  
 80  <a id="document_to_image.DocumentToImageContent.run"></a>
 81  
 82  #### DocumentToImageContent.run
 83  
 84  ```python
 85  @component.output_types(image_contents=list[Optional[ImageContent]])
 86  def run(documents: list[Document]) -> dict[str, list[Optional[ImageContent]]]
 87  ```
 88  
 89  Convert documents with image or PDF sources into ImageContent objects.
 90  
 91  This method processes the input documents, extracting images from supported file formats and converting them
 92  into ImageContent objects.
 93  
 94  **Arguments**:
 95  
 96  - `documents`: A list of documents to process. Each document should have metadata containing at minimum
 97  a 'file_path_meta_field' key. PDF documents additionally require a 'page_number' key to specify which
 98  page to convert.
 99  
100  **Raises**:
101  
102  - `ValueError`: If any document is missing the required metadata keys, has an invalid file path, or has an unsupported
103  MIME type. The error message will specify which document and what information is missing or incorrect.
104  
105  **Returns**:
106  
107  Dictionary containing one key:
108  - "image_contents": ImageContents created from the processed documents. These contain base64-encoded image
109  data and metadata. The order corresponds to order of input documents.
110  
111  <a id="file_to_document"></a>
112  
113  ## Module file\_to\_document
114  
115  <a id="file_to_document.ImageFileToDocument"></a>
116  
117  ### ImageFileToDocument
118  
119  Converts image file references into empty Document objects with associated metadata.
120  
121  This component is useful in pipelines where image file paths need to be wrapped in `Document` objects to be
122  processed by downstream components such as the `SentenceTransformersImageDocumentEmbedder`.
123  
124  It does **not** extract any content from the image files, instead it creates `Document` objects with `None` as
125  their content and attaches metadata such as file path and any user-provided values.
126  
127  ### Usage example
128  ```python
129  from haystack.components.converters.image import ImageFileToDocument
130  
131  converter = ImageFileToDocument()
132  
133  sources = ["image.jpg", "another_image.png"]
134  
135  result = converter.run(sources=sources)
136  documents = result["documents"]
137  
138  print(documents)
139  
140  # [Document(id=..., meta: {'file_path': 'image.jpg'}),
141  # Document(id=..., meta: {'file_path': 'another_image.png'})]
142  ```
143  
144  <a id="file_to_document.ImageFileToDocument.__init__"></a>
145  
146  #### ImageFileToDocument.\_\_init\_\_
147  
148  ```python
149  def __init__(*, store_full_path: bool = False)
150  ```
151  
152  Initialize the ImageFileToDocument component.
153  
154  **Arguments**:
155  
156  - `store_full_path`: If True, the full path of the file is stored in the metadata of the document.
157  If False, only the file name is stored.
158  
159  <a id="file_to_document.ImageFileToDocument.run"></a>
160  
161  #### ImageFileToDocument.run
162  
163  ```python
164  @component.output_types(documents=list[Document])
165  def run(
166      *,
167      sources: list[Union[str, Path, ByteStream]],
168      meta: Optional[Union[dict[str, Any], list[dict[str, Any]]]] = None
169  ) -> dict[str, list[Document]]
170  ```
171  
172  Convert image files into empty Document objects with metadata.
173  
174  This method accepts image file references (as file paths or ByteStreams) and creates `Document` objects
175  without content. These documents are enriched with metadata derived from the input source and optional
176  user-provided metadata.
177  
178  **Arguments**:
179  
180  - `sources`: List of file paths or ByteStream objects to convert.
181  - `meta`: Optional metadata to attach to the documents.
182  This value can be a list of dictionaries or a single dictionary.
183  If it's a single dictionary, its content is added to the metadata of all produced documents.
184  If it's a list, its length must match the number of sources, as they are zipped together.
185  For ByteStream objects, their `meta` is added to the output documents.
186  
187  **Returns**:
188  
189  A dictionary containing:
190  - `documents`: A list of `Document` objects with empty content and associated metadata.
191  
192  <a id="file_to_image"></a>
193  
194  ## Module file\_to\_image
195  
196  <a id="file_to_image.ImageFileToImageContent"></a>
197  
198  ### ImageFileToImageContent
199  
200  Converts image files to ImageContent objects.
201  
202  ### Usage example
203  ```python
204  from haystack.components.converters.image import ImageFileToImageContent
205  
206  converter = ImageFileToImageContent()
207  
208  sources = ["image.jpg", "another_image.png"]
209  
210  image_contents = converter.run(sources=sources)["image_contents"]
211  print(image_contents)
212  
213  # [ImageContent(base64_image='...',
214  #               mime_type='image/jpeg',
215  #               detail=None,
216  #               meta={'file_path': 'image.jpg'}),
217  #  ...]
218  ```
219  
220  <a id="file_to_image.ImageFileToImageContent.__init__"></a>
221  
222  #### ImageFileToImageContent.\_\_init\_\_
223  
224  ```python
225  def __init__(*,
226               detail: Optional[Literal["auto", "high", "low"]] = None,
227               size: Optional[tuple[int, int]] = None)
228  ```
229  
230  Create the ImageFileToImageContent component.
231  
232  **Arguments**:
233  
234  - `detail`: Optional detail level of the image (only supported by OpenAI). One of "auto", "high", or "low".
235  This will be passed to the created ImageContent objects.
236  - `size`: If provided, resizes the image to fit within the specified dimensions (width, height) while
237  maintaining aspect ratio. This reduces file size, memory usage, and processing time, which is beneficial
238  when working with models that have resolution constraints or when transmitting images to remote services.
239  
240  <a id="file_to_image.ImageFileToImageContent.run"></a>
241  
242  #### ImageFileToImageContent.run
243  
244  ```python
245  @component.output_types(image_contents=list[ImageContent])
246  def run(sources: list[Union[str, Path, ByteStream]],
247          meta: Optional[Union[dict[str, Any], list[dict[str, Any]]]] = None,
248          *,
249          detail: Optional[Literal["auto", "high", "low"]] = None,
250          size: Optional[tuple[int,
251                               int]] = None) -> dict[str, list[ImageContent]]
252  ```
253  
254  Converts files to ImageContent objects.
255  
256  **Arguments**:
257  
258  - `sources`: List of file paths or ByteStream objects to convert.
259  - `meta`: Optional metadata to attach to the ImageContent objects.
260  This value can be a list of dictionaries or a single dictionary.
261  If it's a single dictionary, its content is added to the metadata of all produced ImageContent objects.
262  If it's a list, its length must match the number of sources as they're zipped together.
263  For ByteStream objects, their `meta` is added to the output ImageContent objects.
264  - `detail`: Optional detail level of the image (only supported by OpenAI). One of "auto", "high", or "low".
265  This will be passed to the created ImageContent objects.
266  If not provided, the detail level will be the one set in the constructor.
267  - `size`: If provided, resizes the image to fit within the specified dimensions (width, height) while
268  maintaining aspect ratio. This reduces file size, memory usage, and processing time, which is beneficial
269  when working with models that have resolution constraints or when transmitting images to remote services.
270  If not provided, the size value will be the one set in the constructor.
271  
272  **Returns**:
273  
274  A dictionary with the following keys:
275  - `image_contents`: A list of ImageContent objects.
276  
277  <a id="pdf_to_image"></a>
278  
279  ## Module pdf\_to\_image
280  
281  <a id="pdf_to_image.PDFToImageContent"></a>
282  
283  ### PDFToImageContent
284  
285  Converts PDF files to ImageContent objects.
286  
287  ### Usage example
288  ```python
289  from haystack.components.converters.image import PDFToImageContent
290  
291  converter = PDFToImageContent()
292  
293  sources = ["file.pdf", "another_file.pdf"]
294  
295  image_contents = converter.run(sources=sources)["image_contents"]
296  print(image_contents)
297  
298  # [ImageContent(base64_image='...',
299  #               mime_type='application/pdf',
300  #               detail=None,
301  #               meta={'file_path': 'file.pdf', 'page_number': 1}),
302  #  ...]
303  ```
304  
305  <a id="pdf_to_image.PDFToImageContent.__init__"></a>
306  
307  #### PDFToImageContent.\_\_init\_\_
308  
309  ```python
310  def __init__(*,
311               detail: Optional[Literal["auto", "high", "low"]] = None,
312               size: Optional[tuple[int, int]] = None,
313               page_range: Optional[list[Union[str, int]]] = None)
314  ```
315  
316  Create the PDFToImageContent component.
317  
318  **Arguments**:
319  
320  - `detail`: Optional detail level of the image (only supported by OpenAI). One of "auto", "high", or "low".
321  This will be passed to the created ImageContent objects.
322  - `size`: If provided, resizes the image to fit within the specified dimensions (width, height) while
323  maintaining aspect ratio. This reduces file size, memory usage, and processing time, which is beneficial
324  when working with models that have resolution constraints or when transmitting images to remote services.
325  - `page_range`: List of page numbers and/or page ranges to convert to images. Page numbers start at 1.
326  If None, all pages in the PDF will be converted. Pages outside the valid range (1 to number of pages)
327  will be skipped with a warning. For example, page_range=[1, 3] will convert only the first and third
328  pages of the document. It also accepts printable range strings, e.g.:  ['1-3', '5', '8', '10-12']
329  will convert pages 1, 2, 3, 5, 8, 10, 11, 12.
330  
331  <a id="pdf_to_image.PDFToImageContent.run"></a>
332  
333  #### PDFToImageContent.run
334  
335  ```python
336  @component.output_types(image_contents=list[ImageContent])
337  def run(
338      sources: list[Union[str, Path, ByteStream]],
339      meta: Optional[Union[dict[str, Any], list[dict[str, Any]]]] = None,
340      *,
341      detail: Optional[Literal["auto", "high", "low"]] = None,
342      size: Optional[tuple[int, int]] = None,
343      page_range: Optional[list[Union[str, int]]] = None
344  ) -> dict[str, list[ImageContent]]
345  ```
346  
347  Converts files to ImageContent objects.
348  
349  **Arguments**:
350  
351  - `sources`: List of file paths or ByteStream objects to convert.
352  - `meta`: Optional metadata to attach to the ImageContent objects.
353  This value can be a list of dictionaries or a single dictionary.
354  If it's a single dictionary, its content is added to the metadata of all produced ImageContent objects.
355  If it's a list, its length must match the number of sources as they're zipped together.
356  For ByteStream objects, their `meta` is added to the output ImageContent objects.
357  - `detail`: Optional detail level of the image (only supported by OpenAI). One of "auto", "high", or "low".
358  This will be passed to the created ImageContent objects.
359  If not provided, the detail level will be the one set in the constructor.
360  - `size`: If provided, resizes the image to fit within the specified dimensions (width, height) while
361  maintaining aspect ratio. This reduces file size, memory usage, and processing time, which is beneficial
362  when working with models that have resolution constraints or when transmitting images to remote services.
363  If not provided, the size value will be the one set in the constructor.
364  - `page_range`: List of page numbers and/or page ranges to convert to images. Page numbers start at 1.
365  If None, all pages in the PDF will be converted. Pages outside the valid range (1 to number of pages)
366  will be skipped with a warning. For example, page_range=[1, 3] will convert only the first and third
367  pages of the document. It also accepts printable range strings, e.g.:  ['1-3', '5', '8', '10-12']
368  will convert pages 1, 2, 3, 5, 8, 10, 11, 12.
369  If not provided, the page_range value will be the one set in the constructor.
370  
371  **Returns**:
372  
373  A dictionary with the following keys:
374  - `image_contents`: A list of ImageContent objects.
375