Imagine Create

Create Media With Vofy CLI

Deliver generated media with a deterministic, non-interactive workflow.

Workflow

1. Run vofy status; if auth fails, tell the user to run vofy login. 2. Identify output type, source assets, aspect ratio, duration, resolution, and whether local files are required. 3. Load imagine-prompt when the user gives a rough idea, asks for prompt improvement, or model-specific wording matters. 4. Choose the simplest matching mode from the tables below. 5. Pick a default model unless the user named one; load imagine-models only for strict limits, price, or special flags. 6. Build one non-interactive command with --yes and, when local output is useful, --download-to ./output. 7. Return file paths or resource URLs; for async jobs, return the task id and next check command.

If vofy is missing, stop and ask the user to install vofy-cli@0.1.7 and authenticate once.

Default Model Shortcuts

Check vofy models <model> before adding optional flags such as --audio, --background, --web-search, --multi-shot, or motion-control settings.

Image Modes

Base command:

vofy image create --model <model> --prompt "<prompt>" --aspect-ratio <ratio> --resolution <resolution> --yes --download-to ./output

Video Modes

Base command:

vofy video create --model <model> --prompt "<prompt>" --duration <seconds> --aspect-ratio <ratio> --yes --download-to ./output

Result Handling

• Sync create commands wait for completion and print output by default.
• --download-to ./output saves files locally and creates the directory if needed.
• --result-url prints generated resource URLs explicitly after completion.
• --async returns early; use vofy tasks --plain --type video and vofy task <id_or_prefix> --download-to ./output later.
• If the command fails because a value is unsupported, run vofy models <model> and retry with one of the listed ratios, resolutions, durations, or modes.

Common Validation Traps

• --video is ambiguous; always add --mode video_to_video or --mode video_extension.
• Mixed --reference-image with --reference-video or --reference-audio requires --mode multimodal_reference.
• kling-2.6 needs resolution=1080p for --audio and for last-frame interpolation.
• kling-3.0 --multi-shot requires --shot-type; customize uses --multi-prompt, while intelligence uses --prompt.
• Source-driven modes may ignore --aspect-ratio or --resolution; trust derived values from input media.

See examples.md for broader scenarios and commands-reference.md for full CLI help.

vofy-cli Examples

Real-world scenarios for image and video creation.

Image Examples

Product mockup with transparent background

vofy image create \
  --model gpt-image-1.5 \
  --prompt "a sleek wireless headphone, product photography, white background" \
  --background transparent \
  --aspect-ratio 1:1 \
  --yes --download-to ./output

Social media banner

vofy image create \
  --model seedream-4.5 \
  --prompt "abstract gradient background with geometric shapes, modern tech aesthetic" \
  --aspect-ratio 16:9 \
  --resolution 2K \
  --yes --download-to ./output

Edit an existing photo

vofy image create \
  --model gpt-image-1.5 \
  --prompt "change the sky to a dramatic sunset" \
  --image ./landscape.jpg \
  --yes --download-to ./output

Inpainting — remove an object

vofy image create \
  --model gpt-image-1.5 \
  --prompt "clean background, no person" \
  --image ./photo.jpg \
  --mask ./mask.png \
  --yes --download-to ./output

Multiple outputs for selection

vofy image create \
  --model seedream-4.5 \
  --prompt "minimalist app icon for a weather app" \
  --n 4 \
  --aspect-ratio 1:1 \
  --yes --download-to ./output

Batch creation (multiple tasks)

vofy image create \
  --model seedream-4.5 \
  --prompt "hero image for a travel blog" \
  --batch-size 3 \
  --aspect-ratio 16:9 \
  --yes --download-to ./output

Video Examples

Simple text-to-video

vofy video create \
  --model veo-3.1 \
  --prompt "a timelapse of clouds moving over a mountain range, cinematic" \
  --duration 6 \
  --aspect-ratio 16:9 \
  --yes --download-to ./output

Animate a product image

vofy video create \
  --model kling-3.0 \
  --prompt "the product slowly rotates 360 degrees on a white surface" \
  --first-frame ./product.png \
  --duration 5 \
  --yes --download-to ./output

Video with generated audio

vofy video create \
  --model kling-3.0 \
  --prompt "a barista making latte art, ambient coffee shop sounds" \
  --audio \
  --duration 8 \
  --yes --download-to ./output

Morph between two images

vofy video create \
  --model seedance-2.0 \
  --prompt "smooth morphing transition" \
  --first-frame ./before.png \
  --last-frame ./after.png \
  --duration 4 \
  --yes --download-to ./output

Fast preview video

vofy video create \
  --model veo-3.1-fast \
  --prompt "a person walking through a neon-lit city at night" \
  --duration 4 \
  --yes --download-to ./output

Transform existing video style

vofy video create \
  --model seedance-2.0 \
  --prompt "convert to anime style" \
  --mode video_to_video \
  --video ./original.mp4 \
  --yes --download-to ./output

Extend a video

vofy video create \
  --model seedance-2.0 \
  --prompt "continue the scene naturally" \
  --video ./clip.mp4 \
  --mode video_extension \
  --yes --download-to ./output

Reference image for style consistency

vofy video create \
  --model veo-3.1 \
  --prompt "a character walking through a garden" \
  --reference-image ./character-ref.png \
  --duration 8 \
  --yes --download-to ./output

Async Workflow

For long-running video tasks, use async mode:

# Submit without waiting
vofy video create \
  --model veo-3.1 \
  --prompt "epic cinematic scene" \
  --duration 8 \
  --async \
  --yes

# Check status later
vofy tasks --plain --type video

# Download when complete
vofy task <task_id> --download-to ./output