# Image generation Generate images from Python with generate_image: one typed call over the text-to-image endpoint, base64 PNGs back. `generate_image` is one typed Python call to the [text-to-image API](https://docs.privatemind.com/text-to-image.html): you send a prompt and get back base64-encoded images. You can import it from the module or call it as a method on `Client`. The examples run as they are in a PrivateMind workspace, where the SDK reads its token and base URL from the environment. For configuration, authentication and errors, see the [SDK overview](https://docs.privatemind.com/sdk.html). ## Generate and save images ```python import base64 from privatemind import generate_image resp = generate_image( model="cosmos3-super-text2image", prompt="a tropical beach at sunset, dramatic clouds", size="1024x1024", n=4, ) for i, img in enumerate(resp.data): with open(f"out_{i}.png", "wb") as fh: fh.write(base64.b64decode(img.b64_json)) if resp.warnings: print(resp.warnings) # non-fatal notices from the backend ``` Each entry in `resp.data` holds one image as a base64-encoded PNG string in `b64_json`, which you decode yourself. The call waits until every image is ready. > [!TIP] > The client's per-request timeout is 30 seconds by default. Several images in one call, or a high step count, can take longer. Raise it with `Client(timeout=300)` and call `generate_image` on that client, or pass the client as `client=` to the module-level function. ## Parameters All arguments are keyword-only. `model`, `prompt` and `size` are required, and leaving one out raises `TypeError`. | Parameter | Default | Purpose | |---|---|---| | `model` | required | An image model id. Browse [models](https://docs.privatemind.com/models.html) for what your org has. | | `prompt` | required | The text description to render. | | `size` | required | Output resolution as `WIDTHxHEIGHT`, e.g. `1024x1024`. | | `n` | server default | Number of images to generate, 1 to 10. | | `num_inference_steps` | server default | Diffusion steps. Fewer is faster; more can refine detail. | | `guidance_scale` | server default | How closely the image follows the prompt. | | `flow_shift` | server default | Sampling schedule shift. | | `negative_prompt` | omitted | What to steer away from. | | `seed` | random | Set it for reproducible output. | | `extra_args` | omitted | A dict passed to the backend unchanged. See below. | The SDK sends only what you pass. A parameter you leave unset is left out of the request, and the server's default applies. The [text-to-image page](https://docs.privatemind.com/text-to-image.html) lists those defaults. Malformed values raise `ValidationError` before any request is made: - `model` and `prompt` must be non-empty - `n` must be between 1 and 10 - `size` must be `WIDTHxHEIGHT` with a positive ASCII integer on each side. Surrounding whitespace is stripped. Anything else is rejected, including units, leading zeros and non-ASCII digits. A size outside the model's preferred set passes these checks but can come back flagged in `warnings`. ## The response `generate_image` returns a typed `ImageGenerationResponse`: - `created`: Unix timestamp of the generation. - `data`: a list of `ImageGenerationData`, one per image. Each carries `b64_json`, the base64-encoded PNG, and `revised_prompt`, the backend's rewrite of your prompt if it made one, otherwise `None`. - `warnings`: a list of non-fatal notices from the backend, or `None`. ## Reproducible output The same arguments with the same `seed` give the same image. Without a seed, every call is random. To explore a prompt, try several seeds and keep the one you like: ```python import base64 from privatemind import generate_image for seed in (7, 21, 1143): resp = generate_image( model="cosmos3-super-text2image", prompt="a lighthouse in a storm, oil painting", size="1024x1024", seed=seed, ) with open(f"candidate_{seed}.png", "wb") as fh: fh.write(base64.b64decode(resp.data[0].b64_json)) ``` ## Newer backend parameters `extra_args` passes backend parameters the SDK doesn't know about yet. The SDK sends the dict unchanged and checks nothing in it, so a new backend parameter works without an SDK upgrade: ```python resp = generate_image( model="cosmos3-super-text2image", prompt="a tropical beach at sunset", size="1024x1024", extra_args={"new_backend_param": "value"}, # forwarded as-is ) ``` ## Prompt enrichment Before generating, the chat app expands a short prompt into a detailed, structured image description. The SDK doesn't: it sends `prompt` exactly as you pass it. For the same effect, expand your description with a capable LLM and a template you control, then pass the result as `prompt`. The [text-to-image page](https://docs.privatemind.com/text-to-image.html) links the model's prompt-upsampling guidance. ## Where next - [Text to image](https://docs.privatemind.com/text-to-image.html): the HTTP endpoint, server-side defaults, and model details. - [Models](https://docs.privatemind.com/models.html): list the image-capable models in your org. - [SDK overview](https://docs.privatemind.com/sdk.html): configuration, authentication, and the error hierarchy.