在生成前优化提示词

先检查能力

模型详情公开的优化能力决定是否可用、支持哪些模式、参考素材与输入限制。不要给所有模型硬套优化调用。H3 当前提供四模式优化路径。

POST /media/prompt-optimizations 是独立操作，优化和后续生成分别计费。它不会自动生成媒体。

构造请求

{
  "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"。不要静默丢弃音频或其他素材。

确认再生成

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

如果产品要默认推荐优化，应在提交前明确说明流程和费用，不隐藏第二次计费操作。

限流和未知结果

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

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