hf-inference

HF Inference

Use Hugging Face serverless inference for text-to-image and text-to-video generation. Prefer the bundled CLI so model id, seed, parameters, provider fallback, and output path are explicit.

Environment

Set HF_READ_TOKEN or HF_TOKEN before live generation. Never write tokens into commands, files, notes, or final responses.

$env:HF_TOKEN = "<token>"

The script checks HF_READ_TOKEN first, then HF_TOKEN, matching the Nymbo-Tools shared inference helpers.

Image Generation

Default model: Tongyi-MAI/Z-Image-Turbo.

python "C:\Users\devan\.codex\skills\hf-inference\scripts\hf_generate.py" image --prompt "A clean product render of a glass compass" --out "output\hf\compass.png"

Useful options:

• --model-id for any HF text-to-image model
• --negative-prompt
• --width and --height
• --steps
• --cfg-scale
• --seed, with -1 meaning random
• --providers auto,replicate,fal-ai
• --extra-json for provider/model-specific parameters

Video Generation

Default model: Wan-AI/Wan2.2-T2V-A14B.

python "C:\Users\devan\.codex\skills\hf-inference\scripts\hf_generate.py" video --prompt "Ocean waves rolling under moonlight" --out "output\hf\waves.mp4"

Useful options:

• --model-id for any HF text-to-video model
• --negative-prompt
• --width and --height
• --steps
• --cfg-scale
• --seed, with -1 meaning random
• --fps
• --duration
• --providers auto,replicate,fal-ai
• --extra-json for provider/model-specific parameters

Workflow

1. Ask only when the prompt, output type, or model choice is genuinely ambiguous.
2. Use the default model when the user does not specify one.
3. Use stable output paths under the current project, usually output\hf\.
4. Use a seed when the user asks for reproducibility; otherwise leave --seed -1.
5. If the provider rejects a parameter, retry with fewer model-specific options or a different provider.
6. Report the output path, model id, provider, size, and seed.

For video, the script first tries the full width/height/FPS/duration payload, then retries with a minimal serverless payload when providers reject model-specific extras.

Dependencies

Install only when missing:

python -m pip install huggingface_hub pillow

Video generation depends on serverless provider support for the chosen model. Some models require provider-specific parameters through --extra-json.