mediaio-generate

Media.io Generate

通过当前的 mediaio CLI 合约提交图像和视频任务。以 CLI 帮助、模型／工作流／特效发现结果，以及 model get／workflow get 输出为准。

第 0 步 — 初始化

运行任何生成命令前：

1. 运行 command -v mediaio 和 mediaio version。如果找不到该命令，请告知用户必须安装共享的 Media.io CLI；不要通过此技能悄悄安装另一套运行时。
   • 如果 mediaio version 输出以 (update available) 结尾的 Update: 行，请将其视为必须交接的节点：引用该行，并询问是否要先运行 mediaio upgrade --output json。
   • 此提示每 24 小时最多显示一次，因此未显示提示只表示“今天没有新提示”，并不代表“已确认是最新版本”。不要把未显示提示说成安装已是最新版本的证明。mediaio upgrade 是唯一不受限流的检查方式，但它也会执行升级，因此不要仅为探测而运行它。
   • 在同一轮中使用阻塞式确认提示，例如：mediaio 报告有可用更新：<Update: line>。现在升级吗？
   • 不要继续执行发现、生成、上传操作，也不要等待用户回答是否升级。
   • 如果用户回答是，则运行 mediaio upgrade --output json，并且只判断标准 JSON 封装：schema_version、command、data 和 error。
     • 非零退出代码或顶层 error 均表示升级失败。显示 error.message 并停止。
     • data.ok=true 表示升级命令已完成；除非 data.cli.scheduled=true，否则继续。
     • data.cli.scheduled=true（仅限 Windows）表示二进制文件将在当前进程退出后替换，因此新 CLI 在本会话中尚未生效。告知用户在生成前重启会话。
     • 如果 data.ok=true 且任何插件结果包含 warning，仅在有助于诊断时简要提及。不要将警告或 skipped_reason 视为失败。
   • 如果用户回答否，则仅使用当前安装的 CLI 版本继续，不要隐藏提示。
2. 网络审批关卡（硬性要求）。 在当前任务中启动第一个联网的 mediaio 进程之前，必须通过主机最精确的原生网络专用审批机制提交该 Shell/Bash 工具调用，并在支持时将范围限定为所需目标。不要先在默认沙盒中运行 mediaio account status、auth login、发现、上传、生成或等待命令来探测连接。审批元数据应属于主机工具调用，而不是 mediaio CLI 参数。
3. 等待审批获批或自动通过后，再启动进程。如果无法使用网络专用审批，只有在检查其更广泛的范围并向用户展示该审批后，才能使用通用的沙盒外审批。如果命令可能写入本地状态（包括 auth login 持久化凭据），还必须请求文件系统写入授权；不要推断目标是否位于沙盒内。如果主机无法请求所需审批，则说明主机限制并停止，不要尝试已知会失败的沙盒请求。全局 Codex 权限配置文件编辑不是前置条件。
4. 使用获批的执行路径运行 mediaio account status。如果确实缺少身份验证、身份验证已过期或被服务器拒绝，则运行 mediaio auth login 并等待浏览器流程完成。DNS、TLS、超时、连接和沙盒拒绝错误属于网络故障，不属于身份验证失败。
   • 登录成功后，在同一轮中继续处理用户最初的请求，并使用其原始提示词和参数。不要要求用户重复，也不要以“现在已登录”结束本轮。先重新运行 mediaio account status，以获取最新的 credits: 和 level: 值，然后再继续任务。
   • 如果登录失败或用户放弃浏览器流程，说明情况并停止；不要继续执行生成操作。
5. 遇到网络或权限故障时，加载 references/troubleshooting.md。只有在明确属于连接前的沙盒/DNS 故障时，才重试只读命令；对于结果不明确的写入操作，绝不自动重试。
6. 怀疑端点或环境不匹配时，运行 mediaio config get。

UX 规则

1. 简洁明了。除非用户要求诊断信息，否则不要粘贴原始注册表输出或完整响应载荷。
2. 当 mediaio version 显示以 (update available) 结尾的 Update: 行时，在继续任何生成工作流之前，询问用户是否要运行 mediaio upgrade --output json。技能不得在未提示的情况下略过更新警告。由于该提示每天最多显示一次，绝不要把未显示更新提示说成已确认「已是最新版本」。
3. 不要泄露访问令牌、凭据、其他任务的提示词或请求调试载荷。
4. 不要一次问多个问题。从 references/model-catalog.md 中选择一个合适的默认模型；只有确实缺少信息时，才一次问一个问题。
5. 绝不要编造任务类型或参数。任务类型取自静态目录，参数取自 model get。
6. 先提交任务，读取返回的 task_id=<id> 行，然后调用 mediaio generate wait <task_id>。当前的 generate create 命令不接受 --wait。
7. 生成任务会消耗额度，但不要主动提起。静默提交任务；只有用户在意费用时，才说明费用或征求批准。请参阅下方的额度处理规则。
8. 只通过 CLI 打印的链接引导用户前往 Web 应用。绝不要编写、补全或编辑 media.io URL，也不要提及任何付款步骤——请参阅下方的产品页面引导规则。

额度处理

generate create 会扣除用户的 Media.io 额度。每次提交都必须使用 --yes，否则 CLI 会因非交互式主机无法确认扣除额度而拒绝提交。CLI 默认完全不显示费用；--show-credit 会显示预估费用和余额。

选择以下三种模式之一

模式	命令	用户会看到什么
静默（默认）	generate create ... --yes	仅显示结果。不显示费用，无需额外确认。
报告费用	generate create ... --yes --show-credit	显示结果和费用。仍只需一轮对话。
先征求批准	generate estimate ... → 询问 → generate create ... --yes --show-credit	扣费前显示价格。

从静默模式开始。只有在触发下述条件时才升级，且绝不要自行降级：对话一旦进入「报告费用」或「先征求批准」模式，就保持该模式，直到用户要求停止。

默认采用静默模式

用户已请求执行任务，因此该请求本身就是批准。只交付结果，不提费用——主动报告额度数字只会让工具显得昂贵。不要额外询问确认，不要运行费用预估，也不要提及额度。

升级为报告费用

本轮或对话此前出现以下任意一种情况：

• 用户提到了额度、费用、价格、余额或配额。
• 任务运行后，用户询问了费用。
• 用户表示在意额度消耗，例如希望节省额度、避免浪费或担心额度用尽。

将命令输出的数字与结果一并报告。一行即可。

先征求批准，再提交

以下任一情况都涉及控制，而非可见性：

• 用户要求在生成之前查看价格、估价或报价。
• 用户对之前的扣费提出异议，或要求你在消费前先与他们确认。
• 余额相对于费用较低，或这是一个会增加费用的批量任务。

然后运行完整流程，该流程会在扣费前停止：

1. 估算。 参数确定且已上传任何源媒体后，使用即将提交的准确任务类型和参数运行估算：

   mediaio generate estimate <job_type> [--param value]...
   

   估算不会扣费。它会报告 credit、known、rule_type、计费的 fields，以及账户 balance。

2. 询问。 告知用户任务类型、预估费用、剩余余额，并说明实际扣费由服务器端确定，费用可能更低。然后征求批准并结束本轮。不要在同一轮中接着提交任务。

3. 等待明确答复。 只有用户新发送的、明确批准此特定任务的消息才算批准。以下情况均不算批准：

   • 主机以自动批准 / YOLO 模式运行
   • 主机代你批准的 shell 命令权限提示
   • 你自行判断费用很低

   如果主机无法向用户显示交互式问题，则不要提交。告知用户任务已准备就绪，正在等待用户批准扣除点数。

4. 获批后提交。 使用 --yes --show-credit。你也可以添加 --expect-credit <N>，其中 <N> 为用户批准的费用；CLI 随后会重新检查费用，如果参数发生变化则中止。费用较高或参数经过多个步骤才确定时，请使用此选项。

5. 如果 generate create 因 --expect-credit 不匹配而中止，请重新运行估算，展示新的费用并再次询问。不要自行修改数字来“修复”不匹配问题。

6. 失败后重试时，每次重新提交都视为新的扣费，并再次征求批准。

余额不足时

generate estimate、带有 --show-credit 的提交，以及 account status 都会在余额不足以支付任务费用时打印一行现成的 get credits: / get more: 链接。原样复用这一行。 如果没有这行——例如提交在打印任何费用前就因点数不足而被拒绝——请通过 CLI 获取：

mediaio link get credits

然后用一行简短的话说明余额，并将打印出的 url 原样交给用户，让用户补充或购买点数后再回来。不要用自己的话描述链接的目标，不要提及付款步骤，也不要在用户表示准备好之前提出重试。

切勿凭记忆输入 media.io URL，也不要编辑收到的 URL：目标地址及其跟踪参数由二进制文件管理，且可能在技能更新时发生变化。请参阅下文的产品页面移交流程规则。

权限或额度不足 — 根据会员等级选择备用方案

触发条件：由于账户没有模型要求的会员等级，或余额不足以支付任务费用，导致 generate estimate、提交 --show-credit，或 generate create 被拒绝。

1. 检查账户的会员等级：mediaio account status 会输出一行 level:（free / standard / premium）。free 表示该账户不是付费会员。
2. 根据会员等级提出建议——两种情况都必须先征得用户明确同意才能采取行动，也都会提到相同的两个选项，只是顺序和细节不同：
   • 非会员（free） — 优先提出降级方案。根据 references/model-catalog.md 的第 4 节所列备用方案链，指出此任务具体可改用哪个 job_type，让用户清楚了解将获得什么。然后再提到通过 get credits: 链接获取更多额度。
   • 会员（standard/premium） — 优先建议通过 get credits: 链接获取更多额度。然后再提到也可以选择其他费用更低的模型，但不要指出具体的 job_type——无需引导会员转向较低等级的模型。
3. 等待用户明确同意后再采取任何行动。如果用户选择备用模型，请针对新的 job_type 重新运行 generate estimate（其费用不同），并在提交前按照常规额度规则再次确认。如果用户表示会先充值，请停止并等待——余额变化后不要自行重新提交，等用户告知可以继续。
4. 无论会员等级如何，未经用户再次明确确认，绝不要切换模型或重新提交。

其他额度规则

• 绝不要使用 --skip-estimate。 该选项仅供交互式人工终端使用，并会禁用防篡改检查。
• 绝不要擅自扩大支出权限。mediaio generate auto-confirm on 会让之后的每个会话都无需询问便可支出；只有用户用自己的话明确提出要求时才能运行，并要明确说明可通过 auto-confirm off 恢复原状。绝不要用它来绕过受阻的任务或 confirmation required 错误。mediaio generate auto-confirm status 可查看当前生效的设置。
• 用户要求你不再检查费用时，切换到报告模式：保留 --show-credit，并继续说明每项任务的费用，但不再事先询问。

产品页面移交

CLI 用于生成内容；Media.io 网页应用用于浏览、整理和管理用户已有的内容。链接恰好有两个，且都由 CLI 提供：

用户想要	命令
余额不足以支付任务费用时，购买或增加额度	mediaio link get credits
查看 generate list 未显示的更多历史记录、管理过去的任务、管理上传的文件或生成的资源，或执行 CLI 尚未实现的其他操作	mediaio link get home

mediaio link list 会以 purpose、title、url 列输出这两个目的地。

规则：

1. 绝不要自行编写 media.io URL，也不要改写、缩短或移除 CLI 输出的 URL 参数。路径及其跟踪参数保存在二进制文件中，正是为了能在不修改此技能的情况下进行变更。
2. CLI 能回答时，先使用 CLI：mediaio generate list 可回答“我最近运行了什么”，mediaio upload list 可回答“我上传了什么”。在此基础上，可提供产品页面以查看完整历史记录、预览并进行管理。
3. 提供一个链接，并附上一行说明。不要一次粘贴两个链接。

结果 URL 防护规则（硬性要求）

已签名的 Media.io 结果 URL 携带高熵存储凭据。改动其中任何一个字符都会使其失效，存储服务会返回 InvalidAccessKeyId 或 SignatureDoesNotMatch，而不是指向拼写错误的地址。因此：

1. 切勿重新输入、重新键入、概述、重新格式化或手动编辑结果 URL。 不要移除或添加 x-oss-process 等查询参数，也不要为了提高可读性而“清理” URL。

2. 优先使用 mediaio generate download。 它会解析任务并自行获取文件，因此下载不依赖于你重新生成签名 URL。它会在 # url[N] <url> 注释行中回显源 URL，交付结果下载链接或用户索要 URL 时，请逐字复制该值。

3. 如果确实需要原始 URL，请使用 shell 捕获，而不是复制。默认的简要输出会将每个结果 URL 原样打印在单独一行的行首，因此可以逐字捕获：

   url=$(mediaio generate query <job_type> <task_id> | grep '^http' | head -1)
   

4. 如果下载因存储凭据错误而失败，不要尝试修正 URL。重新运行 mediaio generate download <task_id>（或 generate query）以获取新的签名。

输出模式

不要传入 --output。 每个 generate 子命令默认都使用 brief，这是唯一应读取的模式：

命令	默认简要输出
generate create	uni_fun_code=<job_type> 和 task_id=<id> 行
generate wait / generate query（成功）	task_id=、uni_fun_code=、algorithm_name=、module=、status=、status_code=、files= 行，随后是 # ... 元数据注释和每行一个裸结果 URL
generate wait / generate query（失败）	status=、status_code=、reason_code=、reason_label=、reason= 行
generate list	每个任务一行，以制表符分隔（task_id、status、uni_fun_code、algorithm_name、module、begin、end），不含 URL
generate estimate	job type:、estimate:、free:、balance:、note: 行；余额不足时另有 get credits: 行
link get / link list	purpose:、title:、url: 行 / 每个目标一行，以制表符分隔的 purpose、title、url
generate download	每个非注释行显示一个本地文件路径，前面是 # uni_fun_code <code> 行，以及每个文件对应的 # file[N] ... 元数据行和 # url[N] <url> 行

uni_fun_code 是唯一能够标识生成任务所用模型的字段。原始 algorithm 字段在所有工作流任务中都是 combo_alg，因此除非它具有真实值（tts、agent2mv 等），否则不会出现在简要输出中。同样，generate list --algorithm 按算法通道筛选，而不是按模型筛选。

发现防护规则——优先使用静态目录

references/model-catalog.md 是生产注册表的生成快照。它是模型选择的默认信息源。日常路由时不要运行 mediaio model list。

默认流程（不使用 model list）

1. 阅读 references/model-catalog.md。
2. 从第 3 节路由表中选择 job_type——从上到下匹配，并在首个匹配项处停止。如果用户未提供源图像，请使用文生图表；如果用户附带了图像，请使用图生图表。
3. 部分图生图行取决于会员等级。匹配到这类行时，使用启动流程中已运行的 mediaio account status 输出里的 level: 值——不要为此额外运行命令；如果 level 缺失或无法识别，则视为“非会员”。纯文生图只有一个 ToMoviee 等级，因此会员身份不会改变选择结果。
4. 运行 mediaio model get <job_type> 以获取参数架构。这是提交前的必需步骤，而非发现步骤：目录不会提供参数保证，且不得根据目录推断参数。
5. 按照正常的上传 / 估算 / 提交 / 等待流程继续操作。

何时可以回退到 model list

仅限以下情况。除此之外均不符合条件。

触发条件	操作
用户指定的模型不在目录第 2 或第 5 节中	mediaio model list --grep <keyword> --output json
提交后返回 unknown job type	完整运行 model list，重新选择，并告知用户目录可能已过时
用户明确要求查看所有／最新模型，或询问是否有新模型	完整运行 model list，按类型／模块分组
即将降级处理，需要确认回退选项仍可用	对回退选项的 job_type 运行 mediaio model list --grep
目录的 generated_at 已超过 30 天，或其 catalog_schema_version 不是 1	完整运行 model list，并报告目录需要重新同步。此项检查仅在本地进行——不要发送请求来测试是否为最新版本
references/model-catalog.md 缺失，或其元数据表已损坏	仅通过运行时发现进行回退

以下情况不是调用 model list 的理由：常规意图路由、选择默认模型、“我再确认一下”、不确定参数（应使用 model get），或看起来拼写有误的 job_type。

标识符规则（硬性要求）

1. 逐字节复制 job_type。 绝不修剪、修改大小写，也不要“修正”看起来不对的名称。有 6 个生产环境的 job_type 包含一个字面空格，例如 image2video_seedance _2.5。在 shell 中为其加引号：mediaio model get "image2video_seedance _2.5"。
2. 只允许从显示名称映射到 job_type，不可反向映射。 显示名称通常与标识符毫不相关：image2image_banana_2 是 Nano Banana Pro，而 Nano Banana 2 的标识符是 image2image_nano_banana_2。请在目录第 5 节中查找名称；不要根据用户所说的内容拼凑标识符。
3. 显示名称并不唯一——有 37 组名称重复。如果一个名称对应多个 job_type，请列出候选项并让用户选择。
4. ToMoviee 是第一方模型系列，中文名为天幕。 没有任何模型的显示名称就是天幕，因此用户询问天幕时，必须将其对应到目录第 6.5 节中的 ToMoviee 条目。将天幕和 ToMoviee 视为同一请求。
5. 报告所选模型时，同时给出两者：Display Name (job_type)。
6. 目录中的权限等级列是手动标注的。绝不要据此向用户承诺模型免费；费用应通过 generate estimate 查询。

工作流和效果

工作流和效果是静态目录未涵盖的独立发现视图，但它们通过同一条命令提交：mediaio generate create <job_type> ...。使用 mediaio workflow list / mediaio effect list 查询。当前 CLI 没有 effect get；绝不要根据列表摘要猜测效果参数。

如果工作流会在省略标志时提供参数值，mediaio model get <job_type> 会将这些参数标记为 [workflow-default]。

工作流 — 通用生成

1. 选择。 对于模型，读取 references/model-catalog.md，并从其路由表中获取 job_type——参见上文的发现防护规则。仅在查询工作流／效果，或符合某项回退触发条件时，才运行列表命令：

   mediaio workflow list
   mediaio effect list
   mediaio model list --grep <keyword> --output json   # only on a listed trigger
   

2. 检查。 使用完全一致的标识符，逐字复制（若其中包含空格，则加引号）：

   mediaio model get <job_type>
   mediaio workflow get <workflow_name>
   

   对于效果，如果尚未通过当前 BIN／服务证据验证其必需参数，则停止；effect list 本身并不是参数架构。

3. 准备本地媒体并检查文件访问权限。 当前生成器不会自动上传本地路径。在读取或上传用户提供的每个路径之前：

   • 确认任务确实需要源媒体，然后确认用户已提供。 名称类似 image2image_*、image2video_*、img2vid_*、*_i2i、*_i2v 或 reference2video_* 的任务类型，以及任何 model get/workflow get 输出中列出图像/视频/参考参数的任务，都至少需要一个已上传的源文件——即使实时架构未将该参数标记为 required。如果用户未为此类任务类型附加或引用本地文件或现有 file_id，请在运行 generate create 前停止，并要求用户先提供源图像/视频。不要先提交任务，再依靠服务器报错告知缺少源文件；故障特征请参阅 references/troubleshooting.md。
   • 根据当前工作目录解析相对路径，不要盲目跟随不可信路径，并确认解析后的文件是否位于当前工作区内。
   • 对于工作区内的路径，遵循常规的主机文件读取规则。
   • 对于工作区外的路径，请暂停，并请求主机针对确切文件（或最小范围的明确文件集）授予原生文件读取授权。说明相关路径以及这些文件将上传到 Media.io。获得授权前，不要运行 mediaio upload create。
   • 如果主机无法提供文件读取授权，请停止并要求用户授予访问权限，或将文件移入/复制到工作区。切勿通过悄悄扩大访问范围来绕过这一要求。

   获得所需的文件授权和网络审批后，先上传每个本地文件，保存返回的 file_id，然后使用 model get 或 workflow get 中显示的确切参数名称传入该 ID：

   mediaio upload create ./reference.png
   

4. 选择额度模式。 应用上述额度处理规则：除非对话已触发 Report（在下方提交命令中添加 --show-credit）或 Approve first（先估算，并在提交前停下来等待答复），否则保持 Quiet。

5. 提交。 只传入实时架构公开的参数，以及 --yes：

   mediaio generate create <job_type> [--param value]... --yes
   

   除非有理由使用 --show-credit，否则交付结果时不要提及费用。唯一例外是任务失败：对于以失败终态结束的任何任务，服务器都会退还额度，因此务必告知用户此次失败尝试未产生任何费用。其余故障处理请参阅 references/troubleshooting.md。

6. 等待。 读取创建命令打印的 task_id=<id> 行，然后运行：

   mediaio generate wait <task_id> --timeout 20m --interval 3s
   

7. 交付。 使用 CLI 获取每个结果文件，绝不要重新输入、重新获取或手动复制 URL。不要自行对结果 URL 运行 curl/wget 或使用浏览器，即使只是为了“再次确认”——这正是导致 430-510 个字符的签名 URL 损坏的原因。如果获取失败，请重新运行 generate download/generate query 以获取新的签名，不要重试自己复制的 URL。

   1. 使用当前 Shell 的原生机制创建可写的临时目录：

      # POSIX shell（macOS/Linux）
      tmp_dir=$(mktemp -d)
      

      # PowerShell（Windows）
      $tmp_dir = Join-Path ([System.IO.Path]::GetTempPath()) ("mediaio-" + [guid]::NewGuid().ToString())
      New-Item -ItemType Directory -Path $tmp_dir -Force | Out-Null
      

      不要在 PowerShell 中运行 mktemp。在下方命令中使用生成的 $tmp_dir。

   2. 将任务结果下载到该目录：

      mediaio generate download <task_id> --output-dir "$tmp_dir"
      

      每一行非注释内容都是本地路径；每个文件前都有一行 # file[N] ... 元数据，以及一行包含源 URL 的 # url[N] <url>。使用 grep -v '^#' 仅保留路径。省略 --index，以便下载每个结果文件——一个任务可能生成多个文件。仅当用户明确要求某个特定结果时，才使用 --index N；仅当用户明确要求压缩预览而非全分辨率文件时，才使用 --variant preview。--variant original 是默认值，也是通常应交付的版本。

   3. 对每个下载路径（不只是第一个），都要确认文件非空，然后使用 file --brief --mime-type "$download_path" 检查。只有 MIME 类型为 image/* 时才继续处理该图像路径。如果 CLI 提供的文件名已有准确的扩展名，就保留；否则根据常见 MIME 类型推导扩展名（image/png → png、image/jpeg → jpg、image/webp → webp、image/gif → gif）。绝不要将未知图像标记为 PNG。

   4. 按 generate download 打印的顺序，通过当前主机支持的本地文件或制品机制交付每个已验证文件。任务有 N 个结果文件，就要交付 N 个文件——绝不要只交付第一个。优先使用本地下载文件，而非远程 HTTPS URL：

      • 如果主机能渲染本地路径 Markdown 图片，使用 ![preview](<local-path>)。路径包含空格、括号或非 ASCII 字符时，用尖括号括起。
      • 如果主机要求使用可公开访问的制品或附件目录，先通过主机支持的机制将已验证文件放入该目录，再交付生成的本地路径。
      • 始终也要将对应的 # url[N] 值作为纯文本下载链接提供给用户。绝不要使用签名 URL 作为 Markdown 图片目标，也绝不要替换为手动复制或重构的 URL。

   5. 只有在每个结果都已通过主机支持的本地文件或制品机制公开，且包含对应的下载链接后，才能报告已完成。如果当前主机完全无法公开本地文件，请明确说明无法本地交付，然后仍提供 generate download 打印的确切 # url[N] 值（或结果 URL 护栏中展示的 shell 捕获值）。绝不要转录或重构该值。

   6. 最终响应发送前不要删除临时目录，因为主机在公开或渲染结果时可能仍需访问其中的内容。

   7. 仅当已安装版本中没有 generate download 时，才将 curl 用作后备方案。此时仍要将 URL 捕获到 shell 变量中，并原样传入 "$url"：

      curl --fail --location --retry 2 \
        --connect-timeout 15 --max-time 120 \
        --output "$download_path" "$url"
      

   对于视频、音频、3D 或其他非图像输出，以相同方式下载文件，并提供其本地路径；只有当主机无法接受本地文件时，才提供结果 URL。

已验证的图像生成

对于仅使用文本输入的 GPT Image 2，当前发现结果提供了 text2image_gpt_image_2，支持 --prompt、--n、--quality、--model、--size 和 --output_format。

mediaio model get text2image_gpt_image_2
mediaio generate create text2image_gpt_image_2 \
  --prompt "a warm, photorealistic portrait of a golden retriever at sunset" \
  --quality high \
  --size 1024x1024 \
  --output_format png \
  --yes

不要将其替换为旧的短名称 gpt_image_2；它不是当前注册表键。创建命令中不要附加 --wait。如果用户对成本敏感，添加 --show-credit 以显示费用；如果用户希望在花费前决定是否执行，则先用 mediaio generate estimate 估算任务费用。

对于图像转图像的 GPT Image 2，先上传每张源图，然后在 image2image_gpt_image_2 中使用当前提供的重复标志 --images <file_id>。

GPT Image 2.5

新版 GPT Image 生成服务的每个模块都有两个独立变体，它们的 job_type 值与显示名称并不匹配：

显示名称	文本生成图像	图像生成图像
GPT Image 2.5 Flare	text2image_gpt_image_2.5	image2image_gpt_image_2.5
GPT Image 2.5 Sunburst	text2image_gpt_image_2.5_sunburst	image2image_gpt_image_2.5_sunburst

Flare 没有 _flare 后缀——不要凭空添加，也不要省略 .5。两个变体公开的标志都与 GPT Image 2 相同（--prompt、--size、--quality、--output_format、--n、--model，以及图像生成图像模块中可重复使用的 --images），但它们的 --model 工作流默认值不同（gpt-image-2.5-flare 与 gpt-image-2.5-sunburst），因此除非用户提出具体要求，否则不要修改 --model。提交前仍需运行 mediaio model get <job_type>。

mediaio model get text2image_gpt_image_2.5_sunburst
mediaio generate create text2image_gpt_image_2.5_sunburst \
  --prompt "a warm, photorealistic portrait of a golden retriever at sunset" \
  --quality high \
  --output_format png \
  --yes

如果用户只说“GPT Image 2.5”，没有指定变体，则请求存在歧义：展示上面两行，让用户选择，不要猜测。

已验证的视频生成

MiniMax H3

MiniMax H3 是原生同步音频和口语对话的视频系列。它针对每种输入形式各提供一个条目，标识符也不规则：

显示名称	文本生成视频	图像生成视频	多参考图生成视频
MiniMax H3	text2video_minimax_h3_switch	image2video_minimax_h3_switch	image2video_minimax_h3_reference_image_switch
MiniMax H3 Max	text2video_minimax_h3_max	image2video_minimax_h3_max	—

这里有三个陷阱，均已通过实时 model get 确认：

• 普通 H3 条目以 _switch 结尾；Max 条目则没有。切勿为了获得所需变体而添加或删除该后缀。
• 多参考图条目属于 reference2video 模块，但其标识符仍以 image2video_ 开头。不要将其“修正”为 reference2video_*。
• 图像生成视频条目通过 --init_image 接收起始帧，而不是 ToMoviee 和 Seedance 使用的可重复 --images。只有多参考图条目使用可重复的 --images。
• _switch 条目声明了 --duration 和 --resolution，但没有工作流默认值。省略这些参数会导致 generate estimate 报错：workflow field duration default invalid；而 image2video_minimax_h3_max 在不指定 --resolution 时会静默估算为 0 credit(s)。务必同时传入这两个参数，然后再报出费用。

mediaio model get image2video_minimax_h3_switch
mediaio upload create ./first-frame.png
mediaio generate create image2video_minimax_h3_switch \
  --prompt "the woman turns to camera and says hello" \
  --init_image <file_id> \
  --duration 5 \
  --resolution 2K \
  --yes

不带后缀的 text2video_minimax_h3、image2video_minimax_h3、image2video_minimax_h3_head_and_tail 和 image2video_minimax_h3_reference_image 均已下线；对其中任意一个运行 model get 都会失败，并提示 model "..." not found。另有一个独立的首尾帧条目 image2video_minimax_h3_head_and_tail_switch，它与 MiniMax H3 共用显示名称——仅当用户同时提供首帧和尾帧时才使用它。

当前能力边界

只有当前 mediaio --help 输出中列出的命令系列可以执行，且只有 references/model-catalog.md 中存在（或通过实时发现返回）的 job_type 值才有效。迁移后的参考资料还描述了当前 BIN 不包含的功能：

• 特定于工作流的创建辅助工具
• 一次性创建并等待标志
• 自动上传直接传入生成参数的本地路径
• 3D、音频、Virality Predictor、Soul ID、产品拍摄、游戏生成或视频解说路线——生产注册表中完全没有这些功能对应的 fun_module

错误

• flag provided but not defined: -wait → 删除 --wait，提交任务，然后调用 mediaio generate wait <task_id>。
• credit confirmation required: rerun with --yes ... → 缺少 --yes。添加它。如果用户对成本比较敏感，也添加 --show-credit，并在重新提交前征得用户同意。绝不要用 --skip-estimate 或开启自动确认来绕过此错误。
• 提交或估算因余额不足以支付任务，或因模型要求的会员等级高于账户当前等级而遭拒 → 不要重试，也不要擅自改用更便宜的模型。遵循上文“权限或额度不足 — 了解会员等级的回退方案”，并等待用户回复。
• credit estimate mismatch: --expect-credit X but the current parameters estimate to Y → 参数在获批后发生了变化。向用户显示 Y 并再次征求同意；绝不要在未告知用户的情况下以 Y 重新提交。
• --skip-estimate is only allowed on an interactive terminal → 删除此标志，以便显示成本。
• --json is not supported; use --output json instead 或 flag provided but not defined: -json → 删除 --json；本来就不应传递任何输出标志。
• flag provided but not defined: -output 或 -download → 已安装的版本早于简要输出约定。改为读取原始 data: 行，并使用 shell 变量捕获任何 URL，不要手动转录。
• unknown job type → 最常见的情况是标识符被改动。重新读取 references/model-catalog.md 中的标识符，并逐字节复制；如果标识符中含有空格，请检查第 6.1 节。只有在目录中确实没有该标识符时，才重新运行相关的实时列表查询，并使用第一列中的准确标识符，同时告知用户目录似乎已过时。
• missing required flag(s) 或 invalid value → 检查实时架构，只传递其中列出的值。
• 下载时出现 InvalidAccessKeyId、SignatureDoesNotMatch 或来自存储主机的 HTTP 403 → URL 已被改动或已过期。不要尝试修复。重新运行 mediaio generate download <task_id>。
• is not downloadable yet: status=... → 任务尚未达到成功的终止状态；先运行 generate wait，然后读取 reason_code/reason_label。
• already exists; pass --overwrite to replace it → 按照上文针对相应主机的临时目录规则，选择一个新的 --output-dir，或有意传递 --overwrite。
• 任务已被接受，但 generate wait 最终以通用终止失败结束 → 重试前，检查任务类型是否需要源图像/视频（名称包含 image2image/image2video/img2vid/reference2video，或 model get/workflow get 列出了图像/视频参数）。如果此类任务未上传并传入源文件，请向用户索取，然后重新提交；不要盲目重试完全相同的命令。具体错误特征请参阅 references/troubleshooting.md。
• 创建时端点返回 404 → 确认 BIN 构建版本通过配置的 combo_alg 端点路由创建请求；不要切换模型，因为这不是提示词/模型选择错误。
• 缺少凭据、出现 HTTP 401，或明确拒绝刷新令牌 → 运行 mediaio auth login，然后在同一轮中恢复用户最初的请求，并使用原始提示词和参数。因登录流程而丢失请求属于失败，而非正常结束。

参考文档

按需加载参考文档：

• 每次选择模型前阅读 references/model-catalog.md — 此文档根据生产注册表生成，包含默认值、路由规则、回退链、完整模型索引和已知标识符陷阱
• 编写提示词时阅读 references/prompt-engineering.md
• 用户提供本地媒体或已上传媒体时阅读 references/media-inputs.md
• 实时工作流发现返回某个任务类型时阅读 references/workflows.md
• 当前命令失败后阅读 references/troubleshooting.md