Free Quota Image Skill

---

name: free-quota-image-skill

description: Generate images from text with a free-quota-first multi-provider workflow. Use this skill when a user asks for text-to-image generation that needs provider routing (Hugging Face, Gitee, ModelScope, A4F, OpenAI-compatible private endpoints), token pooling with automatic rotation on quota/auth failures, public API fallback for Hugging Face, prompt optimization, model fallback, batch generation in one command, and structured generation outputs.

metadata: {"openclaw":{"homepage":"https://github.com/Amery2010/peinture"}}

---

# Free Quota Image Skill

Overview

Use this skill to run a provider-agnostic text-to-image pipeline with free-quota-first routing, token rotation, and prompt enhancement.

Workflow

1. Load config from `{baseDir}/assets/config.example.yaml` or user-provided config.

2. Resolve provider order (`--provider auto` follows `routing.provider_order`).

3. Resolve model candidates per provider (`requested -> z-image-turbo -> provider default`).

4. Prepare prompt for each attempt:

- optionally auto-translate for target models

- optionally optimize prompt with provider text model

5. Execute generation request.

6. On quota/auth failures, rotate token; if exhausted, move to next provider.

7. Repeat the generation flow when `--count > 1`, and rotate provider/token start position per image to spread load.

8. Return stable JSON output fields or direct URL output.

Commands

Install dependencies:

python -m pip install -r {baseDir}/scripts/requirements.txt

Run generation:

python {baseDir}/scripts/run_text2img.py --prompt "cinematic rainy tokyo alley" --json

Run with explicit provider/model:

python {baseDir}/scripts/run_text2img.py --prompt "a fox astronaut" --provider gitee --model flux-2 --json

Save image locally:

python {baseDir}/scripts/run_text2img.py --prompt "retro sci-fi city" --output ./out.png

Generate multiple images in one run:

python {baseDir}/scripts/run_text2img.py --prompt "anime passport portrait" --count 4 --json

CLI contract

Use `{baseDir}/scripts/run_text2img.py` with the fixed contract:

Output contract

When `--json` is used, output these fields on success:

On failure, output structured error fields:

When `--count > 1`, JSON output contains:

References

Read only what is needed:

Scope boundaries

Keep this skill focused on text-to-image core only.

Do not add image editing, video generation, or cloud storage workflows in this skill.