Skip to main content
NewSeedance 2.5 is live→
ModelRunner
tongyi-mai avatar

Z-Image Base API

tongyi-mai/z-image/base

Generate high-quality, stylistically diverse images with precise prompt adherence using the Z-Image foundation model.

0.01 per megapixel of image
OpenAPI

Model Input

Input

The prompt to generate an image from.

The size of the generated image. Use a preset string (e.g. '4_3_1k') or a custom {width, height} object.

Min: 1 - Max: 50

The number of inference steps to perform.

The same seed and the same prompt given to the same version of the model will output the same image every time.

Safety checker can only be disabled on API call

The format of the generated image.

The acceleration level to use.

Min: 1 - Max: 20

The guidance scale to use for the image generation.

The negative prompt to use for the image generation.

Min: 1 - Max: 4

The number of images to generate. Each generated image is billed.

You need to be logged in to run this model and view results.
Log in

Model Output

Output

Generated image output
Generated in 11.76 seconds
Logs (1 lines)

Model Example Requests

Examples

Example output 1Example output 2

Z-Image Base API

Z-Image Base is a text-to-image AI model by tongyi-mai. On ModelRunner it runs through a REST API or via MCP from any AI assistant, at $0.01 per megapixel.

POST https://queue.modelrunner.run/tongyi-mai/z-image/base

cURL

# Submit a request to the queue. Input fields go at the top level of the
# body. The optional reserved "metadata" object holds your own flat string
# tags — stored on the request, never sent to the model; filter later with
# GET https://queue.modelrunner.run/requests?metadata=<url-encoded JSON>.
curl -X POST https://queue.modelrunner.run/tongyi-mai/z-image/base \
  -H "Authorization: Key $MRUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "seed": 98231,
    "prompt": "A serene Japanese garden in autumn, with red maple leaves floating on a crystal clear koi pond, a traditional wooden …",
    "image_size": {
      "width": 1024,
      "height": 576
    },
    "num_images": 1,
    "acceleration": "regular",
    "output_format": "png",
    "guidance_scale": 7.5,
    "negative_prompt": "blurry, low quality, distorted, watermark, text, bad anatomy",
    "num_inference_steps": 30,
    "enable_safety_checker": true,
    "metadata": {
      "project": "my-project"
    }
  }'
# → { "request_id": "...", "status_url": "...", "response_url": "..." }

# Poll status_url until "COMPLETED", then fetch the result
curl "https://queue.modelrunner.run/tongyi-mai/z-image/base/requests/$REQUEST_ID/status" \
  -H "Authorization: Key $MRUN_API_KEY"
curl "https://queue.modelrunner.run/tongyi-mai/z-image/base/requests/$REQUEST_ID" \
  -H "Authorization: Key $MRUN_API_KEY"

JavaScript

import { modelrunner } from "@modelrunner/client";

const result = await modelrunner.subscribe("tongyi-mai/z-image/base", {
  input: {
    "seed": 98231,
    "prompt": "A serene Japanese garden in autumn, with red maple leaves floating on a crystal clear koi pond, a traditional wooden …",
    "image_size": {
      "width": 1024,
      "height": 576
    },
    "num_images": 1,
    "acceleration": "regular",
    "output_format": "png",
    "guidance_scale": 7.5,
    "negative_prompt": "blurry, low quality, distorted, watermark, text, bad anatomy",
    "num_inference_steps": 30,
    "enable_safety_checker": true
  },
});
console.log(result);

Python

import os
import requests

headers = {"Authorization": f"Key {os.environ['MRUN_API_KEY']}"}

submitted = requests.post(
    "https://queue.modelrunner.run/tongyi-mai/z-image/base",
    headers=headers,
    json={
      "seed": 98231,
      "prompt": "A serene Japanese garden in autumn, with red maple leaves floating on a crystal clear koi pond, a traditional wooden …",
      "image_size": {
        "width": 1024,
        "height": 576
      },
      "num_images": 1,
      "acceleration": "regular",
      "output_format": "png",
      "guidance_scale": 7.5,
      "negative_prompt": "blurry, low quality, distorted, watermark, text, bad anatomy",
      "num_inference_steps": 30,
      "enable_safety_checker": true
    },
).json()

# Poll submitted["status_url"] until "COMPLETED", then:
result = requests.get(submitted["response_url"], headers=headers).json()

Input parameters

NameTypeRequiredDescription
promptstringyesThe prompt to generate an image from.
image_sizeenumnoThe size of the generated image. Use a preset string (e.g. '4_3_1k') or a custom {width, height} object. Default: "4_3_1k".
num_inference_stepsintegernoThe number of inference steps to perform. Default: 28.
seedintegernoThe same seed and the same prompt given to the same version of the model will output the same image every time.
enable_safety_checkerbooleannoIf set to true, the safety checker will be enabled. Default: true.
output_formatenumnoThe format of the generated image. Default: "png".
accelerationenumnoThe acceleration level to use. Default: "regular".
guidance_scalenumbernoThe guidance scale to use for the image generation. Default: 4.
negative_promptstringnoThe negative prompt to use for the image generation. Default: "".
num_imagesintegernoThe number of images to generate. Each generated image is billed. Default: 1.

Machine-readable: OpenAPI schema · llms.txt

Use Z-Image Base from Claude & Cursor (MCP)

Point Claude Code, Claude Desktop, Cursor, or any MCP client at the ModelRunner MCP server and Z-Image Base becomes a tool your assistant can call directly — it authorizes via OAuth (no API key in config) and runs this model with the run_model tool using the endpoint tongyi-mai/z-image/base.

MCP client config (Claude Desktop, Cursor)

{
  "mcpServers": {
    "modelrunner": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.modelrunner.run/mcp"]
    }
  }
}

Claude Code

claude mcp add --transport http modelrunner https://mcp.modelrunner.run/mcp

Then ask your assistant, for example: “Run tongyi-mai/z-image/base on ModelRunner to generate image”. MCP setup guide.

Model Details

Model Details

Z-Image Base is a foundational text-to-image generation model designed to deliver high-quality visuals with robust diversity and broad stylistic coverage. As the core of the Z-Image family, this model is engineered to interpret prompts with high precision, making it an ideal tool for creators looking to translate detailed textual descriptions into coherent and aesthetically pleasing images. Whether you are generating concept art, marketing assets, or illustrative content, Z-Image Base aims to respect the nuances of your input while maintaining structural consistency.

Key capabilities of this model include handling complex scene descriptions and offering a wide range of artistic styles. Users can interact with the model directly through the application UI to generate images and download the results immediately. The model supports various configuration options to fine-tune the output, allowing for control over aspect ratios, inference steps, and guidance scales.

**Input Configurations** To get the best results, users can adjust several parameters: * **Prompt**: The primary text description (e.g., "Grandmother knitting by a window"). * **Image Size**: Select from standard aspect ratios like `landscape_4_3`, `square`, or `portrait_16_9` to fit your composition needs. * **Inference Steps**: Control the quality-speed trade-off. The default is 28 steps, but it ranges from 1 to 50. * **Guidance Scale**: Determines how strictly the model follows the prompt. The default is 4. * **Negative Prompt**: Specify elements to exclude from the image.

**Example Usage** To run this model using the ModelRunner JavaScript client, utilize the following code snippet. This example demonstrates a standard generation request with specific sizing and quality settings.

```javascript import { modelrunner } from "@modelrunner/client";

const result = await modelrunner.subscribe("tongyi-mai/z-image/base", { input: { prompt: "Grandmother knitting by a window, an empty chair by her", image_size: "landscape_4_3", num_inference_steps: 28, num_images: 1, enable_safety_checker: true, output_format: "png", acceleration: "regular", guidance_scale: 4, negative_prompt: "blurry, low quality, distorted" } });

console.log(result); ```