Concepts
Concepts
Section titled “Concepts”Image generation turns a text prompt into a rendered PNG. This page covers the mental model: which engine runs your prompt, what a job is, what you can control, and where the result ends up.
Engines
Section titled “Engines”The model is a choice, not a fixed property of the product. GET /v1/engines reports which engines your workspace can use, and the web app’s engine selector is that same list.
- Fast (
default) — the platform engine. Always available to every workspace, and what you get if you don’t ask for anything. - High quality (
openai) — a higher-quality model that runs on your own OpenAI account. It appears in the list but marked unavailable until you connect OpenAI in Connect, which is where the credential lives; image generation never stores it.
Why bring-your-own for the good one: the credential and the cost stay yours, per workspace, and revoking it in Connect immediately takes the engine away again — there is no second copy to clean up.
Prompts
Section titled “Prompts”You describe the image you want in a prompt. You can also supply a negative prompt — a description of what to keep out of the image (artifacts, styles, objects you don’t want). The negative prompt is optional.
Generation settings
Section titled “Generation settings”A few knobs are tunable per request:
- engine — which model runs the prompt. Defaults to the fast engine.
- width / height — the output resolution, in pixels. Not free-form: the accepted values are
512,576,768, and1024. Anything else is rejected (invalid_width/invalid_height) rather than quietly rounded, so you always know what you got. Defaults to 1024×1024. - steps — how many diffusion steps to run. More steps generally means more detail at the cost of time. Capped at 50, because beyond that each request just burns worker time linearly. Default is 30.
- guidance_scale — how strictly the model follows your prompt versus exploring freely. Default is 7.5.
Omit any of these and the default applies. See the reference for the exact request shape.
The web app
Section titled “The web app”The web app is a chat interface: you describe what you want in conversation rather than filling in a form. It carries an engine selector and a gallery of everything the workspace has generated, so past images are one click away instead of buried in a scrollback.
Generation is asynchronous under the hood. When you submit a prompt, the request becomes a job that moves through a small set of states:
queued— accepted, waiting for a worker.running— the model is generating; progress reports the currentstepout of the total.done— the image is rendered and ready.failed— generation could not complete.
How you observe a job depends on which endpoint you call:
- Streaming (
/v1/generate-and-stream) opens a Server-Sent Event connection and pushesqueued,progress, and a terminaldone(orerror) event. This is what a UI uses to show a live progress bar. - Synchronous (
/v1/generate) blocks and returns the finished result in one JSON response, up to a 120-second ceiling. If the render takes longer than that, the call times out (deadline_exceeded) and you retry — or switch to the streaming endpoint, which has no per-request deadline.
Plan allowances
Section titled “Plan allowances”Two things are metered per workspace and set by your plan: generations per month and concurrent jobs. Consult your plan for the numbers. Note that a workspace over its allowance may be answered with a 429 rather than served, so treat them as real bounds when sizing a batch.
Results land in Drive
Section titled “Results land in Drive”This is the important part: every image you generate is registered in Drive, your workspace’s shared library. There is no separate, per-product image store to manage — Drive is the one library across the entire suite, so an image you make here is immediately reusable in Chat, Studio, or your own code.
Each generated image lands in a per-workspace ImageGen generated folder. The response from a generate call carries:
image_url— a ready-to-load URL for the PNG.drive_file_id— the file’s permanent identifier in Drive.
Because Drive is the system of record, image generation treats it as a hard requirement: a deployment that can’t reach Drive will refuse to generate rather than silently producing images that go nowhere.
How it fits the suite
Section titled “How it fits the suite”Image generation is a peer product, not a standalone island:
- One account, one workspace. You sign in once via Accounts; a single sign-on session follows you across products. The workspace you pick owns every image you create.
- Drive is the sink. Output flows into Drive automatically, attributed to the workspace.
- Generate from Chat. Chat can call image generation on your behalf — ask for an image in a conversation and it’s produced inline, with the file landing in your Drive library.