ultimate-ai-media-generator-skill

Ultimate-AI-Media-Generator-Skill

概述

使用此技能可靠地调用 CyberBara API，创建图像、视频、音频和音乐生成任务，并通过考虑积分的流程返回最终媒体 URL。

对于中文文章或仓库推广标题图，除非用户要求使用其他图像模型，否则默认使用模型 nano-banana-2-lite。建议先生成不含文字的封面背景，再在本地添加最终的中文标题，确保发布的标题准确且清晰易读。

实现架构

运行时采用分层 Python 架构：

• scripts/cyberbara_api.py：仅作为轻量入口
• src/cyberbara_cli/cli.py：解析命令并进行命令路由
• src/cyberbara_cli/usecases/：编排流程（生成 + 轮询）
• src/cyberbara_cli/policies/：安全和策略规则（积分报价 + 正式确认）
• src/cyberbara_cli/gateways/：CyberBara API 原始客户端
• src/cyberbara_cli/config.py：API 密钥发现和本地持久化
• src/cyberbara_cli/constants.py：固定基础 URL 和共享常量

扩展功能时，请将业务规则放在 usecases/ 或 policies/ 中，而不是 scripts/ 中。

设置运行时输入

脚本使用固定的基础 URL：

https://cyberbara.com

API 密钥查找顺序：

1. --api-key
2. 环境变量 CYBERBARA_API_KEY
3. 本地缓存文件 ~/.config/cyberbara/api_key
4. 交互式提示（如果在终端中运行）

建议的一次性设置命令：

python3 scripts/cyberbara_api.py setup-api-key "<api-key>"

也可以从环境变量保存：

export CYBERBARA_API_KEY="<api-key>"
python3 scripts/cyberbara_api.py setup-api-key --from-env

如果缺少 API 密钥，脚本会立即提示输入，并说明如何获取：

https://cyberbara.com/settings/apikeys

通过 --api-key 或交互式提示提供 API 密钥时，密钥会保存到：

~/.config/cyberbara/api_key

后续运行会复用此缓存密钥，因此用户无需每次都提供密钥。

运行标准生成流程

1. 发现可用模型。
2. 如果任务场景需要本地媒体输入，则上传参考图像或视频。
3. 创建生成任务前，先估算所需积分。
4. 创建图像或视频生成任务，并等待最终输出。
5. 自动将生成的媒体保存到本地并打开。
6. 按需检查使用记录。

参考命令：

# 1) List video models
python3 scripts/cyberbara_api.py models --media-type video

# Also available: image, audio, and music models
python3 scripts/cyberbara_api.py models --media-type audio
python3 scripts/cyberbara_api.py models --media-type music

# 2) Upload local reference images
python3 scripts/cyberbara_api.py upload-images ./frame.png ./style.jpg

# Upload local reference videos
python3 scripts/cyberbara_api.py upload-videos ./clip.mp4

# 3) Estimate credits
python3 scripts/cyberbara_api.py quote --json '{
  "model":"sora-2",
  "media_type":"video",
  "scene":"text-to-video",
  "options":{"duration":"10"}
}'

# 4) Create a video task (default behavior: wait for success, save outputs to ./media_outputs, auto-open)
python3 scripts/cyberbara_api.py generate-video --json '{
  "model":"sora-2",
  "prompt":"A calm drone shot over snowy mountains at sunrise",
  "scene":"text-to-video",
  "options":{"duration":"10","resolution":"standard"}
}'

# 5) Existing task: wait + save/open outputs
python3 scripts/cyberbara_api.py wait --task-id <TASK_ID> --interval 5 --timeout 900

默认情况下，图像和视频生成需要确认：

# Single image request: script auto-quotes, then asks you to type CONFIRM
python3 scripts/cyberbara_api.py generate-image --json '{
  "model":"nano-banana-pro",
  "prompt":"A cinematic portrait under neon rain",
  "scene":"text-to-image",
  "options":{"resolution":"1k"}
}'

# Batch image requests (JSON array): script auto-quotes each request and prints total estimated credits
python3 scripts/cyberbara_api.py generate-image --file ./image-requests.json

image-requests.json 格式：

[
  {
    "model": "nano-banana-pro",
    "prompt": "A cinematic portrait under neon rain",
    "scene": "text-to-image",
    "options": { "resolution": "1k" }
  },
  {
    "model": "nano-banana-pro",
    "prompt": "A product still life with dramatic side light",
    "scene": "text-to-image",
    "options": { "resolution": "1k" }
  }
]

只有在获得用户明确批准后，才能使用 --yes：

python3 scripts/cyberbara_api.py generate-image --file ./image-requests.json --yes
python3 scripts/cyberbara_api.py generate-video --json '{
  "model":"sora-2",
  "prompt":"A calm drone shot over snowy mountains at sunrise",
  "scene":"text-to-video",
  "options":{"duration":"10","resolution":"standard"}
}' --yes

python3 scripts/cyberbara_api.py generate-audio --json '{
  "model":"suno-sound-v5-5",
  "prompt":"A short cinematic whoosh with soft digital sparkle",
  "scene":"text-to-audio",
  "options":{"loop":false}
}' --yes

python3 scripts/cyberbara_api.py generate-music --json '{
  "model":"suno-music-v5",
  "prompt":"Warm lo-fi study music with mellow keys",
  "scene":"text-to-music",
  "options":{"instrumental":true}
}' --yes

控制自动保存和打开行为：

# keep waiting but do not auto-open media
python3 scripts/cyberbara_api.py generate-image --file ./image-requests.json --yes --no-open

# custom output directory
python3 scripts/cyberbara_api.py generate-video --json '{...}' --yes --output-dir ./downloads

# submit only (no wait/save/open)
python3 scripts/cyberbara_api.py generate-video --json '{...}' --yes --async

使用脚本功能

scripts/cyberbara_api.py 支持：

• setup-api-key：将 API 密钥保存到本地缓存
• models：列出公开模型（--media-type image|video|audio|music 可选）
• upload-images：将本地图像文件上传到 /api/v1/uploads/images
• upload-videos：将本地视频文件上传到 /api/v1/uploads/videos
• quote：根据 JSON 请求正文估算积分成本
• generate-image：自动估算积分、计算批量请求的总成本、要求正式确认、创建任务、等待完成，然后保存并打开输出
• generate-video：自动估算积分、计算批量请求的总成本、要求正式确认、创建任务、等待完成，然后保存并打开输出
• generate-audio：自动估算积分、计算批量请求的总成本、要求正式确认、创建任务、等待完成，然后保存并打开输出
• generate-music：自动估算积分、计算批量请求的总成本、要求正式确认、创建任务、等待完成，然后保存并打开输出
• task：根据任务 ID 获取任务快照
• wait：轮询任务，直到其状态变为 success、failed 或 canceled，然后保存并打开输出
• balance 和 usage：查看积分
• raw：直接调用自定义端点

对于较长的负载，请使用 --file request.json，而不是 --json。

强制执行 API 负载规则

• 使用 API 密钥进行身份验证（Authorization: Bearer <key> 或 x-api-key）。
• 仅在 options.* 下发送公共请求字段。
• 优先显式指定 scene，避免推断歧义。
• 对于 image-to-image 和 image-to-video，包含 options.image_input。
• 对于 video-to-video，包含 options.video_input。
• 轮询 /api/v1/tasks/{taskId}，直到状态最终确定；只有 success 能确保获得输出 URL。
• 每次提交图像、视频、音频或音乐生成请求前，先获取报价并取得用户明确确认。
• 对于多个图像、视频、音频或音乐请求，在提交前计算并展示预估积分总额。
• 默认将输出文件保存到 media_outputs/，并自动打开，除非已禁用。

查阅详细模型选项

完整的模型列表和示例请参阅参考文件：

• references/cyberbara-api-reference.mdx

在大型参考文档中快速查找：

rg '^## |^### ' references/cyberbara-api-reference.mdx
rg 'kling-2.6|sora-2|veo-3.1|seedance' references/cyberbara-api-reference.mdx

处理常见故障

• invalid_api_key 或 api_key_required：验证密钥和请求头。
• insufficient_credits：先获取报价，或充值积分。
• invalid_scene 或 scene_not_supported：选择模型支持的场景。
• invalid_request：根据模型要求验证 prompt 和 options。
• UPLOAD_INVALID：检查并报告完整的 error.message 和 error.details；这些提供商上传验证错误会在创建任务 ID 之前发生。
• task_not_found：验证任务 ID 和环境域名。