生图 API 接入教程：请求、结果保存与质量验收

生图 API 的难点不只是“能生成一张图”，而是确认端点、输入类型、输出格式、结果有效期和计费单位，并建立一套能复测的质量标准。

不同图像模型可能使用 OpenAI 风格图像接口、厂商专用接口或异步任务。不要根据模型名称猜请求路径，先从当前模型页面和 API 文档确认。

接入前确认四件事

1. 当前账号可用的精确模型 ID。
2. 模型支持文生图、图片编辑还是参考图生成。
3. 请求是同步返回还是创建异步任务。
4. 结果返回 URL、Base64、文件对象还是任务 ID。

先查看当前模型与价格，再从 API 文档复制对应端点和字段。

建立最小请求

下面是通用请求骨架，不代表所有图像模型字段完全一致：

export IMAGE_API_URL="从当前 API 文档复制的完整生图端点"
export API_KEY="你的临时测试 Key"

curl "$IMAGE_API_URL" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "控制台中的精确模型ID",
    "prompt": "白色背景上的蓝色陶瓷杯，正面商品摄影，柔和棚拍光"
  }'

只有当前文档明确支持时，才加入尺寸、宽高比、质量、参考图、透明背景或种子等可选参数。一次加入过多参数，失败后很难判断是不支持字段还是模型问题。

正确处理生成结果

URL 结果

如果响应返回临时 URL：

• 立即下载到自己的对象存储。
• 记录 HTTP 状态、Content-Type 和文件大小。
• 不把临时 URL 当永久素材地址。
• 对下载失败设置有限重试和总超时。

Base64 结果

先校验解码是否成功、文件头是否正确，再写入存储。不要把完整 Base64 放入普通业务日志，否则日志体积和隐私风险都会快速增加。

异步任务

保存任务 ID，使用有上限的轮询间隔查询状态。区分 queued、running、succeeded、failed 和超时，不要在客户端请求超时后立刻重复创建相同任务。

用固定题集验收质量

至少准备四类提示词，每类重复生成多次：

记录每组的可用率、返工次数、生成时间、文件大小和单张成本。只保存最好的一张图，会掩盖模型稳定性问题。

成本和重试怎么记录

图像任务通常按张数、尺寸、质量或模型档位计费，不能直接使用文本 Token 公式。建议保存：

{
  "model": "MODEL_ID",
  "task_type": "text_to_image",
  "width": 0,
  "height": 0,
  "quality": "VALUE_FROM_REQUEST",
  "attempts": 1,
  "status": "succeeded"
}

账务核对应以控制台记录为准。应用侧数据用于定位高返工题型、重复生成和异常失败。

常见错误

400 或参数不支持

回到当前模型文档，删除非必要参数，只保留模型和提示词。不要把另一个供应商的字段直接复制过来。

404 或 model not found

重新查询模型目录并复制精确 ID。确认该模型是否属于图像端点，而不是多模态聊天模型。

返回成功但没有图片

检查响应类型：可能返回任务 ID、临时 URL、Base64 或嵌套数据结构。保存脱敏响应结构，不要只检查 HTTP 状态。

下载链接很快失效

临时结果应在生成成功后立即转存。业务数据库保存自己的对象存储地址和原始任务 ID。

图片质量波动

固定提示词、参考图、尺寸和其他受支持参数，多次生成后比较。模型随机性、内容安全策略和路由变化都可能影响结果。

上线前检查

• 模型 ID 和端点来自当前控制台与文档。
• 同步、异步和失败状态都有处理分支。
• 临时 URL 会立即转存。
• 日志不记录完整图片、Base64 或 API Key。
• 固定题集已经多次复测。
• 单任务超时、轮询和重试都有上限。
• 记录了返工次数与完整任务成本。

完成最小接入后，再阅读模型选择方法和API 成本控制，不要只按单张展示效果决定生产模型。