Get API key

Image generation

View as Markdown

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: 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

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 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:

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