菜单
Generate images, videos, audio, and text through the Flatkey CLI with unified credit balance and agent-friendly JSON output.
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/Aradotso/devtools-skills --skill flatkey-cli-media-generation命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
基于 SOC 职业分类
正在显示 SKILL.md
| name | flatkey-cli-media-generation |
| description | Generate images, videos, audio, and text through the Flatkey CLI with unified credit balance and agent-friendly JSON output. |
| triggers | ["generate image with flatkey","create video using flatkey cli","use flatkey for audio generation","generate media with flatkey","flatkey text to speech","check flatkey credits and models","flatkey ai media generation","flatkey cli video from image"] |
Skill by ara.so — Devtools Skills collection.
Flatkey CLI is a terminal-first media generation tool for images, videos, audio, and text. It provides:
--output / -oflatkey models and flatkey audio voicesBuilt for media teams, AI agents, and programmatic generation workflows that need cost-effective batch testing without long queues.
npm install -g @flatkey-ai/cli
npx @flatkey-ai/cli --ai
flatkey --version
flatkey -v
export FLATKEY_API_KEY=<your-key>
flatkey onboard --api-key <your-key>
flatkey image generate --prompt "test" --api-key <your-key>
Get your API key from console.flatkey.ai/keys.
flatkey image generate \
--prompt "magazine cover, reflective typography, studio lighting" \
--model gpt-image-2 \
-o cover.png
flatkey image generate \
--prompt "minimalist product shot, white background" \
--model nano-banana-pro-preview \
--json \
-o product.png
JSON output includes:
media_url: temporary signed URLlocal_path: saved file path (if -o used)cost: credits spentmodel: model used# Get temporary signed URL for local image
flatkey image upload --file ./reference.png --json
Returns:
{
"url": "https://temporary-media.flatkey.ai/...",
"expires_in_seconds": 3600
}
flatkey video generate \
--prompt "8 second cinematic product reveal, glossy black background" \
--model seedance2 \
--ratio 16:9 \
--resolution 720p \
-o launch.mp4
# Upload image first, then use in video
flatkey video generate \
--model Seedance2.0-pro \
--prompt "a sleepy kitten, soft window light" \
--image ./reference.png \
-o kitten.mp4 \
--json
flatkey video generate \
--model veo-3 \
--prompt "smooth camera transition" \
--first-frame ./start.png \
--last-frame ./end.png \
--ratio 16:9 \
--resolution 1080p \
-o transition.mp4
Ratios: 16:9, 9:16, 4:3, 3:4, 21:9, 1:1
Resolutions: 480p, 720p, 1080p
Models: seedance2, veo-3, veo-3-fast, Seedance2.0-pro
flatkey audio generate \
--prompt "Hello, this is a test of the Flatkey speech API." \
--voice-id EXAVITQu4vr4xnSDxMaL \
--model eleven_multilingual_v2 \
--stability 0.5 \
--similarity-boost 0.75 \
--style 0 \
-o speech.mp3 \
--json
flatkey audio generate \
--prompt "你好，这是 Flatkey 网关的语音测试。" \
--voice-id EXAVITQu4vr4xnSDxMaL \
--model eleven_multilingual_v2 \
-o mandarin.mp3
flatkey audio voices --json
Returns array of voices with:
voice_id: ID to use in generationname: voice namelabels: metadata (gender, age, accent, etc.)flatkey audio sfx \
--prompt "glass shattering on the floor" \
--duration 3 \
-o shatter.mp3 \
--json
flatkey audio music \
--prompt "calm ambient piano, sad mood" \
--music-length-ms 10000 \
-o background.mp3 \
--json
flatkey text generate \
--prompt "write 5 sharp headlines for a creator tool launch" \
--model gpt-5.5 \
-o headlines.txt \
--json
gpt-5.5Check live models:
flatkey models --type text --json
flatkey models --json
flatkey models --type image --json
flatkey models --type video --json
flatkey models --type audio --json
flatkey models --type text --json
flatkey credits --json
flatkey status --json
Use flatkey help --ai to get agent-specific guidance:
flatkey help --ai
--json flag for machine-readable outputFLATKEY_API_KEY environment variable over inline keys--output / -o when file path mattersflatkey models --json before choosing a modelflatkey audio voices --json before choosing a voice--dry-run to validate requests without spending creditsflatkey image upload before using in videoflatkey video generate \
--prompt "fashion campaign hero shot" \
--model seedance2 \
--ratio 16:9 \
--dry-run \
--json
Returns request payload without executing generation.
#!/bin/bash
PROMPTS=(
"product shot, white background"
"lifestyle photo, natural light"
"close-up detail, macro lens"
)
for i in "${!PROMPTS[@]}"; do
flatkey image generate \
--prompt "${PROMPTS[$i]}" \
--model gpt-image-2 \
-o "output_$i.png" \
--json
done
#!/bin/bash
# Upload reference image
UPLOAD_RESULT=$(flatkey image upload --file ./ref.png --json)
IMAGE_URL=$(echo $UPLOAD_RESULT | jq -r '.url')
# Generate video using uploaded image
flatkey video generate \
--model seedance2 \
--prompt "cinematic zoom in" \
--image "$IMAGE_URL" \
-o output.mp4 \
--json
#!/bin/bash
# Get available voices
VOICES=$(flatkey audio voices --json | jq -r '.[].voice_id' | head -3)
TEXT="This is a test of multiple voice synthesis."
for VOICE in $VOICES; do
flatkey audio generate \
--prompt "$TEXT" \
--voice-id "$VOICE" \
--model eleven_multilingual_v2 \
-o "voice_${VOICE}.mp3" \
--json
done
#!/bin/bash
CREDITS=$(flatkey credits --json | jq -r '.balance')
if (( $(echo "$CREDITS < 100" | bc -l) )); then
echo "Low credits: $CREDITS"
exit 1
fi
flatkey video generate \
--prompt "test video" \
--model veo-3-fast \
-o test.mp4 \
--json
#!/bin/bash
# Get all video models
VIDEO_MODELS=$(flatkey models --type video --json | jq -r '.[].id')
echo "Available video models:"
echo "$VIDEO_MODELS"
# Use first available model
FIRST_MODEL=$(echo "$VIDEO_MODELS" | head -1)
flatkey video generate \
--prompt "test generation" \
--model "$FIRST_MODEL" \
-o test.mp4 \
--json
Success:
{
"media_url": "https://...",
"local_path": "./output.png",
"cost": 5.2,
"model": "gpt-image-2"
}
Error:
{
"error": "Insufficient credits",
"code": "INSUFFICIENT_CREDITS",
"details": {...}
}
| Error | Cause | Solution |
|---|---|---|
FLATKEY_API_KEY not found | No API key set | Set export FLATKEY_API_KEY=<key> |
Insufficient credits | Credit balance too low | Add credits at console.flatkey.ai |
Model not found | Invalid model ID | Run flatkey models --json |
Invalid voice_id | Voice doesn't exist | Run flatkey audio voices --json |
File upload failed | Local file not found | Check file path |
# Dry run to check request structure
flatkey image generate \
--prompt "test" \
--model gpt-image-2 \
--dry-run \
--json
# Check credits
flatkey credits --json
# Check model availability
flatkey models --type image --json
flatkey image generate \
--prompt "test" \
--base-url http://127.0.0.1:3000 \
--json
https://router.flatkey.aihttps://console.flatkey.ai/v1/available_modelshttps://router.flatkey.ai/v1/voices# Check installation
npm list -g @flatkey-ai/cli
# Reinstall
npm install -g @flatkey-ai/cli
# Use npx
npx @flatkey-ai/cli --version
Always use --json flag for agent workflows:
flatkey image generate --prompt "test" --json
This disables terminal animation and ensures clean stdout.
Check -o / --output path permissions:
# Ensure directory exists
mkdir -p ./outputs
flatkey image generate --prompt "test" -o ./outputs/test.png
Upload local image first:
# Wrong (local path)
flatkey video generate --image ./local.png --prompt "test"
# Correct (upload first)
UPLOAD=$(flatkey image upload --file ./local.png --json)
URL=$(echo $UPLOAD | jq -r '.url')
flatkey video generate --image "$URL" --prompt "test" --json
Always check live models before generation:
flatkey models --type video --json | jq -r '.[].id'
Model IDs can change. Use dynamic lookup in scripts.