generate_image is one typed Python call to the text-to-image API: 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.
Generate and save images
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 backendEach 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.
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 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 lists those defaults.
Malformed values raise ValidationError before any request is made:
modelandpromptmust be non-emptynmust be between 1 and 10sizemust beWIDTHxHEIGHTwith 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 ofImageGenerationData, one per image. Each carriesb64_json, the base64-encoded PNG, andrevised_prompt, the backend's rewrite of your prompt if it made one, otherwiseNone.warnings: a list of non-fatal notices from the backend, orNone.
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:
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:
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 links the model's prompt-upsampling guidance.
Where next
- Text to image: the HTTP endpoint, server-side defaults, and model details.
- Models: list the image-capable models in your org.
- SDK overview: configuration, authentication, and the error hierarchy.