> For the complete documentation index, see [llms.txt](https://bountyv.gitbook.io/vdocs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bountyv.gitbook.io/vdocs/image-api/images-txt2img.md). # Text-to-Image Generate an image from a text prompt. Pick the architecture with `engine` — five self-hosted (Z-Image, SDXL, SD1.5, Qwen-Image, FLUX.2) plus three SFW-only external engines (Seedream, Nano Banana Pro, ChatGPT Image), each with its own foundation models and LoRA presets. ``` POST /api/v1/images/txt2img ``` Synchronous — the generated image is returned directly in the response body. ## Authentication ``` Authorization: Bearer sk_live_... ``` See [Authentication](/vdocs/authentication.md). ## Request **Content-Type:** `application/json` | Field | Type | Required | Default | Description | | ----------------- | ------- | -------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `prompt` | string | ✅ | — | What to generate | | `mode` | string | — | `"nsfw"` | `"sfw"` runs the engine through the SFW guard — explicit prompts are rejected and the model is biased away from adult output. `"nsfw"` allows adult content | | `engine` | string | — | `"zimage"` | One of `zimage`, `sdxl`, `sd15`, `qwen`, `flux2`, `seedream`, `nanobanana`, `gptimage`. The external engines — `seedream` (BytePlus ModelArk Seedream 4.x), `nanobanana` (Google Gemini 3 Pro Image / Nano Banana Pro), `gptimage` (OpenAI gpt-image-2 / ChatGPT Image) — are SFW mode only | | `foundation` | string | — | — | Engine-specific foundation key (ignored by `qwen` and the external engines) | | `preset` | string | — | — | Engine LoRA preset key (ignored by the external engines) | | `size` | string | — | `"2K"` | `seedream` / `nanobanana` only — `"1K"` \| `"2K"` \| `"4K"`. Other engines use `width`/`height`. **`seedream` accepts `2K`/`4K` only** (the underlying Seedream 4.5 rejects `1K`); an unsupported value falls back to `2K` | | `aspect` | string | — | — | Aspect-ratio lock: `9:16`, `2:3`, `3:4`, `4:5`, `1:1`, `5:4`, `4:3`, `3:2`, `16:9`. Resolves to the engine's native width/height so you don't compute pixels yourself. An explicit `width`/`height` overrides it. `gptimage` supports `2:3`, `1:1`, `3:2` only; `seedream` ignores it (size buckets only); all other engines support the full set | | `loras` | array | — | — | `[{ name, strength }]` LoRA stack | | `negative_prompt` | string | — | — | Extra negatives folded in on top of the safety negatives | | `width` | integer | — | — | Output width in pixels. Overrides `aspect`. **Clamped** — see below | | `height` | integer | — | — | Output height in pixels. Overrides `aspect`. **Clamped** — see below | | `seed` | integer | — | — | Reproducibility | | `steps` | integer | — | — | Diffusion steps | | `cfg` | number | — | — | Guidance scale | | `hires` | boolean | — | `true` | Hi-res pass | | `draft` | boolean | — | `false` | Fast low-quality preview | | `face_detail` | boolean | — | — | `flux2` only — FaceDetailer pass | | `add_instapic` | boolean | — | — | `flux2` only — social-media realism layer | ### Size limits `aspect` always resolves to dimensions the chosen engine renders well. An explicit `width`/`height` bypasses that, so it is **clamped down to the engine's area budget**, preserving your aspect ratio. This is a quality guard, not a quota: asking SD 1.5 for 896×1200 — roughly 2.7× its native area — produces duplicated subjects rather than a bigger picture. If your dimensions are reduced, the response still reports what was actually rendered. Omit `width`/`height` and use `aspect` unless you have a specific reason. ### Pricing The price depends on the engine — the external frontier engines cost us more per render, so they bill higher than the self-hosted lanes: | Engine | Price | | ----------------------------------------- | ----- | | `zimage`, `sdxl`, `sd15`, `qwen`, `flux2` | $0.32 | | `seedream` | $0.29 | | `gptimage` | $0.39 | | `nanobanana` | $0.49 | The exact amount deducted is always returned as `charged_cents`. If your balance can't cover the selected engine the call returns `402` with `required_cents` and the `engine` that was priced, before any generation runs. ### Safety Every prompt runs through an age-safety blocklist and is augmented with adult-positive / minor-negative tokens; outputs are additionally screened on the worker. Prompts implying minors are rejected with `400`. ## Response ```json { "image": "https://.../generations/.png?token=...", "generation_id": "gJ8nP3kQ2m", "engine": "zimage", "charged_cents": 25, "balance_cents": 4775, "elapsed_ms": 8123 } ``` | Field | Type | Description | | --------------- | --------------- | ------------------------------------------------------------------------------------------------------------------- | | `image` | string | Generated image. A time-limited signed URL when the generation persists to storage, otherwise an inline `data:` URL | | `generation_id` | string \| null | Generation record ID, or `null` if persistence failed. List past results via the generations history endpoint | | `engine` | string | The engine that ran | | `charged_cents` | integer | Amount deducted from your balance for this call | | `balance_cents` | integer | Remaining balance | | `elapsed_ms` | integer \| null | Generation time in milliseconds | ## Example ```bash curl -X POST https://substance-api.com/api/v1/images/txt2img \ -H "Authorization: Bearer sk_live_..." \ -H "Content-Type: application/json" \ -d '{"prompt": "...", "engine": "flux2", "foundation": "snofs", "aspect": "3:4"}' ``` ## Errors | Status | When | | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `400` | Missing `prompt`; an SFW-only external engine (`seedream`, `nanobanana`, `gptimage`) called with `mode: "nsfw"`; or the prompt is rejected by the safety filter | | `401` | Missing/invalid API key | | `402` | Insufficient credits | | `403` | Required entitlement not enabled — `image` for `mode: "sfw"`, `nsfw` for `mode: "nsfw"` | | `503` | The base pipeline, or the selected external engine specifically, is temporarily disabled | | `502` | Generation failed upstream. Balance is refunded automatically | See [Errors](/vdocs/errors.md) for the general error format. ## Pricing Billed per call — see [Credits & pricing](/vdocs/account/credits.md) for current rates. Rate varies by `engine`. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://bountyv.gitbook.io/vdocs/image-api/images-txt2img.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.