Flatkey CLI

Creative generation from the terminal for media teams and AI agents. Generate images, videos, audio, and text through one Flatkey credit balance.

Languages: English | 简体中文 | 日本語

Website: flatkey.ai

npm install -g @flatkey-ai/cli
export FLATKEY_API_KEY=<your-flatkey-api-key>

flatkey image generate --prompt "editorial cover, neon city at dawn" -o cover.png
flatkey video generate --prompt "cinematic product launch clip" --model seedance2 -o launch.mp4
flatkey audio generate --prompt "你好，这是 Flatkey 的配音测试" -o speech.mp3
flatkey models --json
flatkey credits --json

Why Flatkey CLI

• One CLI for image, video, audio, and text generation.
• One FLATKEY_API_KEY, one credit balance.
• Agent-friendly JSON mode with clean stdout.
• Local output support with --output / -o.
• Cross-platform npm package for macOS, Linux, and Windows.
• Cool terminal progress animation for human runs; disabled in --json mode.

Product Comparison

Flatkey is built for media teams that want programmatic generation without paying a premium for a closed creative suite or waiting in long queues. Higgsfield is strong for creator-facing workflows, and Dreamina/Jimeng has good ByteDance video models, but both can become expensive or slow once the workflow moves from manual creation to repeated AI-agent testing. In our testing, Dreamina/Jimeng video generation can wait up to 5 hours during peak time, which makes one-by-one prompt iteration impractical.

Need	Flatkey	Higgsfield	Dreamina / Jimeng
Cost for repeat testing	Flatkey token pricing is at least ~20% lower than comparable retail routes, and some modalities such as image can be ~40% lower.	Credit packages can be expensive once premium video/image models are used heavily.	Subscription credits can be cheaper in some local workflows, but API-style automation usually has plan and region constraints.
Programmatic access	First-class CLI and API-router workflow. Designed for agents, scripts, and batch testing.	Strong product UI for creators; CLI-style automation is not the primary product promise.	CLI/API access is gated behind higher-tier setup in many workflows, not the default creator entry path.
Queue / iteration speed	Built for fast CLI retries, --dry-run, local outputs, and unified model routing.	Good for polished creator workflows, but heavy credit usage makes broad testing costly.	Peak-time queues can block video iteration; we have observed waits up to 5 hours for a single video generation test.
Modalities	Image, video, TTS, SFX, music, text, credits, status, and model discovery behind one Flatkey key.	Strong image/video creator stack and media tooling.	Strong ByteDance image/video models, especially Seedance/Dreamina-style workflows.
Agent ergonomics	--json, --output/-o, --dry-run, models, audio voices, and predictable stdout/stderr.	More oriented around human creative workflows.	More oriented around app/product workflow than simple agent protocol.
Best fit	Media teams building repeatable generation pipelines and AI-agent workflows.	Creators who want a polished visual production suite.	Teams already deep in CapCut/Dreamina/Jimeng ecosystem and willing to accept plan/queue tradeoffs.

In short: use Flatkey when the job is repeated media generation, cost-sensitive testing, and AI-agent automation. Use creator suites when you want their native editing UI more than a programmable router.

Install

npm install -g @flatkey-ai/cli

Run without installing:

npx @flatkey-ai/cli help --ai

Check local version:

flatkey --version
flatkey -v

Auth

Use an environment variable:

export FLATKEY_API_KEY=<key>

Or save it locally:

flatkey onboard --api-key <key>

Create a key at console.flatkey.ai/keys, then pass it with --api-key.

Commands

Generate Image

flatkey image generate \
  --prompt "magazine cover, reflective typography, studio lighting" \
  --model gpt-image-2 \
  -o cover.png

Upload a local image and get a temporary signed URL:

flatkey image upload --file ./reference.png

Generate Video

flatkey video generate \
  --prompt "8 second cinematic product reveal, glossy black background" \
  --model seedance2 \
  --ratio 16:9 \
  --resolution 720p \
  -o launch.mp4

Video ratios: 16:9, 9:16, 4:3, 3:4, 21:9, 1:1. Video resolutions: 480p, 720p, 1080p.

Local reference images are uploaded through Flatkey temporary media first:

flatkey video generate \
  --model Seedance2.0-pro \
  --prompt "a sleepy kitten, soft window light" \
  --image ./reference.png \
  -o kitten.mp4

First/last frame:

flatkey video generate \
  --model Seedance2.0-pro \
  --prompt "slow camera push-in" \
  --first-frame ./first.png \
  --last-frame ./last.png \
  -o transition.mp4

Generate Audio

Text to speech:

flatkey audio generate \
  --prompt "你好，这是 Flatkey 网关的语音测试。" \
  --voice-id EXAVITQu4vr4xnSDxMaL \
  --model eleven_multilingual_v2 \
  --stability 0.5 \
  --similarity-boost 0.75 \
  --style 0 \
  -o speech.mp3

List voices:

flatkey audio voices --json

Sound effects:

flatkey audio sfx \
  --prompt "glass shattering on the floor" \
  --duration 3 \
  -o sfx.mp3

Music:

flatkey audio music \
  --prompt "calm ambient piano, sad mood" \
  --music-length-ms 10000 \
  -o music.mp3

Generate Text

flatkey text generate \
  --prompt "write 5 sharp headlines for a creator tool launch" \
  --model gpt-5.5 \
  -o headlines.txt

Credits, Status, Models

flatkey credits --json
flatkey status --json
flatkey models --json
flatkey models --type image --json
flatkey help --ai

Models

Live model list:

flatkey models --json

Useful current defaults:

Type	Models
Image	gpt-image-2, nano-banana-pro-preview, Gemini image models
Video	seedance2, veo-3, veo-3-fast
Audio	eleven_multilingual_v2, ElevenLabs voices, sound effects, music
Text	gpt-5.5, Claude, Gemini, GLM, Grok models

models reads from the Flatkey console model registry. Generation calls use the Flatkey router.

Agent Protocol

Use this when wiring Flatkey into Codex, Claude Code, Cursor, or other agents:

flatkey help --ai

Agent rules:

• Prefer FLATKEY_API_KEY.
• Always pass --json for machine-readable output.
• Use --output / -o when the generated file path matters.
• Use flatkey image upload --file <path> for a temporary signed image URL.
• Use --image, --first-frame, or --last-frame to pass local images into video generation.
• Call flatkey models --json before choosing a model.
• Call flatkey audio voices --json before choosing a TTS voice_id.
• Use --dry-run to inspect request shape without spending credits.

Example dry run:

flatkey video generate \
  --prompt "fashion campaign hero shot" \
  --model seedance2 \
  --dry-run \
  --json

Routing

• Generation router: https://router.flatkey.ai
• Model registry: https://console.flatkey.ai/v1/available_models
• Voice registry: https://router.flatkey.ai/v1/voices

Override router only when developing or testing:

flatkey image generate --prompt "test" --base-url http://127.0.0.1:3000 --json

Release Channels

Primary release:

• npm package: @flatkey-ai/cli

Planned wrappers:

• Homebrew formula.
• Debian .deb package for apt-based install.
• Windows MSI package.

Development

git clone https://github.com/flatkey-ai/flatkey-cli.git
cd flatkey-cli
npm install
npm test
node bin/flatkey.js --version

Links

• Website: flatkey.ai
• npm: @flatkey-ai/cli
• Issues: github.com/flatkey-ai/flatkey-cli/issues