Higgsfield generation

Helper: python <skill-dir>/scripts/hf.py (Python 3.8+, standard library only). JSON on stdout, progress on stderr. Run it from the user's project folder; jobs are recorded in work/higgsfield/jobs.db, files go to outputs/.

1. Pick the model

• hf.py models [words] searches all models, e.g. hf.py models kling image. MODELS.md in the skill folder lists them all with example prices.
• If the user names a model, use it exactly (model id like kling-video-v3.0-pro-text-to-video or its endpoint kling-video/v3.0/pro/text-to-video). Never swap to a different model or variant without asking.
• If they don't, suggest one that fits the task (text-to-video, image-to-video, reference-to-video, video-edit, text-to-image, image edit) and mention its example price. Default for video: bytedance-seedance-2.5-text-to-video, 5 s, 720p.
• hf.py info <model> shows every parameter (type, allowed values, default, required), outputs, pricing note, and an example. Read it before writing a request; parameters differ between models, even between variants of one model. For full details open the model's agent_prompt URL from info.

2. Build the request

• Write JSON to work/higgsfield/<job>.json with only parameters from info. hf.py validate --model M --input F checks it offline.
• Local images/video/audio: hf.py upload <file> returns a public_url; put that URL in the model's field (image_url, image_urls, video_url, start_image_url, ...). Only upload files the user asked you to use. Supported: jpg, png, webp, gif, wav, mp4.
• Marketing Studio product shots / ads with a preset: hf.py presets lists preset ids; ask the user to choose; set enhance_prompt: true, preset_id, and the product image in image_urls. Never invent preset ids.
• hf.py check verifies the key for free. If credentials are missing, tell the user to fill ~/.config/higgsfield/.env (HF_API_KEY_ID, HF_API_KEY_SECRET). Never ask for or print the key, and never put it in commands or project files.

3. Price it