@flatkey-ai/cli

v0.3.3

Published

20 hours ago

Flatkey media generation CLI for image, video, audio, credits, status, and models.

Downloads

457

0High
0Medium
0Low

antimoron

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
flatkey login

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

Recommended: sign in through the Flatkey console:

flatkey login

flatkey login opens a browser authorization page, waits for approval, then saves the CLI API key and account metadata in your local Flatkey config. After login, check the active auth state:

flatkey auth status
flatkey status --json

If your terminal cannot open a browser automatically, print the approval URL and open it yourself:

flatkey login --no-open

For staging or self-hosted console testing:

flatkey login --console-url https://console.flatkey.ai

To remove the saved API key:

flatkey logout

Alternative: use an environment variable:

export FLATKEY_API_KEY=<key>

Or save a manually created key 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

Copy Video

Recreate a local 5-15 second video using a generated Depth Anything V2 video reference:

flatkey video copy \
  --source input.mp4 \
  --frame-ratio 80 \
  --depth-resolution 480p \
  -o result.mp4

video copy preserves the source duration by default. The source and requested duration must be between 5 and 15 seconds. Depth processing uses a platform runtime downloaded by the CLI; runtime distribution is configured through FLATKEY_VIDEO_RUNTIME_BASE_URL until the Flatkey runtime release channel is published. The generated depth video is uploaded as the primary motion reference. If the selected upstream model cannot fetch video references, the CLI explicitly falls back to three depth keyframes and reports that mode in JSON output as depth-keyframes-fallback.

Video ratios: 16:9, 9:16, 4:3, 3:4, 21:9, 1:1, adaptive. 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

Seedance 2.5 accepts reference images and videos as ordered content inputs:

flatkey video generate \
  --model seedance-2-5-pro \
  --prompt "保持人物、服装和镜头运动一致" \
  --image-url https://example.com/character.png \
  --video-url https://example.com/motion.mp4 \
  --ratio adaptive \
  -o result.mp4

For Seedance 2.5, the CLI allows up to 30 reference images and 10 reference videos in one request. Local files are uploaded before generation and all inputs keep their command-line order. Reference videos can be .mp4 or .mov.

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