Z-Image generation

Z-Image is a lightweight text-to-image model family that runs on Civitai's sdcpp workers. Two variants on the same ecosystem:

`model`	Typical use	Defaults
`turbo`	Default — distilled model, extremely fast and cheap, high enough quality for most workloads	`cfgScale: 1`, `steps: 9`
`base`	Upgrade tier — use when `turbo` isn't delivering enough fidelity for a specific prompt	`cfgScale: 4`, `steps: 20`

Both share the same engine: "sdcpp", ecosystem: "zImage" invocation — they differ in default sampler tuning and the expected usage pattern. Neither supports img2img or image editing; the only operation is createImage.

Default choice: model: "turbo" at cfgScale: 1 / steps: 9. Switch to base (with cfgScale: 4 / steps: 20) when you need more fidelity — better prompt adherence, cleaner detail, or working negative prompts.

Prerequisites

No checkpoint URN needed — the ecosystem ships its own models; you pick between base and turbo via the model field

The request shape

Every Z-Image request is a single imageGen step routed through sdcpp:

json

{
  "$type": "imageGen",
  "input": {
    "engine":    "sdcpp",
    "ecosystem": "zImage",
    "model":     "turbo",        // turbo | base
    "operation": "createImage"
  }
}

The orchestrator dispatches to the matching input schema (ZImageTurboCreateImageGenInput or ZImageBaseCreateImageGenInput), so only the fields valid for that combination are accepted — SubmitWorkflow will 400 on unknown ones.

turbo (default)

Turbo is the distilled Z-Image variant — fast, cheap, and good enough for almost every workload. Low CFG (cfgScale: 1, effectively disabling classifier-free guidance) and short step counts make it the cost/quality sweet spot:

http

POST https://orchestration.civitai.com/v2/consumer/workflows?wait=60
Authorization: Bearer <your-token>
Content-Type: application/json

{
  "steps": [{
    "$type": "imageGen",
    "input": {
      "engine": "sdcpp",
      "ecosystem": "zImage",
      "model": "turbo",
      "operation": "createImage",
      "prompt": "A cozy cabin in the woods at sunset, cinematic lighting",
      "width": 1024,
      "height": 1024,
      "cfgScale": 1,
      "steps": 9
    }
  }]
}

Set your Civitai API token via the Token button in the navbar to enable Try It.

Request body — edit to customize (e.g. swap the image URL or prompt)

Valid JSON

Turbo tuning

Keep cfgScale at 1 and steps at 8–12. Pushing either up negates the turbo speedup without meaningfully improving quality — if you need better output, switch to base instead of cranking turbo's knobs.

Batching with turbo

Turbo's low cost makes it a natural fit for multi-image calls. quantity up to 12 is supported on the schema, though above ~4–6 (depending on dimensions) a call will generally outlast your HTTP client's timeout:

json

{
  "steps": [{
    "$type": "imageGen",
    "input": {
      "engine": "sdcpp",
      "ecosystem": "zImage",
      "model": "turbo",
      "operation": "createImage",
      "prompt": "A majestic fox with flowing tails in an enchanted garden",
      "width": 1024,
      "height": 1024,
      "quantity": 4,
      "cfgScale": 1,
      "steps": 9
    }
  }]
}

Set your Civitai API token via the Token button in the navbar to enable Try It.

Request body — edit to customize (e.g. swap the image URL or prompt)

Valid JSON

For larger batches, submit with wait=0 and poll (see Results & webhooks).

base (fallback when turbo isn't enough)

Step up to base when turbo isn't delivering — prompts that need strong adherence, fine detail work, or negative-prompt conditioning. Higher cfgScale (4 is the default) and more sampler steps (20+) at the cost of higher wall time and spend.

json

{
  "steps": [{
    "$type": "imageGen",
    "input": {
      "engine": "sdcpp",
      "ecosystem": "zImage",
      "model": "base",
      "operation": "createImage",
      "prompt": "A photorealistic portrait of a woman with flowers in her hair, golden hour lighting",
      "width": 1024,
      "height": 1024,
      "cfgScale": 4,
      "steps": 20
    }
  }]
}

Set your Civitai API token via the Token button in the navbar to enable Try It.

Request body — edit to customize (e.g. swap the image URL or prompt)

Valid JSON

With a negative prompt

Z-Image Base honours negative prompts; they steer the model away from undesired content. (Turbo effectively ignores them at cfgScale: 1, so this is one of the cleanest reasons to step up.)

json

{
  "steps": [{
    "$type": "imageGen",
    "input": {
      "engine": "sdcpp",
      "ecosystem": "zImage",
      "model": "base",
      "operation": "createImage",
      "prompt": "A detailed anime character in a magical forest, ethereal lighting, masterpiece",
      "negativePrompt": "blurry, low quality, deformed hands, bad anatomy, watermark, text",
      "width": 1024,
      "height": 1024,
      "cfgScale": 4,
      "steps": 24
    }
  }]
}

Set your Civitai API token via the Token button in the navbar to enable Try It.

Request body — edit to customize (e.g. swap the image URL or prompt)

Valid JSON

With LoRAs

Z-Image LoRAs are a map of AIR URN → strength — same shape as every other sdcpp ecosystem. LoRAs work on both turbo and base; this example is on base because LoRA-driven styles usually benefit from the higher-fidelity tier:

json

{
  "steps": [{
    "$type": "imageGen",
    "input": {
      "engine": "sdcpp",
      "ecosystem": "zImage",
      "model": "base",
      "operation": "createImage",
      "prompt": "A cyberpunk street scene with neon signs and rain reflections",
      "width": 1024,
      "height": 1024,
      "cfgScale": 4,
      "steps": 20,
      "loras": {
        "urn:air:zImage:lora:civitai:123456@789012": 0.8
      }
    }
  }]
}

Set your Civitai API token via the Token button in the navbar to enable Try It.

Request body — edit to customize (e.g. swap the image URL or prompt)

Valid JSON

Common parameters

Both turbo and base share the same schema — only defaults differ. See the ZImageTurboCreateImageGenInput and ZImageBaseCreateImageGenInput schemas for the complete field list.

Field	Required	Turbo default	Base default	Range	Notes
`prompt`	✅	—	—	≤ 10 000 chars	Natural-language descriptions with lighting / composition / camera cues.
`negativePrompt`		(none)	(none)	≤ 10 000 chars	Most useful on `base`; effectively ignored on `turbo` because `cfgScale: 1`.
`width` / `height`		`1024`	`1024`	`64`–`2048`	Divisible by 16.
`cfgScale`		`1`	`4`	`0`–`30`	Turbo: keep at `1`. Base: `3`–`5` is the sweet spot.
`steps`		`9`	`20`	`1`–`150`	Turbo: `8`–`12`. Base: `20`–`30`.
`sampleMethod`		`euler`	`euler`	enum	`SdCppSampleMethod`.
`schedule`		`simple`	`simple`	enum	`SdCppSchedule`.
`loras`		`{}`	`{}`	`{ airUrn: strength }`	Stack multiple; strengths in `0.0`–`2.0` are typical.
`quantity`		`1`	`1`	`1`–`12`	Number of images per call.
`seed`		random	random	int64	Pin for reproducibility.

Reading the result

Standard imageGen output: an images[] array, one entry per quantity (shape and URL expiry).

Runtime

Variant	Typical wall time per 1024×1024 image	`wait` recommendation
`turbo` (`cfgScale: 1`, `steps: 9`) — default	3–8 s	`wait=30` fine for `quantity ≤ 4`
`base` (`cfgScale: 4`, `steps: 20`)	8–20 s	`wait=60` fine for `quantity ≤ 2`

Turbo's cost advantage shows up most clearly in batch mode — quantity: 4 on turbo often finishes in the same wall-clock window as quantity: 1 on base. For larger batches or dimensions, submit with wait=0 and poll.

Cost

Preview the exact charge with whatif=true (Payments (Buzz)).

Same per-pixel / per-step shape for both variants — different base cost and reference step count:

total = base × (width × height / 1024²) × (steps / referenceSteps) × quantity

Variant	`base`	`referenceSteps`	Defaults (1024², default steps, `quantity: 1`)
`turbo`	`8`	`9`	~8 Buzz
`base`	`20`	`20`	~20 Buzz

Examples:

Turbo at quantity: 4 → ~32 Buzz
Turbo at 1536×1024, steps: 12 → ~8 × 1.5 × 1.33 ≈ ~16 Buzz
Base at 1024², steps: 30 → ~20 × 1 × 1.5 ≈ ~30 Buzz

Troubleshooting

Timeouts, moderation blocks and expired blob URLs: see Common troubleshooting.

Symptom	Likely cause	Fix
`400` with unknown property	Field not valid for the ecosystem (e.g. `guidanceScale` — that's a Flux knob, not sdcpp)	Z-Image uses the sdcpp knob names: `cfgScale`, `steps`, `sampleMethod`, `schedule`.
`400` with "operation must be createImage"	Passed `editImage` or `createVariant`	Z-Image only supports `createImage` on either model. Use Flux 2 Klein or Flux 1 sdcpp if you need img2img / edit.
`400` with "ecosystem must be zImage"	Typo on the ecosystem slug	`"zImage"` — camelCase with capital I. Not `"z-image"`, `"zimage"`, `"Z-Image"`.
Turbo output looks washed out / low-detail	Step count too low for the prompt complexity	Bump `steps` to `10`–`12`; or switch to `base` if you need more.
Turbo ignores the negative prompt	`cfgScale: 1` effectively disables negative-prompt conditioning	Use `base` (with `cfgScale: 4`) if your workload depends on negative prompts.
Base output ignores the prompt	`cfgScale` too low or prompt too short	Raise `cfgScale` toward `5`; add lighting / composition cues.
LoRA silently has no effect	Wrong AIR URN, unpublished / private model, wrong ecosystem	Verify the URN on the LoRA's Civitai page; Z-Image LoRAs must be tagged for the `zImage` ecosystem.
Request timed out (`wait` expired)	Large `quantity`, large dimensions, or cold worker	Resubmit with `wait=0` and poll. Turbo is less likely to time out than base for the same dimensions.

SubmitWorkflow · GetWorkflow
Flux 2 image generation — higher-fidelity alternative with createVariant / editImage support
Flux 1 image generation — other sdcpp-hosted Flux ecosystem
Image upscaling — chain after imageGen for higher-res output
Prompt enhancement — LLM-rewrite a prompt before feeding it in via $ref
Full parameter catalog: the ZImageBaseCreateImageGenInput and ZImageTurboCreateImageGenInput schemas in the API reference
imageGen OpenAPI spec

Z-Image generation ​

Prerequisites ​

The request shape ​

turbo (default) ​

Batching with turbo ​

base (fallback when turbo isn't enough) ​

With a negative prompt ​

With LoRAs ​

Common parameters ​

Reading the result ​

Runtime ​

Cost ​

Troubleshooting ​

Related ​

Z-Image generation

Prerequisites

The request shape

turbo (default)

Batching with turbo

base (fallback when turbo isn't enough)

With a negative prompt

With LoRAs

Common parameters

Reading the result

Runtime

Cost

Troubleshooting

Related