free-quota-image-skill

# 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:

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

Run generation:

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

Run with explicit provider/model:

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

Save image locally:

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

Generate multiple images in one run:

```bash
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:

- `--prompt` (required)
- `--provider` (`auto|huggingface|gitee|modelscope|a4f|openai_compatible`, default `auto`)
- `--model` (default `z-image-turbo`)
- `--aspect-ratio` (default `1:1`)
- `--seed` (optional int)
- `--steps` (optional int)
- `--guidance-scale` (optional float)
- `--enable-hd` (flag)
- `--optimize-prompt` / `--no-optimize-prompt` (default on)...