generate2dmedia

生成 2D 媒体

路由层。它负责生成原始媒体；所属技能会先规划素材，再在生成后进行检查。

适用场景

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

不适用场景

• 规划、键控、注册或打包： generate2dsprite、video2dsprite、generate2dmap。
• 用户要求绘制的代码生成艺术： codeart2d。

路由顺序（所有者于 2026-10-06 决定）

1. API：按以下顺序使用已配置密钥的所有提供商（用户的 providers.order 优先）。图像：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）。已配置的密钥即表示所有者同意使用，无需逐次询问。
2. 本地：优先使用你自己的图像工具（如果有，例如 Codex image_gen、Grok 原生工具）；否则使用用户已登录的 CLI：先使用 Codex（本地 CLI）image_gen 并附上参考图，再使用 Grok（本地 CLI）进行单次图像生成或编辑；视频则在 ACP 模式下使用 Grok（本地 CLI）。已安装的 CLI 按原样使用；首次成功运行会记录已验证凭据。
3. codeart2d：仅当用户明确要求绘制代码生成艺术，或 route_media.py 输出 no-route（退出码 3）时使用。

始终注明实际使用的路由（“OpenAI API”、“Google Gemini API”、“xAI API”、“BytePlus ModelArk API”、“fal.ai API”、“Codex (local CLI)”、“Grok (local CLI)”）。详情请参阅：route-media.md。

能力检查（每个会话运行一次）

运行 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 密钥（是或否，绝不显示密钥）、各 CLI 的本地就绪状态以及解析后的顺序（routeOrder）。如果 encoding.stdout 失败，请设置 PYTHONUTF8=1。

生成（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（不会使用密钥、发送任何内容或写入任何内容）

成功时会打印一行 ASCII JSON 并以状态码 0 退出：{"status":"ok","route":"api:openai","artifact":"<out-dir>/generated.png","sha256":...,"estimateUsd":...}，此外还会包含 model、job；对于视频，还会包含 lastFrameUsed、durationRequested 和 durationUsed（时长会取整为模型支持渲染的最接近时长；Grok（本地 CLI）渲染时长为 6 或 10 秒，且不会固定最后一帧）；如果为了适配不支持 1:1 的模型而将帧填充为 16:9，还会包含 crop。所有片段发布时均不含音频。没有可用路由时，会打印 {"status":"no-route","fallback":"codeart2d"} 并以状态码 3 退出。失败时会打印一行 error: <route>: <code>: <message> 并以状态码 1 退出。如果某条路由的账户无法处理请求（余额不足、没有访问权限或未登录），请求会转交给下一条路由；如果是审核拒绝等情况，则会停止。请自行将提示词写入 UTF-8 文件；本地路由会从提示词中读取尺寸和所有指令。

密钥

每个提供商只读取自己的密钥：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 密钥。

费用和账本

每次调用，无论付费还是本地调用，都会在 <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 ... 可关闭结果未知的记录。

底层工具

需求	命令
手动发起一次 API 请求（直到使用 --execute 前均为试运行）	使用 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（会调用一次配额）

宿主说明

• Codex： image_gen 是你自己的工具：如果未配置密钥，就使用它并采用生成结果（cli_media.py adopt）；脚本通过 route_media.py 调用 Codex（本地 CLI）。此技能在 Codex 中仅可显式调用。
• Claude Code： 没有媒体工具；route_media.py 可调用 API 或本地 CLI。<skill-dir> 是 ${CLAUDE_SKILL_DIR}；使用 Read 查看结果。
• Grok： 其原生媒体工具是你自己的工具；同一个 grok 可执行文件也是供其他宿主使用的「Grok（本地 CLI）」路由。Agent 配置：agent-profiles/README.md。

命令和输出

从用户的项目根目录运行每个工具，每条命令占一行：python "<skill-dir>/scripts/<tool>.py" ...。输出会写入项目内新建的 --out-dir。结果是原始媒体：交由负责身份、尺寸、Alpha、动态效果和接缝检查的技能处理。保留提示词、输入哈希、任务 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。