chore: import upstream snapshot with attribution

docs-website/docs/pipeline-components/generators/openaiimagegenerator.mdx

@@ -0,0 +1,98 @@
+---
+title: "OpenAIImageGenerator"
+id: openaiimagegenerator
+slug: "/openaiimagegenerator"
+description: "Generate images using OpenAI's image generation models such as `gpt-image-2`."
+---
+
+# OpenAIImageGenerator
+
+Generate images using OpenAI's image generation models such as `gpt-image-2`.
+
+<div className="key-value-table">
+
+|  |  |
+| --- | --- |
+| **Most common position in a pipeline** | After a [`PromptBuilder`](../builders/promptbuilder.mdx), flexible |
+| **Mandatory init variables** | `api_key`: An OpenAI API key. Can be set with `OPENAI_API_KEY` env var. |
+| **Mandatory run variables** | `prompt`: A string containing the prompt for the model |
+| **Output variables** | `images`: A list of generated images  <br /> <br />`revised_prompt`: A string containing the prompt that was used to generate the image, if there was any revision to the prompt made by OpenAI |
+| **API reference** | [Generators](/reference/generators-api) |
+| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/generators/openai_image_generator.py |
+| **Package name** | `haystack-ai` |
+
+</div>
+
+## Overview
+
+The `OpenAIImageGenerator` component generates images using OpenAI's image generation models (such as `gpt-image-2`).
+
+By default, the component uses the `gpt-image-2` model, `"auto"` quality, and 1024x1024 resolution. You can change these parameters using `model` (during component initialization), `quality`, and `size` (during component initialization or run) parameters.
+
+`OpenAIImageGenerator` needs an OpenAI key to work. It uses an `OPENAI_API_KEY` environment variable by default. Otherwise, you can pass an API key at initialization with `api_key`:
+
+```
+image_generator = OpenAIImageGenerator(api_key=Secret.from_token("<your-api-key>"))
+```
+
+Check our [API reference](/reference/generators-api#openaiimagegenerator) for the detailed component parameters description, or the [OpenAI documentation](https://developers.openai.com/api/reference/resources/images/methods/generate) for the details on OpenAI API parameters.
+
+## Usage
+
+### On its own
+
+```python
+from haystack.components.generators import OpenAIImageGenerator
+
+image_generator = OpenAIImageGenerator()
+response = image_generator.run("Show me a picture of a black cat.")
+
+print(response)
+```
+
+### In a pipeline
+
+In the following pipeline, we first set up a `PromptBuilder` that will structure the image description with a detailed template describing various artistic elements. The pipeline then passes this structured prompt into an `OpenAIImageGenerator` to generate the image based on this detailed description.
+
+```python
+from haystack import Pipeline
+from haystack.components.generators import OpenAIImageGenerator
+from haystack.components.builders import PromptBuilder
+
+prompt_builder = PromptBuilder(
+    template="""Create a {style} image with the following details:
+
+                Main subject: {prompt}
+                Artistic style: {art_style}
+                Lighting: {lighting}
+                Color palette: {colors}
+                Composition: {composition}
+                Additional details: {details}""",
+)
+
+image_generator = OpenAIImageGenerator()
+
+pipeline = Pipeline()
+pipeline.add_component("prompt_builder", prompt_builder)
+pipeline.add_component("image_generator", image_generator)
+
+pipeline.connect("prompt_builder.prompt", "image_generator.prompt")
+
+results = pipeline.run(
+    {
+        "prompt": "a mystical treehouse library",
+        "style": "photorealistic",
+        "art_style": "fantasy concept art with intricate details",
+        "lighting": "dusk with warm lantern light glowing from within",
+        "colors": "rich earth tones, deep greens, and golden accents",
+        "composition": "wide angle view showing the entire structure nestled in an ancient oak tree",
+        "details": "spiral staircases wrapping around branches, stained glass windows, floating books, and magical fireflies providing ambient illumination",
+    },
+)
+
+generated_images = results["image_generator"]["images"]
+revised_prompt = results["image_generator"]["revised_prompt"]
+
+print(f"Generated image (base64-encoded): {generated_images[0]}")
+print(f"Revised prompt: {revised_prompt}")
+```