图片调用须知(最佳实践)

图像生成是同步长请求(通常 10–60 秒),与对话接口的调用习惯不同。上量前请通读本页。

超时与重试

• 客户端超时设 ≥120 秒,HTTP 库默认 30 秒会在生成完成前掐断连接;
• 断开的请求上游可能已在计费流程中——失败会自动返还预扣额度,但不要立即密集重试, 建议指数退避(5s → 15s → 45s);
• 429 表示触发限流,处理方式见限流与 429。

型号与画幅选择

• 画幅/分辨率通过模型名后缀指定(-portrait、-landscape、-2k、-4k 等), 不要依赖 size 参数,完整规则见图像与视频生成模型;
• 批量场景优先 -fast 档,验证提示词后再切标准档精修;
• 4K 型号价格更高、生成更慢,只在最终成品阶段使用。

结果处理

• 返回的图片 URL 有时效性,拿到后立即转存到自己的对象存储,不要热链;
• 返回 base64 时注意响应体较大,反代与网关的 body 上限要放宽;
• 按次计费:成功一次扣一次,失败(上游错误/超时)不扣费。

成本控制

• 先用小批量校准提示词模板,稳定后再放量;
• 为图片业务单独建 API 令牌并设额度上限,防止程序 bug 打爆预算;
• 每笔扣费可在控制台”日志”核对,或用日志查询 API 对账。