
Zimage Generation
- 827 installs
- 12 repo stars
- Updated January 25, 2026
- toolsai/free-zimage-skills
zimage-generation is an agent skill that generates images through ModelScope's Z-Image Inference API for developers who want on-demand Z-Image renders from zimage: prompts inside coding agent sessions.
About
zimage-generation is a toolsai free-zimage-skills integration that calls ModelScope's Z-Image model via the ModelScope Inference API when developers type zimage: prompts or mention Zimage and ModelScope keywords. The skill activates on commands like zimage: <prompt> or natural requests to generate images with a configured ModelScope API key. Developers reach for zimage-generation when agents need a specific Z-Image backend instead of generic DALL-E or Stable Diffusion wrappers. The workflow is intentionally narrow: validate trigger phrases, forward prompts to ModelScope, and return generated raster assets for documentation, UI mocks, or content pipelines.
- Generates images via ModelScope's Z-Image Inference API
- Supports trigger phrases: Zimage, ModelScope, zimage:
- Three API key setup methods including .env file
- Provides ready-to-run Python script generate_zimage.py
- Command-line support for custom prompts and keys
Zimage Generation by the numbers
- 827 all-time installs (skills.sh)
- +7 installs in the week ending Aug 5, 2026 (Skillselion tracking)
- Ranked #312 of 1,335 Generative Media skills by installs in the Skillselion catalog
- Security screen: HIGH risk (skills.sh audit)
- Data as of Aug 5, 2026 (Skillselion catalog sync)
npx skills add https://github.com/toolsai/free-zimage-skills --skill zimage-generationAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 827 |
|---|---|
| repo stars | ★ 12 |
| Security audit | 1 / 3 scanners passed |
| Last updated | January 25, 2026 |
| Repository | toolsai/free-zimage-skills ↗ |
How do you generate images with ModelScope Z-Image?
Generate high-quality images on demand using the ModelScope Z-Image model directly from agent prompts.
Who is it for?
Developers with a ModelScope API key who want agents to generate images specifically through the Z-Image model on demand.
Skip if: Developers needing multi-model image routing, local Stable Diffusion GPU inference, or video generation pipelines.
When should I use this skill?
A developer types zimage:, mentions ModelScope image generation, or asks to generate images with the Z-Image model.
What you get
ModelScope Z-Image API response and generated raster image file from agent prompt.
- generated image file
- API response metadata
Files
Z-Image Generation Skill
This skill allows you to generate images using the Z-Image model via the ModelScope Inference API.
When to Use
Use this skill when:
- The user requests to generate an image using "Zimage", "zimage:", or "ModelScope".
- The user inputs a command like
zimage: <prompt>orzimage <prompt>. - The user wants to use their configured ModelScope API key for image generation.
Usage
The skill provides a Python script scripts/generate_zimage.py to handle the API interaction.
Prerequisites
- Python 3 with
requestsinstalled. - API Key Setup (Choose one):
- Method A (Easiest for beginners): Open
scripts/generate_zimage.pyand paste your key into theDEFAULT_API_KEYvariable at the top. - Method B (Temporary): Pass via command line:
--api-key your_token - Method C (Recommended Project Setup): Create a new text file named
.envin the same folder as the script (scripts/). - Content of the file should be:
MODELSCOPE_API_TOKEN="your_key_here"
Commands
To generate an image:
# If you used Method A (pasted key in file):
python3 /Users/promptcase/.gemini/antigravity/skills/zimage-generation/scripts/generate_zimage.py "Your descriptive prompt here"
# If you prefer command line (Method B):
python3 /Users/promptcase/.gemini/antigravity/skills/zimage-generation/scripts/generate_zimage.py "Your prompt" --api-key "your_key"Arguments:
prompt: The text description of the image (required).--output,-o: Specify output filename (optional).--model: Specify a different model ID (optional).--api-key: API key (if not set in file or environment).
API Verification Note
If the script returns a 401 error mentioning "bind your Alibaba Cloud account", notify the user that they must log in to ModelScope (https://modelscope.cn/my/account) and bind their Alibaba Cloud account to enable API access. This is a one-time setup required by the platform.
Example
# To generate a cyberpunk city
python3 /Users/mattchan/.gemini/antigravity/skills/zimage-generation/scripts/generate_zimage.py "cyberpunk city, neon lights, rainy street, high detail"Bud1 ptsIlocblscriptsIlocblobA.������scriptsbwspblob�bplist00�]ShowStatusBar[ShowToolbar[ShowTabView_ContainerShowSidebar\WindowBounds[ShowSidebar _{{2186, 0}, {1157, 921}} #/;R_klmno�
�scriptsvSrnlongSKILL.mdIlocblob�.������ @� @� @� @E DSDB `� @� @� @scripts/.env
*.png
__pycache__
.DS_Store
Z-Image 圖片生成工具 (Antigravity Skill)
這是一個基於 ModelScope Z-Image 模型的圖片生成工具。它可以讓你在終端機 (Terminal) 輸入簡單的指令,即刻生成高品質的 AI 圖片。
🌟 功能特點
- 高品質生成:使用阿里雲開發的 Z-Image 模型,支持中英文提示詞。
- 異步處理:完美解決大模型生成時間較長的問題,自動排隊並獲取結果。
- 多種配置方式:支持直接修改代碼、命令列參數或
.env配置文件,靈活且安全。
🛠️ 安裝與準備
1. 安裝環境
確保你的電腦已安裝 Python 3,然後安裝必要的套件:
pip install requests python-dotenv2. 獲取 API Key
1. 註冊並登入 ModelScope 魔搭社區。 2. 在「個人中心」獲取你的 API Key。 3. 重要:請確保你的 ModelScope 帳號已綁定「阿里雲帳號」,否則 API 會返回認證錯誤。
3. 設定 API Key (三選一)
- 方法 A (最直觀):打開
scripts/generate_zimage.py,在大約第 18 行的DEFAULT_API_KEY處填入你的 Key。 - 方法 B (推薦):在
scripts/資料夾下建立一個.env檔案,內容如下:
MODELSCOPE_API_TOKEN="你的Key"- 方法 C (臨時用):執行指令時加上
--api-key "你的Key"。
🚀 使用方法
在終端機輸入以下指令:
python3 scripts/generate_zimage.py "一隻正在宇宙中漫步的可愛金色貓咪,4k畫質,精緻細節"常用參數:
--output或-o: 指定輸出的路徑與檔名(預設為自動生成)。--size或-s: 指定圖片尺寸(預設 1024x1024)。--api-key或-k: 臨時指定 API Key。
📁 檔案結構
SKILL.md: 供 Antigravity AI Agent 讀取的技能說明文檔。scripts/generate_zimage.py: 核心 Python 腳本。scripts/.env.example: 環境變數配置文件範例。
📝 授權說明
本項目僅供學習與交流使用。模型版權歸 ModelScope/Alibaba 所有。
Bud1�Ilocblob.envIlocblob�.������generate_zimage.pyIlocblobA.������ @� @� @� @E�DSDB ` @� @� @MODELSCOPE_API_TOKEN="Your Key Here ms-xxx"
#!/usr/bin/env python3
import requests
import json
import os
import argparse
import sys
import time
from datetime import datetime
try:
from dotenv import load_dotenv
load_dotenv()
except ImportError:
pass # Handle case where python-dotenv is not installed
# Configuration
# Configuration
# ==============================================================================
# [新手設定區] 請在這裡貼上你的 API Key
# 1. 刪除 None
# 2. 貼上你的 Key,並保留引號
# 例: DEFAULT_API_KEY = "ms-xxxyyyzzzz..."
# ==============================================================================
DEFAULT_API_KEY = None
DEFAULT_MODEL = "Tongyi-MAI/Z-Image-Turbo"
BASE_URL = "https://api-inference.modelscope.cn/"
def generate_image(prompt, output_path=None, api_key=None, model=None, size="1024x1024"):
token = api_key or os.environ.get("MODELSCOPE_API_TOKEN") or DEFAULT_API_KEY
if not token:
print("Error: No API Key provided.")
print("Please set the MODELSCOPE_API_TOKEN environment variable or pass --api-key.")
return False
model_id = model or DEFAULT_MODEL
if not output_path:
timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
safe_prompt = prompt[:20].replace(" ", "_").replace("/", "")
output_path = f"zimage_{timestamp}_{safe_prompt}.png"
print(f"Generating image with Z-Image ({model_id})...")
print(f"Prompt: {prompt}")
headers = {
"Authorization": f"Bearer {token}",
"Content-Type": "application/json",
"X-ModelScope-Async-Mode": "true" # Required for Z-Image
}
data = {
"model": model_id,
"prompt": prompt,
"n": 1,
"size": size
}
try:
# 1. Submit Async Task
submit_url = f"{BASE_URL}v1/images/generations"
response = requests.post(submit_url, headers=headers, json=data, timeout=60)
if response.status_code != 200:
print(f"Error submitting task: {response.status_code}")
print(response.text)
return False
task_data = response.json()
task_id = task_data.get("task_id")
if not task_id:
print("Error: No task_id received.")
return False
print(f"Task submitted successfully (ID: {task_id}). Polling for result...")
# 2. Poll for Status
# Important header for polling image tasks
poll_headers = {
"Authorization": f"Bearer {token}",
"Content-Type": "application/json",
"X-ModelScope-Task-Type": "image_generation"
}
start_time = time.time()
timeout_seconds = 300 # 5 minutes timeout
while True:
if time.time() - start_time > timeout_seconds:
print("Timeout waiting for image generation.")
return False
poll_resp = requests.get(
f"{BASE_URL}v1/tasks/{task_id}",
headers=poll_headers,
timeout=30
)
if poll_resp.status_code != 200:
print(f"Polling error: {poll_resp.status_code}")
# Don't break immediately on transient network errors, maybe retry?
# For now we print and sleep
else:
data = poll_resp.json()
status = data.get("task_status")
if status == "SUCCEED":
if "output_images" in data and len(data["output_images"]) > 0:
image_url = data["output_images"][0]
print(f"Generation successful! Downloading from {image_url}...")
# Download Image
img_response = requests.get(image_url)
if img_response.status_code == 200:
with open(output_path, "wb") as f:
f.write(img_response.content)
print(f"Image saved to: {os.path.abspath(output_path)}")
return True
else:
print("Error: Failed to download the generated image file.")
return False
else:
print("Task succeeded but no output image found.")
return False
elif status == "FAILED":
print("Generation Failed.")
print(f"Details: {data}")
return False
elif status in ["PENDING", "RUNNING", "QUEUED", "PROCESSING"]:
print(f"Status: {status}...", end="\r")
else:
print(f"Unknown status: {status}")
time.sleep(2)
except Exception as e:
print(f"Exception during generation: {e}")
return False
if __name__ == "__main__":
parser = argparse.ArgumentParser(description="Generate images using ModelScope Z-Image API")
parser.add_argument("prompt", help="Text prompt for image generation")
parser.add_argument("--output", "-o", help="Output filename")
parser.add_argument("--model", "-m", help=f"Model ID (default: {DEFAULT_MODEL})")
parser.add_argument("--size", "-s", default="1024x1024", help="Image size (default: 1024x1024)")
parser.add_argument("--api-key", "-k", help="ModelScope API Key")
args = parser.parse_args()
success = generate_image(args.prompt, args.output, model=args.model, size=args.size, api_key=args.api_key)
if not success:
sys.exit(1)
Related skills
How it compares
Use zimage-generation when the requirement explicitly names ModelScope Z-Image rather than general-purpose image generation skills.
FAQ
How do you trigger zimage-generation?
zimage-generation activates when developers use zimage: <prompt> commands or mention Zimage and ModelScope keywords, routing prompts to the ModelScope Z-Image Inference API with a configured API key.
Which API does zimage-generation use?
zimage-generation calls ModelScope's Z-Image model through the ModelScope Inference API, returning generated images for agent workflows that specify Z-Image rather than generic image backends.
Is Zimage Generation safe to install?
skills.sh reports 1 of 3 security scanners passed. Review the Security Audits panel on this page before installing in production.