Skill: futurizerush/imgforge (version 1.1.0)

--- name: zimage description: Generate AI images for free using Z-Image-Turbo. Say "generate an image of..." and get stunning results in seconds. version: 1.1.0 allowed-tools: Bash, Write, Read metadata: openclaw: requires: env: [MODELSCOPE_API_KEY] bins: [python3] primaryEnv: MODELSCOPE_API_KEY emoji: "🎨" homepage: https://github.com/FuturizeRush/zimage-skill os: [macos, linux, windows] --- # Z-Image — Free AI Image Generation Generate images from text using Alibaba's open-source Z-Image-Turbo model. Free to use. ## When to Trigger Activate this skill when the user asks to: - generate, create, draw, or make an image / picture / illustration / photo - create thumbnails, avatars, banners, or social-media graphics - visualize a concept, scene, or character ## Generating an Image ```bash python3 SKILL_DIR/imgforge.py "PROMPT" -o OUTPUT_PATH ``` ### Arguments | Flag | Default | Description | |------|---------|-------------| | `PROMPT` (positional) | — | Text description (English or Chinese) | | `-o`, `--out` | `output.jpg` | File path to save the image | | `-W`, `--width` | 1024 | Width in pixels (512–2048) | | `-H`, `--height` | 1024 | Height in pixels (512–2048) | | `--json` | off | Output result as JSON | ### Common sizes | Aspect | Flags | |--------|-------| | Square (1:1) | `-W 1024 -H 1024` | | Landscape (16:9) | `-W 1280 -H 720` | | Portrait (9:16) | `-W 720 -H 1280` | | Wide banner | `-W 2048 -H 1024` | ### Prompt tips Add quality keywords for better output: "4K", "cinematic", "professional photography", "dramatic lighting", "shallow depth of field". Specify a style: "oil painting", "watercolor", "anime", "pixel art", "minimalist vector". ## Environment Requires `MODELSCOPE_API_KEY`. If the user hasn't set it, guide them: 1. Create a free Alibaba Cloud account (phone verification + payment method required, but Z-Image is free) → https://www.alibabacloud.com/campaign/benefits?referral_code=A9242N 2. Sign up at https://modelscope.ai/register?inviteCode=futurizerush&invitorName=futurizerush&login=true&logintype=register and bind the Alibaba Cloud account in settings 3. Create a token at https://modelscope.ai/my/access/token 4. Set the environment variable: `export MODELSCOPE_API_KEY="ms-..."` For Claude Code users, add to `~/.claude/settings.json` under `"env"`. ## Errors | Symptom | Cause & fix | |---------|-------------| | 401 Unauthorized | Token is from modelscope.cn (wrong site) — must use **modelscope.ai**. Or Alibaba Cloud account not bound. | | Timeout after 150s | API under load — retry in a minute | | Content moderation | Rephrase the prompt — Alibaba's filter blocked it | ## Notes - No external dependencies required (uses Python stdlib). Pillow is optional for format conversion. - The script creates parent directories automatically. - Image URLs from the API expire in 24h — the script downloads immediately.

path: README.md
content: # zimage — Free AI Image Generation Skill

<p align="center">
  <img src="./icon.png" alt="Z-Image Skill" width="128" height="128">
</p>

<p align="center">
  <strong>Turn text into images for free, right from your AI coding assistant.</strong><br>
  Works with Claude Code · OpenClaw · Codex · Antigravity · Paperclip
</p>

<p align="center">
  <a href="./README.md">English</a> ·
  <a href="./docs/README_TW.md">繁體中文</a> ·
  <a href="./docs/README_JA.md">日本語</a> ·
  <a href="./docs/README_KO.md">한국어</a> ·
  <a href="./docs/README_ES.md">Español</a> ·
  <a href="./docs/README_DE.md">Deutsch</a> ·
  <a href="./docs/README_FR.md">Français</a> ·
  <a href="./docs/README_IT.md">Italiano</a>
</p>

---

## Overview

**zimage** gives your AI assistant the ability to generate images from natural language. It calls [Z-Image-Turbo](https://github.com/Tongyi-MAI/Z-Image) — an open-source 6B-parameter model by Alibaba's Tongyi-MAI team — through ModelScope's free API.

```
You:  Create an image of a fox reading a book in a library
AI:   Submitting: a fox reading a book in a library
      Task 91204 — waiting for result…
      Saved → fox_library.jpg
```

### How it compares

|  | zimage | DALL-E 3 | Midjourney |
|--|--------|----------|------------|
| Price | **Free** | $0.04–0.08 / image | From $10/mo |
| Open source | Apache 2.0 | No | No |
| Setup time | ~5 min | Billing required | Discord required |

> **Free tier:** 2,000 API calls/day total, 500/day per model. Limits may be dynamically adjusted. ([official limits](https://modelscope.ai/docs/model-service/API-Inference/limits))

---

## Setup

### 1 — Alibaba Cloud account (free)

Register at **https://www.alibabacloud.com/campaign/benefits?referral_code=A9242N**

You'll need to verify your phone number and add a payment method during registration. **Z-Image itself is free and will not charge you**, but Alibaba Cloud requires payment info on file for all accounts.

### 2 — ModelScope account + binding

1. Go to **https://modelscope.ai/register?inviteCode=futurizerush&invitorName=futurizerush&login=true&logintype=register** → sign up (GitHub login works)
2. Open **Settings → Bind Alibaba Cloud Account** and link the account from step 1

### 3 — API token

1. Visit **https://modelscope.ai/my/access/token**
2. Click **Create Your Token**
3. Copy it — looks like `ms-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`

---

## Install

<details>
<summary><b>Claude Code</b></summary>

Say this in Claude Code:

```
Install the zimage skill from https://github.com/FuturizeRush/zimage-skill
```

Then:

```
Set my MODELSCOPE_API_KEY environment variable to ms-your-token
```

Restart Claude Code.
</details>

<details>
<summary><b>OpenClaw / ClawHub</b></summary>

```bash
openclaw skills install zimage
# or
npx clawhub@latest install zimage
```

```bash
export MODELSCOPE_API_KEY="ms-your-token"
```
</details>

<details>
<summary><b>Codex / Antigravity / Paperclip / Other</b></summary>

```bash
git clone https://github.com/FuturizeRush/zimage-skill.git
cd zimage-skill
pip install Pillow  # optional, for format conversion
export MODELSCOPE_API_KEY="ms-your-token"
```

```bash
python3 imgforge.py "a sunset over the ocean" sunset.jpg
```
</details>

---

## Usage

### Through your AI assistant

Just ask naturally:

```
Generate an image of a cozy coffee shop, warm lighting, cinematic
Draw a pixel-art dragon breathing fire
Create a minimalist logo, blue gradients, clean vector style
```

### Direct CLI

```bash
# Basic
python3 imgforge.py "a cat astronaut on Mars"

# Custom size (landscape)
python3 imgforge.py "mountain panorama at golden hour" -o panorama.jpg -W 2048 -H 1024

# Machine-readable output
python3 imgforge.py "abstract art" --json
# → {"ok": true, "path": "output.jpg", "task": "91204"}
```

### CLI flags

| Flag | Default | Description |
|------|---------|-------------|
| `prompt` | *(required)* | What to generate |
| `-o` / `--out` | `output.jpg` | Output path (.jpg, .png, .webp) |
| `-W` / `--width` | `1024` | Width, 512–2048 px |
| `-H` / `--height` | `1024` | Height, 512–2048 px |
| `--json` | off | JSON output for scripting |

### Prompt tips

**Quality boosters:** `4K`, `cinematic`, `professional photography`, `dramatic lighting`, `shallow depth of field`

**Style keywords:** `oil painting`, `watercolor`, `anime`, `pixel art`, `ink wash`, `blueprint`, `isometric`

---

## Troubleshooting

| Problem | Solution |
|---------|----------|
| `MODELSCOPE_API_KEY is not set` | See [Setup](#setup) above |
| `401 Unauthorized` | Use **modelscope.ai** (not .cn). Bind Alibaba Cloud in settings. Regenerate token. |
| Timeout | API under load — retry in a minute |
| Content moderation | Rephrase your prompt |

---

## Technical notes

- **Zero required dependencies** — uses Python's `urllib.request`. Pillow is optional (auto-detected for format conversion).
- Supports custom image dimensions from 512×512 to 2048×2048.
- `--json` flag enables integration with other tools and scripts.
- Image URLs from the API expire in 24h — the script downloads immediately.
- Model: [Tongyi-MAI/Z-Image-Turbo](https://huggingface.co/Tongyi-MAI/Z-Image-Turbo) (Apache 2.0)
- API: ModelScope International (`api-inference.modelscope.ai`)

---

## License

MIT-0 — do whatever you want with it.


path: docs/README_DE.md
content: # zimage — Kostenlose KI-Bildgenerierung

<p align="center">
  <img src="../icon.png" alt="Z-Image Skill" width="128" height="128">
</p>

<p align="center">
  <strong>Generiere kostenlos Bilder aus Text mit deinem KI-Programmierassistenten.</strong><br>
  Kompatibel mit Claude Code · OpenClaw · Codex · Antigravity · Paperclip
</p>

<p align="center">
  <a href="../README.md">English</a> ·
  <a href="./README_TW.md">繁體中文</a> ·
  <a href="./README_JA.md">日本語</a> ·
  <a href="./README_KO.md">한국어</a> ·
  <a href="./README_ES.md">Español</a> ·
  <a href="./README_DE.md">Deutsch</a> ·
  <a href="./README_FR.md">Français</a> ·
  <a href="./README_IT.md">Italiano</a>
</p>

---

## Überblick

**zimage** gibt deinem KI-Assistenten die Fähigkeit, Bilder aus Textbeschreibungen zu generieren. Es nutzt [Z-Image-Turbo](https://github.com/Tongyi-MAI/Z-Image) — ein Open-Source-Modell mit 6 Milliarden Parametern vom Tongyi-MAI-Team bei Alibaba — über die kostenlose ModelScope-API.

|  | zimage | DALL-E 3 | Midjourney |
|--|--------|----------|------------|
| Preis | **Kostenlos** | $0,04–0,08 / Bild | Ab $10/Monat |
| Open Source | Apache 2.0 | Nein | Nein |

> Kostenloses Kontingent: 2.000 API-Aufrufe/Tag gesamt, 500/Tag pro Modell ([offizielle Limits](https://modelscope.ai/docs/model-service/API-Inference/limits)). Limits können dynamisch angepasst werden.

---

## Einrichtung

### 1 — Alibaba Cloud Konto (kostenlos)

Registriere dich hier: **https://www.alibabacloud.com/campaign/benefits?referral_code=A9242N**

Bei der Registrierung sind eine Telefonnummer-Verifizierung und eine Zahlungsmethode erforderlich. **Z-Image selbst ist kostenlos und verursacht keine Kosten**, aber Alibaba Cloud verlangt Zahlungsinformationen im Konto.

### 2 — ModelScope Konto + Verknüpfung

1. Gehe zu **https://modelscope.ai/register?inviteCode=futurizerush&invitorName=futurizerush&login=true&logintype=register** → registriere dich (GitHub-Login möglich)
2. Unter **Einstellungen → Bind Alibaba Cloud Account** dein Konto verknüpfen

### 3 — API-Token

1. Besuche **https://modelscope.ai/my/access/token**
2. Klicke auf **Create Your Token**
3. Kopiere den Token (Format: `ms-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`)

---

## Installation

<details>
<summary><b>Claude Code</b></summary>

```
Install the zimage skill from https://github.com/FuturizeRush/zimage-skill
```

```
Set my MODELSCOPE_API_KEY environment variable to ms-dein-token
```

Claude Code neu starten.
</details>

<details>
<summary><b>OpenClaw / ClawHub</b></summary>

```bash
openclaw skills install zimage
```

```bash
export MODELSCOPE_API_KEY="ms-dein-token"
```
</details>

<details>
<summary><b>Codex / Antigravity / Paperclip / Andere</b></summary>

```bash
git clone https://github.com/FuturizeRush/zimage-skill.git
cd zimage-skill
export MODELSCOPE_API_KEY="ms-dein-token"
python3 imgforge.py "ein Sonnenuntergang über dem Meer" sunset.jpg
```
</details>

---

## Nutzung

```
Erstelle ein Bild von einem gemütlichen Café, warmes Licht, filmisch
Zeichne einen Pixel-Art-Drachen, der Feuer speit
Erstelle ein minimalistisches Logo, blaue Farbverläufe
```

### CLI

```bash
python3 imgforge.py "ein Astronaut auf dem Mars" -o astronaut.jpg -W 1280 -H 720
python3 imgforge.py "abstrakte Kunst" --json
```

---

## Fehlerbehebung

| Problem | Lösung |
|---------|--------|
| `MODELSCOPE_API_KEY is not set` | [Einrichtung](#einrichtung) abschließen |
| `401 Unauthorized` | **modelscope.ai** verwenden (nicht .cn). Alibaba Cloud verknüpfen. Token erneuern. |
| Timeout | API ausgelastet — in einer Minute erneut versuchen |

---

## Lizenz

MIT-0 — frei verwendbar, keine Namensnennung erforderlich.


path: docs/README_ES.md
content: # zimage — Generación gratuita de imágenes con IA

<p align="center">
  <img src="../icon.png" alt="Z-Image Skill" width="128" height="128">
</p>

<p align="center">
  <strong>Genera imágenes gratis con texto desde tu asistente de programación con IA.</strong><br>
  Compatible con Claude Code · OpenClaw · Codex · Antigravity · Paperclip
</p>

<p align="center">
  <a href="../README.md">English</a> ·
  <a href="./README_TW.md">繁體中文</a> ·
  <a href="./README_JA.md">日本語</a> ·
  <a href="./README_KO.md">한국어</a> ·
  <a href="./README_ES.md">Español</a> ·
  <a href="./README_DE.md">Deutsch</a> ·
  <a href="./README_FR.md">Français</a> ·
  <a href="./README_IT.md">Italiano</a>
</p>

---

## Descripción

**zimage** añade a tu asistente de IA la capacidad de generar imágenes a partir de texto. Utiliza [Z-Image-Turbo](https://github.com/Tongyi-MAI/Z-Image), un modelo de código abierto con 6.000 millones de parámetros del equipo Tongyi-MAI de Alibaba, a través de la API gratuita de ModelScope.

|  | zimage | DALL-E 3 | Midjourney |
|--|--------|----------|------------|
| Precio | **Gratis** | $0,04–0,08 / imagen | Desde $10/mes |
| Código abierto | Apache 2.0 | No | No |

> Cuota gratuita: 2.000 llamadas API/día en total, 500/día por modelo ([límites oficiales](https://modelscope.ai/docs/model-service/API-Inference/limits)). Los límites pueden ajustarse dinámicamente.

---

## Configuración

### 1 — Cuenta Alibaba Cloud (gratis)

Regístrate en: **https://www.alibabacloud.com/campaign/benefits?referral_code=A9242N**

Se requiere verificación telefónica y un método de pago al registrarse. **Z-Image es gratis y no se te cobrará**, pero Alibaba Cloud requiere información de pago en la cuenta.

### 2 — Cuenta ModelScope + vinculación

1. Ve a **https://modelscope.ai/register?inviteCode=futurizerush&invitorName=futurizerush&login=true&logintype=register** → regístrate (login con GitHub disponible)
2. En **Configuración → Bind Alibaba Cloud Account**, vincula tu cuenta

### 3 — Token API

1. Visita **https://modelscope.ai/my/access/token**
2. Haz clic en **Create Your Token**
3. Copia el token (formato: `ms-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`)

---

## Instalación

<details>
<summary><b>Claude Code</b></summary>

```
Install the zimage skill from https://github.com/FuturizeRush/zimage-skill
```

```
Set my MODELSCOPE_API_KEY environment variable to ms-tu-token
```

Reinicia Claude Code.
</details>

<details>
<summary><b>OpenClaw / ClawHub</b></summary>

```bash
openclaw skills install zimage
```

```bash
export MODELSCOPE_API_KEY="ms-tu-token"
```
</details>

<details>
<summary><b>Codex / Antigravity / Paperclip / Otros</b></summary>

```bash
git clone https://github.com/FuturizeRush/zimage-skill.git
cd zimage-skill
pip install Pillow  # opcional
export MODELSCOPE_API_KEY="ms-tu-token"
python3 imgforge.py "una puesta de sol sobre el océano" sunset.jpg
```
</details>

---

## Uso

```
Genera una imagen de una cafetería acogedora, iluminación cálida, cinematográfica
Dibuja un dragón pixel art lanzando fuego
Crea un logo minimalista, gradientes azules
```

### CLI

```bash
python3 imgforge.py "un astronauta en Marte" -o astronauta.jpg -W 1280 -H 720
python3 imgforge.py "arte abstracto" --json
```

---

## Solución de problemas

| Problema | Solución |
|----------|----------|
| `MODELSCOPE_API_KEY is not set` | Completa la [configuración](#configuración) |
| `401 Unauthorized` | Usa **modelscope.ai** (no .cn). Vincula Alibaba Cloud. Regenera el token. |
| Timeout | API con carga alta — reintenta en un minuto |

---

## Licencia

MIT-0 — úsalo como quieras.


path: docs/README_FR.md
content: # zimage — Génération d'images IA gratuite

<p align="center">
  <img src="../icon.png" alt="Z-Image Skill" width="128" height="128">
</p>

<p align="center">
  <strong>Générez des images gratuitement à partir de texte avec votre assistant IA.</strong><br>
  Compatible avec Claude Code · OpenClaw · Codex · Antigravity · Paperclip
</p>

<p align="center">
  <a href="../README.md">English</a> ·
  <a href="./README_TW.md">繁體中文</a> ·
  <a href="./README_JA.md">日本語</a> ·
  <a href="./README_KO.md">한국어</a> ·
  <a href="./README_ES.md">Español</a> ·
  <a href="./README_DE.md">Deutsch</a> ·
  <a href="./README_FR.md">Français</a> ·
  <a href="./README_IT.md">Italiano</a>
</p>

---

## Présentation

**zimage** donne à votre assistant IA la capacité de générer des images à partir de descriptions textuelles. Il utilise [Z-Image-Turbo](https://github.com/Tongyi-MAI/Z-Image) — un modèle open source de 6 milliards de paramètres de l'équipe Tongyi-MAI d'Alibaba — via l'API gratuite de ModelScope.

|  | zimage | DALL-E 3 | Midjourney |
|--|--------|----------|------------|
| Prix | **Gratuit** | 0,04–0,08 $ / image | À partir de 10 $/mois |
| Open source | Apache 2.0 | Non | Non |

> Quota gratuit : 2 000 appels API/jour au total, 500/jour par modèle ([limites officielles](https://modelscope.ai/docs/model-service/API-Inference/limits)). Les limites peuvent être ajustées dynamiquement.

---

## Configuration

### 1 — Compte Alibaba Cloud (gratuit)

Inscrivez-vous ici : **https://www.alibabacloud.com/campaign/benefits?referral_code=A9242N**

Une vérification téléphonique et un moyen de paiement sont requis à l'inscription. **Z-Image est gratuit et ne vous facturera rien**, mais Alibaba Cloud exige des informations de paiement sur le compte.

### 2 — Compte ModelScope + liaison

1. Allez sur **https://modelscope.ai/register?inviteCode=futurizerush&invitorName=futurizerush&login=true&logintype=register** → inscrivez-vous (connexion GitHub possible)
2. Dans **Paramètres → Bind Alibaba Cloud Account**, liez votre compte

### 3 — Jeton API

1. Visitez **https://modelscope.ai/my/access/token**
2. Cliquez sur **Create Your Token**
3. Copiez le jeton (format : `ms-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`)

---

## Installation

<details>
<summary><b>Claude Code</b></summary>

```
Install the zimage skill from https://github.com/FuturizeRush/zimage-skill
```

```
Set my MODELSCOPE_API_KEY environment variable to ms-votre-jeton
```

Redémarrez Claude Code.
</details>

<details>
<summary><b>OpenClaw / ClawHub</b></summary>

```bash
openclaw skills install zimage
```

```bash
export MODELSCOPE_API_KEY="ms-votre-jeton"
```
</details>

<details>
<summary><b>Codex / Antigravity / Paperclip / Autres</b></summary>

```bash
git clone https://github.com/FuturizeRush/zimage-skill.git
cd zimage-skill
export MODELSCOPE_API_KEY="ms-votre-jeton"
python3 imgforge.py "un coucher de soleil sur l'océan" sunset.jpg
```
</details>

---

## Utilisation

```
Génère une image d'un café chaleureux, éclairage tamisé, cinématographique
Dessine un dragon en pixel art crachant du feu
Crée un logo minimaliste, dégradés bleus
```

### CLI

```bash
python3 imgforge.py "un astronaute sur Mars" -o astronaute.jpg -W 1280 -H 720
python3 imgforge.py "art abstrait" --json
```

---

## Dépannage

| Problème | Solution |
|----------|----------|
| `MODELSCOPE_API_KEY is not set` | Complétez la [configuration](#configuration) |
| `401 Unauthorized` | Utilisez **modelscope.ai** (pas .cn). Liez Alibaba Cloud. Régénérez le jeton. |
| Timeout | API surchargée — réessayez dans une minute |

---

## Licence

MIT-0 — utilisez-le comme vous voulez, aucune attribution requise.


path: docs/README_IT.md
content: # zimage — Generazione gratuita di immagini con IA

<p align="center">
  <img src="../icon.png" alt="Z-Image Skill" width="128" height="128">
</p>

<p align="center">
  <strong>Genera immagini gratis da testo con il tuo assistente IA.</strong><br>
  Compatibile con Claude Code · OpenClaw · Codex · Antigravity · Paperclip
</p>

<p align="center">
  <a href="../README.md">English</a> ·
  <a href="./README_TW.md">繁體中文</a> ·
  <a href="./README_JA.md">日本語</a> ·
  <a href="./README_KO.md">한국어</a> ·
  <a href="./README_ES.md">Español</a> ·
  <a href="./README_DE.md">Deutsch</a> ·
  <a href="./README_FR.md">Français</a> ·
  <a href="./README_IT.md">Italiano</a>
</p>

---

## Panoramica

**zimage** aggiunge al tuo assistente IA la capacità di generare immagini da descrizioni testuali. Utilizza [Z-Image-Turbo](https://github.com/Tongyi-MAI/Z-Image) — un modello open source con 6 miliardi di parametri del team Tongyi-MAI di Alibaba — tramite l'API gratuita di ModelScope.

|  | zimage | DALL-E 3 | Midjourney |
|--|--------|----------|------------|
| Prezzo | **Gratis** | $0,04–0,08 / immagine | Da $10/mese |
| Open source | Apache 2.0 | No | No |

> Quota gratuita: 2.000 chiamate API/giorno in totale, 500/giorno per modello ([limiti ufficiali](https://modelscope.ai/docs/model-service/API-Inference/limits)). I limiti possono essere regolati dinamicamente.

---

## Configurazione

### 1 — Account Alibaba Cloud (gratis)

Registrati qui: **https://www.alibabacloud.com/campaign/benefits?referral_code=A9242N**

È necessaria la verifica telefonica e un metodo di pagamento durante la registrazione. **Z-Image è gratuito e non ti verrà addebitato nulla**, ma Alibaba Cloud richiede informazioni di pagamento sull'account.

### 2 — Account ModelScope + collegamento

1. Vai su **https://modelscope.ai/register?inviteCode=futurizerush&invitorName=futurizerush&login=true&logintype=register** → registrati (login con GitHub disponibile)
2. In **Impostazioni → Bind Alibaba Cloud Account**, collega il tuo account

### 3 — Token API

1. Visita **https://modelscope.ai/my/access/token**
2. Clicca su **Create Your Token**
3. Copia il token (formato: `ms-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`)

---

## Installazione

<details>
<summary><b>Claude Code</b></summary>

```
Install the zimage skill from https://github.com/FuturizeRush/zimage-skill
```

```
Set my MODELSCOPE_API_KEY environment variable to ms-il-tuo-token
```

Riavvia Claude Code.
</details>

<details>
<summary><b>OpenClaw / ClawHub</b></summary>

```bash
openclaw skills install zimage
```

```bash
export MODELSCOPE_API_KEY="ms-il-tuo-token"
```
</details>

<details>
<summary><b>Codex / Antigravity / Paperclip / Altri</b></summary>

```bash
git clone https://github.com/FuturizeRush/zimage-skill.git
cd zimage-skill
export MODELSCOPE_API_KEY="ms-il-tuo-token"
python3 imgforge.py "un tramonto sull'oceano" sunset.jpg
```
</details>

---

## Utilizzo

```
Genera un'immagine di un caffè accogliente, luce calda, cinematografico
Disegna un drago pixel art che sputa fuoco
Crea un logo minimalista, sfumature blu
```

### CLI

```bash
python3 imgforge.py "un astronauta su Marte" -o astronauta.jpg -W 1280 -H 720
python3 imgforge.py "arte astratta" --json
```

---

## Risoluzione dei problemi

| Problema | Soluzione |
|----------|----------|
| `MODELSCOPE_API_KEY is not set` | Completa la [configurazione](#configurazione) |
| `401 Unauthorized` | Usa **modelscope.ai** (non .cn). Collega Alibaba Cloud. Rigenera il token. |
| Timeout | API sovraccarica — riprova tra un minuto |

---

## Licenza

MIT-0 — usalo come vuoi, nessuna attribuzione richiesta.


path: docs/README_JA.md
content: # zimage — 無料AI画像生成スキル

<p align="center">
  <img src="../icon.png" alt="Z-Image Skill" width="128" height="128">
</p>

<p align="center">
  <strong>AIコーディングアシスタントから、テキストで無料で画像を生成。</strong><br>
  Claude Code · OpenClaw · Codex · Antigravity · Paperclip 対応
</p>

<p align="center">
  <a href="../README.md">English</a> ·
  <a href="./README_TW.md">繁體中文</a> ·
  <a href="./README_JA.md">日本語</a> ·
  <a href="./README_KO.md">한국어</a> ·
  <a href="./README_ES.md">Español</a> ·
  <a href="./README_DE.md">Deutsch</a> ·
  <a href="./README_FR.md">Français</a> ·
  <a href="./README_IT.md">Italiano</a>
</p>

---

## 概要

**zimage** は、AIアシスタントにテキストから画像を生成する機能を追加するスキルです。Alibaba Tongyi-MAIチームが開発したオープンソースモデル [Z-Image-Turbo](https://github.com/Tongyi-MAI/Z-Image)（60億パラメータ）を、ModelScopeの無料APIを通じて利用します。

```
あなた：  図書館で本を読んでいるキツネの画像を作って
AI：     送信中: 図書館で本を読んでいるキツネ
         タスク 91204 — 結果を待っています…
         保存完了 → fox_library.jpg
```

### 比較

|  | zimage | DALL-E 3 | Midjourney |
|--|--------|----------|------------|
| 料金 | **無料** | $0.04–0.08 / 枚 | $10+/月〜 |
| オープンソース | Apache 2.0 | いいえ | いいえ |
| セットアップ時間 | 約5分 | 課金設定が必要 | Discordが必要 |

> **無料枠：** 1日合計2,000回、モデルごとに500回/日。制限は動的に調整される場合があります。（[公式制限](https://modelscope.ai/docs/model-service/API-Inference/limits)）

---

## セットアップ

### ステップ1 — Alibaba Cloudアカウント（無料）

こちらから登録：**https://www.alibabacloud.com/campaign/benefits?referral_code=A9242N**

登録時に電話番号の認証と支払い方法の登録が必要です。**Z-Image自体は無料で課金されません**が、Alibaba Cloudはアカウントに支払い情報の登録を求めます。

### ステップ2 — ModelScopeアカウント + 連携

1. **https://modelscope.ai/register?inviteCode=futurizerush&invitorName=futurizerush&login=true&logintype=register** でアカウント登録（GitHubログイン対応）
2. **設定 → Bind Alibaba Cloud Account** からステップ1のアカウントを連携

### ステップ3 — APIトークン取得

1. **https://modelscope.ai/my/access/token** にアクセス
2. **Create Your Token** をクリック
3. トークンをコピー（形式：`ms-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`）

---

## インストール

<details>
<summary><b>Claude Code</b></summary>

Claude Codeで次のように伝えてください：

```
Install the zimage skill from https://github.com/FuturizeRush/zimage-skill
```

続いて：

```
Set my MODELSCOPE_API_KEY environment variable to ms-あなたのトークン
```

Claude Codeを再起動してください。
</details>

<details>
<summary><b>OpenClaw / ClawHub</b></summary>

```bash
openclaw skills install zimage
# または
npx clawhub@latest install zimage
```

```bash
export MODELSCOPE_API_KEY="ms-あなたのトークン"
```
</details>

<details>
<summary><b>Codex / Antigravity / Paperclip / その他</b></summary>

```bash
git clone https://github.com/FuturizeRush/zimage-skill.git
cd zimage-skill
pip install Pillow  # オプション（フォーマット変換用）
export MODELSCOPE_API_KEY="ms-あなたのトークン"
```

```bash
python3 imgforge.py "海に沈む夕日" sunset.jpg
```
</details>

---

## 使い方

### AIアシスタント経由

自然言語で指示するだけ：

```
おしゃれなカフェの画像を作って、暖かい照明、映画のような雰囲気
炎を吐くドット絵のドラゴンを描いて
ミニマルなロゴを作って、青のグラデーション
```

### CLI直接実行

```bash
# 基本
python3 imgforge.py "火星の宇宙飛行士"

# カスタムサイズ（横長）
python3 imgforge.py "ゴールデンアワーの山のパノラマ" -o panorama.jpg -W 2048 -H 1024

# JSON出力
python3 imgforge.py "抽象アート" --json
```

### CLIフラグ

| フラグ | デフォルト | 説明 |
|--------|-----------|------|
| `prompt` | *（必須）* | 生成する画像の説明 |
| `-o` / `--out` | `output.jpg` | 出力パス |
| `-W` / `--width` | `1024` | 幅、512–2048 px |
| `-H` / `--height` | `1024` | 高さ、512–2048 px |
| `--json` | オフ | JSON形式で出力 |

---

## トラブルシューティング

| 問題 | 解決方法 |
|------|---------|
| `MODELSCOPE_API_KEY is not set` | 上記の[セットアップ](#セットアップ)を完了してください |
| `401 Unauthorized` | **modelscope.ai**（.cnではなく）を使用。Alibaba Cloud連携を確認。トークンを再生成。 |
| タイムアウト | API負荷が高い — 1分後に再試行 |
| コンテンツモデレーション | プロンプトを変更してください |

---

## 技術情報

- **外部依存なし** — Python標準ライブラリの `urllib.request` を使用。Pillowはオプション。
- 512×512 から 2048×2048 までのカスタムサイズに対応。
- モデル：[Tongyi-MAI/Z-Image-Turbo](https://huggingface.co/Tongyi-MAI/Z-Image-Turbo)（Apache 2.0）
- API：ModelScope International（`api-inference.modelscope.ai`）

---

## ライセンス

MIT-0 — 自由に使えます。帰属表示不要。


path: docs/README_KO.md
content: # zimage — 무료 AI 이미지 생성 스킬

<p align="center">
  <img src="../icon.png" alt="Z-Image Skill" width="128" height="128">
</p>

<p align="center">
  <strong>AI 코딩 어시스턴트에서 텍스트로 무료 이미지를 생성하세요.</strong><br>
  Claude Code · OpenClaw · Codex · Antigravity · Paperclip 지원
</p>

<p align="center">
  <a href="../README.md">English</a> ·
  <a href="./README_TW.md">繁體中文</a> ·
  <a href="./README_JA.md">日本語</a> ·
  <a href="./README_KO.md">한국어</a> ·
  <a href="./README_ES.md">Español</a> ·
  <a href="./README_DE.md">Deutsch</a> ·
  <a href="./README_FR.md">Français</a> ·
  <a href="./README_IT.md">Italiano</a>
</p>

---

## 개요

**zimage**는 AI 어시스턴트에 텍스트에서 이미지를 생성하는 기능을 추가하는 스킬입니다. Alibaba Tongyi-MAI 팀이 개발한 오픈소스 모델 [Z-Image-Turbo](https://github.com/Tongyi-MAI/Z-Image)(60억 파라미터)를 ModelScope의 무료 API를 통해 호출합니다.

```
사용자:  도서관에서 책을 읽는 여우 이미지를 만들어줘
AI:     제출 중: 도서관에서 책을 읽는 여우
        태스크 91204 — 결과 대기 중…
        저장 완료 → fox_library.jpg
```

### 비교

|  | zimage | DALL-E 3 | Midjourney |
|--|--------|----------|------------|
| 가격 | **무료** | $0.04–0.08 / 장 | $10+/월 |
| 오픈소스 | Apache 2.0 | 아니오 | 아니오 |
| 설정 시간 | 약 5분 | 결제 설정 필요 | Discord 필요 |

> **무료 할당량:** 하루 총 2,000회, 모델당 500회/일. 한도는 동적으로 조정될 수 있습니다. ([공식 한도](https://modelscope.ai/docs/model-service/API-Inference/limits))

---

## 설정

### 1단계 — Alibaba Cloud 계정 (무료)

여기서 가입: **https://www.alibabacloud.com/campaign/benefits?referral_code=A9242N**

가입 시 전화번호 인증과 결제 수단 등록이 필요합니다. **Z-Image 자체는 무료이며 요금이 부과되지 않습니다**. 단, Alibaba Cloud는 계정에 결제 정보 등록을 요구합니다.

### 2단계 — ModelScope 계정 + 연동

1. **https://modelscope.ai/register?inviteCode=futurizerush&invitorName=futurizerush&login=true&logintype=register** 에서 가입 (GitHub 로그인 지원)
2. **설정 → Bind Alibaba Cloud Account**에서 1단계 계정 연동

### 3단계 — API 토큰

1. **https://modelscope.ai/my/access/token** 방문
2. **Create Your Token** 클릭
3. 토큰 복사 (형식: `ms-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`)

---

## 설치

<details>
<summary><b>Claude Code</b></summary>

Claude Code에서 이렇게 말하세요:

```
Install the zimage skill from https://github.com/FuturizeRush/zimage-skill
```

그 다음:

```
Set my MODELSCOPE_API_KEY environment variable to ms-당신의토큰
```

Claude Code를 재시작하세요.
</details>

<details>
<summary><b>OpenClaw / ClawHub</b></summary>

```bash
openclaw skills install zimage
# 또는
npx clawhub@latest install zimage
```

```bash
export MODELSCOPE_API_KEY="ms-당신의토큰"
```
</details>

<details>
<summary><b>Codex / Antigravity / Paperclip / 기타</b></summary>

```bash
git clone https://github.com/FuturizeRush/zimage-skill.git
cd zimage-skill
pip install Pillow  # 선택 사항 (형식 변환용)
export MODELSCOPE_API_KEY="ms-당신의토큰"
```

```bash
python3 imgforge.py "바다 위의 석양" sunset.jpg
```
</details>

---

## 사용법

### AI 어시스턴트를 통해

자연어로 요청하세요:

```
아늑한 카페 이미지를 만들어줘, 따뜻한 조명, 시네마틱
불을 뿜는 픽셀 아트 드래곤을 그려줘
미니멀한 로고를 만들어줘, 파란 그라데이션
```

### CLI 직접 실행

```bash
# 기본
python3 imgforge.py "화성의 우주비행사"

# 커스텀 사이즈 (가로형)
python3 imgforge.py "골든아워의 산 파노라마" -o panorama.jpg -W 2048 -H 1024

# JSON 출력
python3 imgforge.py "추상 예술" --json
```

---

## 문제 해결

| 문제 | 해결 방법 |
|------|----------|
| `MODELSCOPE_API_KEY is not set` | [설정](#설정)을 완료하세요 |
| `401 Unauthorized` | **modelscope.ai** (.cn 아님) 사용. Alibaba Cloud 연동 확인. 토큰 재생성. |
| 타임아웃 | API 부하 — 1분 후 재시도 |
| 콘텐츠 모더레이션 | 프롬프트를 수정하세요 |

---

## 라이선스

MIT-0 — 자유롭게 사용하세요. 저작자 표시 불필요.


path: docs/README_TW.md
content: # zimage — 免費 AI 圖片生成技能

<p align="center">
  <img src="../icon.png" alt="Z-Image Skill" width="128" height="128">
</p>

<p align="center">
  <strong>在 AI 編程助手裡，用一句話免費生成精美圖片。</strong><br>
  支援 Claude Code · OpenClaw · Codex · Antigravity · Paperclip
</p>

<p align="center">
  <a href="../README.md">English</a> ·
  <a href="./README_TW.md">繁體中文</a> ·
  <a href="./README_JA.md">日本語</a> ·
  <a href="./README_KO.md">한국어</a> ·
  <a href="./README_ES.md">Español</a> ·
  <a href="./README_DE.md">Deutsch</a> ·
  <a href="./README_FR.md">Français</a> ·
  <a href="./README_IT.md">Italiano</a>
</p>

---

## 簡介

**zimage** 讓你的 AI 助手能夠根據文字描述生成圖片。背後使用阿里巴巴通義 MAI 團隊開發的開源模型 [Z-Image-Turbo](https://github.com/Tongyi-MAI/Z-Image)（60 億參數），透過 ModelScope 的免費 API 呼叫。

```
你：   幫我生成一隻狐狸在圖書館看書的圖片
AI：   正在提交：一隻狐狸在圖書館看書
       任務 91204 — 等待結果中…
       已儲存 → fox_library.jpg
```

### 比較

|  | zimage | DALL-E 3 | Midjourney |
|--|--------|----------|------------|
| 費用 | **免費** | $0.04–0.08 / 張 | $10+/月起 |
| 開源 | Apache 2.0 | 否 | 否 |
| 設定時間 | 約 5 分鐘 | 需綁定付款 | 需要 Discord |

> **免費額度：** 每日共 2,000 次 API 呼叫，單一模型上限 500 次/天。額度可能動態調整。（[官方限額說明](https://modelscope.ai/docs/model-service/API-Inference/limits)）

---

## 設定

### 第一步 — 阿里雲帳號（免費）

到這裡註冊：**https://www.alibabacloud.com/campaign/benefits?referral_code=A9242N**

註冊時需要驗證手機號碼並綁定付款方式。**Z-Image 本身免費，不會向你收費**，但阿里雲帳號要求綁定付款資訊才能使用。

### 第二步 — ModelScope 帳號 + 綁定

1. 到 **https://modelscope.ai/register?inviteCode=futurizerush&invitorName=futurizerush&login=true&logintype=register** 註冊（支援 GitHub 登入）
2. 進入 **設定 → Bind Alibaba Cloud Account**，綁定第一步建立的阿里雲帳號

> ⚠️ 請使用 **modelscope.ai**（國際站），不是 modelscope.cn（中國站）。

### 第三步 — 取得 API Token

1. 前往 **https://modelscope.ai/my/access/token**
2. 點擊 **Create Your Token**
3. 複製 Token（格式：`ms-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`）

---

## 安裝

<details>
<summary><b>Claude Code</b></summary>

在 Claude Code 裡說：

```
幫我安裝 zimage skill，來源是 https://github.com/FuturizeRush/zimage-skill
```

然後：

```
幫我設定環境變數 MODELSCOPE_API_KEY，值是 ms-你的token
```

重新啟動 Claude Code 即可。
</details>

<details>
<summary><b>OpenClaw / ClawHub</b></summary>

```bash
openclaw skills install zimage
# 或
npx clawhub@latest install zimage
```

```bash
export MODELSCOPE_API_KEY="ms-你的token"
```
</details>

<details>
<summary><b>Codex / Antigravity / Paperclip / 其他</b></summary>

```bash
git clone https://github.com/FuturizeRush/zimage-skill.git
cd zimage-skill
pip install Pillow  # 選用，用於格式轉換
export MODELSCOPE_API_KEY="ms-你的token"
```

```bash
python3 imgforge.py "海邊的日落" sunset.jpg
```
</details>

---

## 使用方式

### 透過 AI 助手

直接用自然語言描述：

```
生成一張溫馨咖啡廳的圖片，溫暖燈光，電影感
畫一隻噴火的像素風格龍
做一個極簡風格的 logo，藍色漸層
```

### 直接 CLI

```bash
# 基本用法
python3 imgforge.py "太空人在火星上"

# 自訂尺寸（橫幅）
python3 imgforge.py "黃金時刻的山景全景" -o panorama.jpg -W 2048 -H 1024

# JSON 輸出
python3 imgforge.py "抽象藝術" --json
```

### CLI 參數

| 參數 | 預設值 | 說明 |
|------|--------|------|
| `prompt` | *（必填）* | 圖片描述 |
| `-o` / `--out` | `output.jpg` | 輸出路徑 |
| `-W` / `--width` | `1024` | 寬度，512–2048 px |
| `-H` / `--height` | `1024` | 高度，512–2048 px |
| `--json` | 關閉 | JSON 格式輸出 |

---

## 常見問題

| 問題 | 解決方式 |
|------|---------|
| `MODELSCOPE_API_KEY is not set` | 請完成上方[設定](#設定)步驟 |
| `401 Unauthorized` | 確認用的是 **modelscope.ai**（不是 .cn）。確認已綁定阿里雲。重新產生 Token。 |
| 逾時 | API 負載較高，請稍後再試 |
| 內容審核錯誤 | 修改描述內容後重試 |

---

## 技術資訊

- **零必要依賴** — 使用 Python 標準庫 `urllib.request`。Pillow 為選用（僅用於格式轉換）。
- 支援 512×512 到 2048×2048 自訂尺寸。
- `--json` 可與其他工具串接。
- 模型：[Tongyi-MAI/Z-Image-Turbo](https://huggingface.co/Tongyi-MAI/Z-Image-Turbo)（Apache 2.0）
- API：ModelScope 國際站（`api-inference.modelscope.ai`）

---

## 授權

MIT-0 — 自由使用，無需署名。


path: imgforge.py
content: #!/usr/bin/env python3
"""
imgforge — text-to-image via ModelScope's Z-Image-Turbo endpoint.

A lightweight CLI that talks to the ModelScope async inference API.
Uses only Python stdlib; Pillow is auto-detected for format conversion.
"""

import argparse
import json
import os
import pathlib
import sys
import time
import urllib.error
import urllib.request

_ENDPOINT = "https://api-inference.modelscope.ai"
_MODEL = "Tongyi-MAI/Z-Image-Turbo"


# ── HTTP helpers ──────────────────────────────────────────────────────

def _post(path: str, token: str, payload: dict, extra: dict | None = None) -> dict:
    hdrs = {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}
    if extra:
        hdrs.update(extra)
    body = json.dumps(payload, ensure_ascii=False).encode("utf-8")
    req = urllib.request.Request(f"{_ENDPOINT}{path}", data=body, headers=hdrs, method="POST")
    with urllib.request.urlopen(req, timeout=60) as r:
        return json.loads(r.read())


def _get(path: str, token: str, extra: dict | None = None) -> dict:
    hdrs = {"Authorization": f"Bearer {token}"}
    if extra:
        hdrs.update(extra)
    req = urllib.request.Request(f"{_ENDPOINT}{path}", headers=hdrs, method="GET")
    with urllib.request.urlopen(req, timeout=60) as r:
        return json.loads(r.read())


def _fetch_bytes(url: str) -> bytes:
    with urllib.request.urlopen(url, timeout=120) as r:
        return r.read()


# ── Core logic ────────────────────────────────────────────────────────

def _create_task(token: str, prompt: str, w: int, h: int) -> str:
    resp = _post(
        "/v1/images/generations", token,
        {"model": _MODEL, "prompt": prompt, "width": w, "height": h},
        extra={"X-ModelScope-Async-Mode": "true"},
    )
    return resp["task_id"]


def _await_task(token: str, tid: str, limit: float = 150) -> str:
    end = time.monotonic() + limit
    while time.monotonic() < end:
        data = _get(f"/v1/tasks/{tid}", token, extra={"X-ModelScope-Task-Type": "image_generation"})
        st = data.get("task_status", "")
        if st == "SUCCEED":
            return data["output_images"][0]
        if st == "FAILED":
            raise RuntimeError(data.get("error", "Task failed with no details."))
        time.sleep(4)
    raise TimeoutError(f"No result after {limit:.0f}s — the API may be overloaded.")


def _save(raw: bytes, dest: pathlib.Path) -> None:
    dest.parent.mkdir(parents=True, exist_ok=True)
    try:
        from PIL import Image
        from io import BytesIO
        Image.open(BytesIO(raw)).save(dest)
    except ImportError:
        dest.write_bytes(raw)


# ── CLI ───────────────────────────────────────────────────────────────

def main() -> None:
    ap = argparse.ArgumentParser(
        prog="imgforge",
        description="Generate an image from text (free, via Z-Image-Turbo).",
    )
    ap.add_argument("prompt", help="Describe the image you want")
    ap.add_argument("-o", "--out", default="output.jpg", help="Save path (default: output.jpg)")
    ap.add_argument("-W", "--width", type=int, default=1024, help="Width 512-2048 (default: 1024)")
    ap.add_argument("-H", "--height", type=int, default=1024, help="Height 512-2048 (default: 1024)")
    ap.add_argument("--json", dest="as_json", action="store_true", help="Machine-readable JSON output")
    args = ap.parse_args()

    [REDACTED_SECRET]"MODELSCOPE_API_KEY", "")
    if not [REDACTED_SECRET]
            "MODELSCOPE_API_KEY is not set.\n\n"
            "Get a free token:\n"
            "  1. Alibaba Cloud  → https://www.alibabacloud.com/campaign/benefits?referral_code=A9242N\n"
            "  2. ModelScope      → https://modelscope.ai/register?inviteCode=futurizerush&invitorName=futurizerush&login=true&logintype=register\n"
            "  3. Create token    → https://modelscope.ai/my/access/token\n\n"
            "Then:  export MODELSCOPE_API_KEY='ms-...'"
        )

    dest = pathlib.Path(args.out).expanduser()
    try:
        if not args.as_json:
            print(f"[imgforge] prompt: {args.prompt[:90]}{'…' if len(args.prompt) > 90 else ''}")

        tid = _create_task(token, args.prompt, args.width, args.height)
        if not args.as_json:
            print(f"[imgforge] task {tid} — generating…")

        url = _await_task(token, tid)
        _save(_fetch_bytes(url), dest)

        if args.as_json:
            print(json.dumps({"ok": True, "path": str(dest), "task": tid}))
        else:
            print(f"[imgforge] saved → {dest}")

    except (RuntimeError, TimeoutError, urllib.error.HTTPError) as e:
        if args.as_json:
            print(json.dumps({"ok": False, "error": str(e)}))
        else:
            print(f"[imgforge] error: {e}", file=sys.stderr)
        sys.exit(1)


if __name__ == "__main__":
    main()


path: requirements.txt
content: Pillow>=8.0.0


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)