ClawHub

free quota text to image

Workflows

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.

Install

openclaw skills install 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:

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:

  • id
  • url
  • provider
  • model
  • prompt_original
  • prompt_final
  • seed
  • steps
  • guidance_scale
  • aspect_ratio
  • fallback_chain
  • elapsed_ms

On failure, output structured error fields:

  • error_type
  • error
  • fallback_chain

When --count > 1, JSON output contains:

  • count
  • images (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.

More in Workflows