| 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. |
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
- Load config from
{baseDir}/assets/config.example.yaml or user-provided config.
- Resolve provider order (
--provider auto follows routing.provider_order).
- Resolve model candidates per provider (
requested -> z-image-turbo -> provider default).
- Prepare prompt for each attempt:
- optionally auto-translate for target models
- optionally optimize prompt with provider text model
- Execute generation request.
- On quota/auth failures, rotate token; if exhausted, move to next provider.
- Repeat the generation flow when
--count > 1, and rotate provider/token start position per image to spread load.
- 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:
--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)--auto-translate / --no-auto-translate (default off)--config (default {baseDir}/assets/config.example.yaml)--output (optional output file path)--count (number of images in one run, default 1)--json (structured output)
Output contract
When --json is used, output these fields on success:
idurlprovidermodelprompt_originalprompt_finalseedstepsguidance_scaleaspect_ratiofallback_chainelapsed_ms
On failure, output structured error fields:
error_typeerrorfallback_chain
When --count > 1, JSON output contains:
countimages (array of standard success payloads)elapsed_ms
References
Read only what is needed:
- Provider API wiring:
references/provider-endpoints.md
- Model coverage and fallback:
references/model-matrix.md
- Token rotation and date rules:
references/token-rotation-policy.md
- Prompt optimization pipeline:
references/prompt-optimization-policy.md
- OpenClaw setup details:
references/openclaw-integration.md
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.
