PrivateMind
Get API key

Image generation

Generate images from Python with generate_image: one typed call over the text-to-image endpoint, base64 PNGs back.

generate_image wraps the text-to-image API in a single typed call, available as a module-level import and as a method on Client. A prompt goes in, base64-encoded images come back.

Everything on this page runs as-is inside a PrivateMind workspace: the SDK picks up its token and base URL from the environment. Configuration, authentication, and the exception hierarchy live on 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 carries one image as a base64-encoded PNG in b64_json; the SDK hands you the string as-is and leaves decoding to you. Generation is synchronous: the call holds until every image is ready.

Parameters

All arguments are keyword-only, and model, prompt, and size are required: omitting any of them is a 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 strongly the image adheres to the prompt.
flow_shift server default Sampling schedule shift.
negative_prompt omitted What to steer away from.
seed random Fix for reproducible output.
extra_args omitted Dict forwarded to the backend untouched. See below.

The SDK sends only what you pass: a knob you leave unset is omitted from the request and the server's default applies. The current defaults are on the text-to-image page.

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, including units, leading zeros, or non-ASCII digits, is rejected)

Any positive WIDTHxHEIGHT passes local validation; a size outside the model's preferred set 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 revision of your prompt when 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 reproduce the output; without one, every call is random. Sweep seeds to explore a prompt, then 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))

Re-run with the winning seed and the same arguments to get the same image back.

Newer backend parameters

extra_args is the escape hatch for backend parameters the SDK does not know about yet. The dict is forwarded untouched and nothing in it is validated locally, so a parameter added on the backend is usable 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

The chat UI enriches sparse prompts into dense, structured text-to-image descriptions before generating. The SDK does not bundle that step: prompt is sent exactly as you pass it. For the same effect, expand your description with any strong LLM using 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.