提示词优化：H3 默认集成与 Qwen 手动改写

区分 H3 默认生成编排和 Qwen Image 手动改写，明确素材、采用、费用和失败恢复。

Qwen Image 2.1 手动改写

Qwen Image 2.1 使用同一 POST /media/prompt-optimizations 独立优化入口，由既有 Qwen3.8 按官方改写规则调用一次并返回正文。它为手动可选，不默认自动生成，不套用 H3 的结构化 JSON 或修复流程。

{
  "clientRequestId": "qwen-rewrite-001",
  "model": "qwen-image-2.1",
  "generationMode": "i2i",
  "originalPrompt": "将图1的人物放入图2的场景，保持人物特征。",
  "mediaSpec": {"outputSizeCode": "qwen21_standard_1376x768"},
  "referenceInputs": [
    {"role": "reference_image_1", "assetId": "<ASSET_1>"},
    {"role": "reference_image_2", "assetId": "<ASSET_2>"}
  ]
}

使用当前 Key 先上传参考图；请求头 Idempotency-Key 与 clientRequestId 相同。纯文字使用 generationMode: t2i 和空数组；单图或多图使用 i2i 和原序 reference_image_N。十张生成参考图合法，但优化模型有自己的上限，全部图片会按原序转交；上游拒绝时返回错误，不静默丢图或增加调用次数。

读取 optimization.optimizedPrompt，展示候选供用户编辑和采用；采用后将文本填入图片生成的 prompt，保留原 size，再以新的业务键提交生成。HTTP 结果仍是 JSON 封套，其中优化正文为普通文本；不要求模型正文输出 JSON。优化失败不自动生成，用户可选择保留原文。优化按 Qwen3.8 用量独立计费，后续生成另计费。

默认已包含在 H3 生成流程中

使用 Account API Key 调用 H3 的 POST /v1/media/generations 时，平台默认在同一个 Job 内先优化提示词，再生成视频。只需提交一次生成请求，无需先额外调用优化接口。 这适用于文生视频、首帧生视频、首尾帧生视频和全能参考四种模式。

用法	如何提交	是否调用优化
默认优化后生成	省略 `optimizePrompt`，或传 `true`	在生成 Job 内完成优化
直接使用确定的文本	生成请求顶层传 `"optimizePrompt": false`	不调用优化、不产生优化费用
单独优化，查看或编辑后生成	先调用独立优化接口；采用结果生成时传 `false`	独立优化一次，生成时不再优化

optimizePrompt 是生成请求的顶层参数，不放进 mediaSpec；只接受 JSON 布尔值。关闭优化不会关闭内容安全审核或视频生成计费。平台应用调用 H3 也支持默认优化及同样的关闭参数；应用开发者参见内部应用开发中的平台服务教程。个人创作及其他模型不自动套用这个默认规则。

默认调用示例：

{"model":"minimax-h3","generationMode":"t2v","prompt":"清晨海岸，镜头缓慢推进","resolutionTier":"544p","orientation":"landscape","seconds":5}

无需自动优化时，在同一正文添加 "optimizePrompt": false。完整的提交、查询和下载示例见 API Key 异步媒体调用。优化失败会终止任务，不回退原文继续生成；费用按实际优化调用结算。

平台负责保持参考素材的类型、顺序和编号。优化正文未逐一写出全部合法素材编号，不会仅因此判定失败或重复调用优化模型；实际素材缺失、引用不存在的编号、输出截断、超长以及安全审核错误仍按各自原因处理。不要把编号出现等同于模型完全理解了素材，复杂参考关系仍建议检查优化结果。

优化要求默认保留原提示词中对白的原文与语种；明确指定某句、某个角色或全局台词语种时，按对应范围忠实翻译。英文镜头描述不代表允许把中文台词改成英文。优化结果仍应核对原意，尤其是长对白与短视频时长互相冲突的情况。

需要单独优化时

独立优化适合先查看、编辑、采用或放弃候选的场景。POST /media/prompt-optimizations 只返回优化结果，不自动生成媒体；采用结果后再生成是另一个业务请求，使用独立幂等键。

先查询当前服务的能力与素材限制。automaticPromptOptimization 描述公开 H3 的自动编排是否启用；独立优化由 promptOptimization 声明。自动编排就绪不等于所有模型后端实时健康，能力不可用时须处理明确错误。

构造请求

{
  "clientRequestId":"your-optimization-business-id",
  "model":"<MODEL_ALIAS>",
  "generationMode":"t2v",
  "originalPrompt":"雨夜街道上的撑伞人物",
  "mediaSpec":{"resolutionTier":"768p","orientation":"landscape","seconds":5},
  "referenceInputs":[]
}

请求头 Idempotency-Key 必须等于 clientRequestId。图生、首尾帧和全能参考要附匹配的素材；优化接口的每个参考项只传 role 与 assetId，不要把生成请求的 mediaType 直接复制进去。

{"role":"reference_image","assetId":"<ASSET_ID>"}

音频参考按服务公开策略保留用途，不代表模型理解音频内容。有 H3 音频参考时须传 audioReferencePolicy: "preserve_without_understanding"。不要静默丢弃音频或其他素材。

优化时用于识图的图片会按原比例缩小至长边不超过 1024 像素，小图不放大、不裁切，透明区域以白底显示。视频生成仍使用原始素材；无需另行上传缩略图。细小文字或细节可能因缩小而不易辨认，关键要求应同时写在原提示词中。

确认再生成

优化成功读取 optimization.optimizedPrompt。
展示给用户，允许修改、采用或放弃；失败时保留原提示词。
用户确认后，将最终文本放到生成请求的 prompt；公开 H3 同时传 optimizePrompt: false，避免再优化一次。
使用另一个生成业务幂等键提交媒体请求，进入任务查询。

例如，独立优化后采用候选的 H3 生成请求为：

{"model":"<MODEL_ALIAS>","generationMode":"t2v","prompt":"人工采用并确认的最终正文","optimizePrompt":false,"resolutionTier":"768p","orientation":"landscape","seconds":5}

个人创作继续采用独立优化、人工采用、生成流程。App 的 H3 生成入口支持默认优化及顶层 optimizePrompt；采用独立优化结果生成时同样传 false，避免再次优化。SDK 接入方式见内部应用开发中的平台服务教程。

自动优化、失败与费用

公开 H3 POST /v1/media/generations 的 optimizePrompt 缺省为 true，显式 false 跳过优化和优化费用。只接受 JSON 布尔值；null、字符串或数字均无效。其他模型不因省略字段自动优化。关闭优化仍保留正常生成审核和生成费用。

平台尚未启用自动优化能力时，H3 缺省或 optimizePrompt: true 请求返回 503 prompt_optimization_capability_unavailable。此时不会按原文自动生成；需要直接使用已确认文本时显式传 false，仍需满足正常生成审核与规格要求。默认优化示例以平台已启用该能力为前提。

开启后创建响应继续是异步 Job，202 仅表示任务受理。轮询原 jobUrl；promptOptimization 可显示准备状态及尝试次数，不能将准备中当作视频已经开始。已知可重试技术失败最多重试一次；技术重试耗尽时 Job 为 failed，errorCode 为 prompt_optimization_failed，不回退原文生成。安全拒绝、需要澄清或候选拒绝不触发技术重试。

每个自动任务最多两次常规优化尝试，每次仅可对完整超长候选压缩一次，因此最多四次优化模型调用。常规调用、重试、压缩均按实际用量计费，已执行的调用即使任务失败也可能收费；未开始的视频生成不扣视频生成费用。独立生图优化最多一次常规调用加一次受控压缩，共两次模型调用，不增加 1200 字符硬上限，也不机械截断。

响应未知时先恢复原优化尝试；不能新建业务键盲目再调用或重复扣费。自动准备与生成共用任务创建起 30 分钟期限，重试不重新获得期限。重放同一请求复用原 Job 与已冻结策略，不重复优化；已受理的历史任务不会因默认值变化追加优化。

自动优化的错误会区分原因：准备超时为 prompt_optimization_timeout；内容审核未通过为 content_safety_blocked；需要补充说明为 content_safety_requires_clarification；优化稿被拒绝为 prompt_optimization_candidate_rejected；审核服务暂不可用为 content_safety_unavailable。这些错误发生于 failureStage: prompt_optimization，安全相关原因的 phase 为 content_safety。技术失败继续使用 prompt_optimization_failed。响应说明视频生成尚未开始，优化费用仍按实际调用结算。

查询 HTTP 200 仅表示查询成功，必须检查正文 status、errorCode、errorMessage；有 details 时可显示受控的审核原因和操作指导。retryable: false 表示不要自动新建付费任务。恢复查询保留原失败原因。

限流和未知结果

并发、频率和服务端超时读取当前能力合同，不在客户端写死套餐额度。429 或明确的容量保护按返回建议退避；结果未知时保留原正文和原键恢复。

optimization_in_progress 表示同一操作尚在处理，不应新建键再优化。明确终态失败后的新动作使用新业务键，并向用户说明；不能把失败直接转换为未经确认的视频生成。