SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场generate2dmedia

generate2dmedia

设计与创作

查看项目

更新于 10-15 11:36

技能介绍

用途

generate2dmedia 是 Forge 技能集的“路由层”（art-route layer），只负责生成原始媒体素材：图像、参考图编辑或图生视频片段。它不负责规划、密钥管理、注册或打包，这些由上层技能（generate2dsprite、video2dsprite、generate2dmap）在生成前规划和生成后校验。

主要能力

  • 通过 route_media.py 一条命令生成图像或图生视频片段。
  • 支持多种 API 路由：OpenAI（gpt-image-2.5-sunburst）、Google Gemini（gemini-3.1-flash-image，--tier hero 使用 gemini-3-pro-image）、xAI（grok-imagine-image-2.0）、BytePlus ModelArk（Seedream 5.0）、fal.ai（参考图编辑）。
  • 视频路由：xAI（grok-imagine-video-1.5，--tier draft 使用 1.5 Lite）、BytePlus ModelArk（Seedance 2.0）、fal.ai（Kling v3、Veo 3.1、Luma、MiniMax、Wan、Vidu、LTX）。
  • 本地路由：自有图像工具（Codex image_gen、Grok 原生工具），或用户已登录的 CLI：Codex（本地 CLI）image_gen（可附参考图）、Grok（本地 CLI）一次性图像或编辑；视频使用 Grok（本地 CLI）ACP 模式。
  • 支持 --dry-run 先查看计划与估算，不消耗密钥、不发送、不写入。
  • 支持 --route、--model、--tier、--provider-option 等参数指定路由或模型。
  • 每次调用（付费或本地）记录到 <project>/.forge/ledger.jsonl，可用 media_ledger.py summary 查看花费。
  • 支持预算与调用次数限制：--budget-usd、--max-calls、FORGE_MAX_PAID_REQUESTS、FORGE_SESSION_IMAGES / FORGE_SESSION_VIDEOS。

使用方式

  1. 能力检查（每会话一次）：运行 python "<skill-dir>/scripts/forge_doctor.py" --host-tools <tools> --save <output>/doctor.json，其中 <tools> 列出自身工具列表中的媒体工具（image_gen、image_edit、image_to_video）或 none。ROUTES 块显示已配置的 API 密钥（只显示 yes/no，不显示密钥）、各 CLI 的本地就绪状态及解析后的顺序（routeOrder）。若 encoding.stdout 失败，设置 PYTHONUTF8=1。

  2. 生成（route_media.py）：

    • 查看将运行哪条路由：python "<skill-dir>/scripts/route_media.py" resolve --kind image（或 video；--references N）
    • 生成一张图像（静态或编辑）：python "<skill-dir>/scripts/route_media.py" image --prompt-file <txt> --reference <png> --size 1024x1024 --out-dir <new>（--reference 可重复，按提示词中命名的顺序）
    • 将已批准的静态图动画化：python "<skill-dir>/scripts/route_media.py" video --prompt-file <txt> --reference <still.png> --last-frame <still.png> --duration 6 --resolution 720p --out-dir <new>
    • 指定路由或模型：添加 --route api, local, openai, gemini, xai, byteplus, fal, fal:<endpoint-id>, codex-cli, grok-cli 或 grok-acp；--model <id>，--tier draft 或 hero，--provider-option [PROVIDER:]KEY=VALUE
    • 先看计划与估算：添加 --dry-run

  3. 成功时打印一行 ASCII JSON 并退出 0：{"status":"ok","route":"api:openai","artifact":"<out-dir>/generated.png","sha256":...,"estimateUsd":...}，另含 model、job，视频还含 lastFrameUsed、durationRequested、durationUsed（长度会吸附到模型可渲染的最近值；Grok 本地 CLI 渲染 6 或 10 秒且从不固定末帧）以及 crop（当帧被填充到 16:9 以适配不支持 1:1 的模型时）。每个片段发布时无音频。无路由时打印 {"status":"no-route","fallback":"codeart2d"} 并退出 3。失败时打印一行 error: <route>: <code>: <message> 并退出 1。账户无法服务请求（无额度、无权限、未登录）时传递给下一条路由；拒绝（如审核）则停止。提示词需自行写入 UTF-8 文件；本地路由从提示词中获取尺寸和所有指令。

  4. 密钥：各提供商只读取自己的密钥：OPENAI_API_KEY、GOOGLE_API_KEY 或 GEMINI_API_KEY（GOOGLE_API_KEY 优先）、XAI_API_KEY、ARK_API_KEY（BytePlus ModelArk）、FAL_KEY（fal.ai），来自环境变量或用户配置文件，绝不来自项目。Windows 为 %APPDATA%\agent-sprite-forge\config.json，其他平台为 ~/.config/agent-sprite-forge/config.json（设置 $XDG_CONFIG_HOME 时使用该路径），格式如 {"OPENAI_API_KEY": "...", "FAL_KEY": "..."}，可选 "models" 和 "providers": {"order": [...]}。绝不打印、记录、提交或粘贴密钥，也不将密钥放入提示词。Codex 或 Grok 的登录不是 API 密钥。

  5. 花费与账本：每次调用（付费或本地）都是 <project>/.forge/ledger.jsonl 中的一行，含估算值（无已验证价格时 estimateUsd 为 null，应说明“价格未知”）。默认无上限；用户要求时可用 --budget-usd、--max-calls、FORGE_MAX_PAID_REQUESTS 和 FORGE_SESSION_IMAGES / FORGE_SESSION_VIDEOS 设置。python "<skill-dir>/scripts/media_ledger.py" summary 显示花费；media_ledger.py settle <id> --status ... 关闭未知结果。

  6. 更低层工具：

    • 手动发起一次 API 请求（--execute 前为 dry run）：generate_media.py image 或 video，带 --provider、--model、--prompt-file、--out-dir（见 api-usage.md）
    • 轮询或下载视频或 fal.ai 任务而不再次付费：generate_media.py resume --job <out>/job.json
    • 手动运行一次本地 CLI：cli_media.py image --route codex-cli --prompt-file <txt> --output-dir <new> --execute（见 cli-routes.md）
    • 本地运行超时或被中断：cli_media.py resume --run <id>，然后 --adopt（绝不重跑 CLI）
    • Codex 生成的图像不在项目中：cli_media.py adopt --codex-thread <thread-id> --output-dir <new>
    • 批量任务：generate_media.py batch 或 cli_media.py batch
    • 提前验证本地路由（可选）：forge_doctor.py --verify-route <route> --execute（消耗一次配额调用）

适用场景

  • 任何 Forge 技能（或其流水线脚本）需要生成图像、参考图编辑或图生视频片段时。
  • 每会话一次，查看哪些路由可用（forge_doctor.py）。
  • 用户要求配置 API 密钥、使用特定路由或询问花费时。

限制

  • 不用于规划、密钥管理、注册或打包：这些由 generate2dsprite、video2dsprite、generate2dmap 负责。
  • 不用于用户要求的代码绘制艺术：由 codeart2d 负责。
  • 结果只是原始媒体，需交给上层技能进行身份、尺寸、透明度、运动和接缝检查。
  • 需保留提示词、输入哈希、任务 ID 和结果哈希；分别报告请求的模型和返回的模型。
  • 提供商信息见 provider-survey.md（最后验证 2026-10-06，含关闭日期）；能力见 references/capabilities.json（python "<skill-dir>/scripts/media_providers.py" list）；价格见 references/prices.json；数据契约见 references/schemas/media.schema.json。
  • 主机说明：Codex 中 image_gen 是自有工具，无配置密钥时使用并采纳结果（cli_media.py adopt）；脚本通过 route_media.py 到达 Codex（本地 CLI）。此技能在 Codex 中为 explicit-only。Claude Code 无媒体工具，route_media.py 走 API 或本地 CLI；<skill-dir> 为 ${CLAUDE_SKILL_DIR}，用 Read 查看结果。Grok 的原生媒体工具是自有工具；同一 grok 可执行文件对其他主机是“Grok（本地 CLI）”路由。代理设置见 agent-profiles/README.md。
  • 所有工具从用户项目根目录以一行命令运行：python "<skill-dir>/scripts/<tool>.py" ...。输出到项目内新的 --out-dir。