novita

CLI for generating images with the Novita Hunyuan Image 3 API.

Build

cargo build --release
# binary at: target/release/novita

Usage

# Set your API key (required)
export NOVITA_API_KEY=your_key_here

# Prompt via flag
novita --prompt "a calico cat in a neon-lit alley"

# Prompt via file
novita --file prompt.txt

# Prompt via stdin
echo "a stormy sea at midnight" | novita

# Custom size and seed
novita --prompt "a forest at dawn" --width 1280 --height 720 --seed 42

# Specify output file
novita --prompt "a red panda" --output red_panda.png

Authentication

The API key is read exclusively from the NOVITA_API_KEY environment variable:

export NOVITA_API_KEY=your_key_here

The CLI will exit with a clear error if it is not set.

Options

Flag	Default	Description
--prompt / -p	—	Prompt text
--file / -f	—	Path to plaintext prompt file
--width	1024	Image width in pixels
--height	1024	Image height in pixels
--seed	-1	Seed (-1 = random)
--count / -c	1	Number of images to generate in parallel
--output / -o	novita_hunyuan3_<timestamp>.png	Output file path (index appended when --count > 1)

Parallel generation

Use --count N to submit N requests simultaneously and poll/download them all concurrently:

novita --prompt "a crab in a top hat" --count 4
# outputs: novita_hunyuan3_<ts>_0.png ... novita_hunyuan3_<ts>_3.png

All requests are submitted before waiting on any of them, so total time ≈ single-image time regardless of N (up to API rate limits).

Prompt resolution

Priority order:

1. --prompt flag
2. --file flag
3. stdin (if piped)

How it works

1. POST to /v3/async/hunyuan-image-3 → get task_id
2. Poll /v3/async/task-result?task_id=... until TASK_STATUS_SUCCEED
3. Download image from returned URL
4. Save to output file

The output file path is also printed to stdout (stderr gets the status messages), so you can pipe it:

open $(novita --prompt "a crab in a top hat" 2>/dev/null)