使用指南
imagen-4.0 上手指南：文生图能力边界、定价与接口接入要点
imagen-4.0 是什么，适合谁用
imagen-4.0 是 HiAPI.ai 上新接入的图像生成模型，输出类型为图像，能力范围是 text-to-image。换句话说，你给它一段文字描述，它返回一张（或多张）匹配描述的图片；它的输入是文本，输出是图像，中间不涉及其他模态。
正因为它是一个「纯文生图」定位的模型，适合它的业务场景其实很清晰：
- 需要批量、程序化地产出配图的内容平台，例如文章头图、商品场景图、营销素材初稿。
- 产品内需要「一句话生成一张图」的交互，比如头像、壁纸、灵感草图一类功能。
- 需要把生成能力嵌进内部设计、运营工作流，用 API 代替人工反复出图。
反过来，如果你的需求里出现了这些关键词，就要先停下来确认：图生图、局部重绘/编辑、参考图保持人物一致性、图像理解（看图说话）、视频生成。这些能力不在 text-to-image 的范围内，imagen-4.0 并不承诺覆盖。选型的第一步不是比效果，而是确认「我的业务只需要文生图」——如果需求本身就跨模态，越早换方向越省成本。
对于只想快速验证效果的团队，最轻量的路径是先在 HiAPI.ai 上跑几条提示词、看看出图风格是否贴合品牌调性，再决定要不要进入工程接入阶段。
能力边界：文生图能做什么、不能做什么
把能力边界写清楚，比写清楚「它很强」更有用。基于已知信息，imagen-4.0 的核心能力就是 text-to-image：输入提示词，输出图像。围绕这条主线，可以这样分层理解。
可以预期的工作方式
- 文本到图像的生成：提示词是唯一的语义入口，画面内容、风格、构图都依赖你怎么描述。
- 单次请求产出一张图：如果业务需要多个候选，按多次生成或多张出图来设计调用次数与预算。
- 适合可被文字充分描述的题材：主体明确、风格明确、构图要求相对明确的画面，通常比「我想要一张很有感觉的图」这类模糊需求更容易得到稳定结果。
不在承诺范围内的能力
以下方向材料未作覆盖，请不要在方案里预设它们可用，需要时请自行通过小样本调用验证：
- 图生图、以参考图控制风格或主体一致性。
- 图像编辑类操作，如局部修改、扩图、去除元素。
- 图像理解或多模态往返对话。
- 对生成结果做精确的文字渲染、特定版权素材复现等强约束任务。
一个务实的判断方法
把需求拆成「输入是什么、输出是什么、约束有多强」三格。输入必须是文本、输出必须是图像、约束可以靠提示词表达——三条全过，才进入下一步评估；只要有一条不过，就先做一次最小验证调用，别直接把接口写进主流程。边界不清的功能最贵，因为它会在上线后才暴露。
计费方式与成本估算思路
imagen-4.0 采用按张计费的口径：每生成一张图计一次费。这个口径的含义是，成本与「实际出图张数」线性相关，而不是与请求次数、提示词长短或生成耗时相关。实时单价请以 HiAPI.ai 站点价格面板为准，本文不展开具体数字，只讲估算方法。
成本估算的基本公式
月度成本 ≈ 单价 × 月出图张数
月出图张数 = 有效请求数 × 每请求候选图数 × (1 + 重试率)
三个乘数里，只有「有效请求数」是业务真正想要的产出，另外两个都是工程变量。它们决定了你的实际成本会偏离预算多少：
- 候选图数量：为了挑一张满意的图而一次出四张，成本就是单张的四倍。候选策略要按场景分级，不是所有位置都需要多候选。
- 重试率：参数错误、提示词被拒、网络超时都会触发重试，每一次重试都可能产生实际计费。重试必须设上限。
- 缓存命中：同一个提示词与参数组合被重复请求时，直接返回缓存结果可以省掉整笔费用，这在模板化配图场景里收益很明显。
估算时的三个习惯
- 先估「最终需要多少张可用图」，再反推需要生成多少张，把筛选损耗算进去。
- 把重试与候选分开记账，便于定位成本异常是来自业务增长还是来自失败重试。
- 在预算里给验证阶段单独留一块：小样本试跑也是真实消耗，但它换来的是后续放量的可控性。
不建议在估算时引入任何未公开的价格档位、折扣或免费额度假设——一切以价格面板与账单为准。
调用方式与参数关注点
在 HiAPI.ai 上使用 imagen-4.0，走的是统一的模型调用路径：同一个接入方式、同一套鉴权与请求结构，模型之间通过模型标识切换。这意味着你不需要为图像模型单独搭一套 SDK 或网关，已有的调用封装可以复用。
通用接入流程
- 在 HiAPI.ai 获取调用凭证，按统一鉴权方式配置到服务端环境变量中，不要下发到客户端。
- 选择 imagen-4.0 作为目标模型，构造请求：提示词放在输入字段，生成相关的可选配置按需传入。
- 解析响应，取出图像结果（通常是链接或二进制数据，取决于接口返回形态），落盘或转存到自己的对象存储。
- 对返回结果做校验：是否有图、尺寸是否符合预期、内容是否通过你自己的审核环节。
上线前需要确认的参数维度
具体字段名与取值范围请以 HiAPI.ai 的模型文档为准，这里只列出需要你在联调阶段逐项确认的维度，避免上线后才发现默认值不合预期：
- 出图数量：单次请求返回几张图，是否支持一次多图；这直接决定计费口径下的单请求成本。
- 尺寸与宽高比：业务实际需要的画幅是方图、竖图还是横图，默认尺寸是否符合你的展示位。
- 输出格式与返回形态：返回的是 URL 还是字节流，URL 是否有有效期，是否需要你自行转存。
- 安全与过滤行为：哪些提示词会被拒绝，拒绝时返回什么状态，便于你设计用户提示与降级文案。
- 超时与限流：单次生成的时间量级、并发上限与错误码含义，决定你的队列与重试策略。
联调建议用固定的十条提示词做一次冒烟，把所有参数维度各改一次，记录行为差异，形成团队内部的接入笔记。
提示词与出图质量的实践方法
文生图的效果对提示词高度敏感，而敏感意味着两件事：调好它能显著提升可用率，调不好它会持续烧钱。工程团队应该把提示词当成受版本管理的资产，而不是散落在代码里的字符串。
提示词的组织方式
把提示词拆成可复用的结构块，比写一长句更稳：
- 主体：画面里最重要的东西，放在最前面，描述具体而非抽象。
- 场景与环境：地点、时间、氛围、背景元素。
- 风格与媒介：摄影、插画、3D 渲染等风格取向，以及光线和色调倾向。
- 技术性约束：画幅比例、镜头感、清晰度要求等，尽量用模型能理解的自然语言表达。
- 负面约束：明确不想要什么（比如不要出现文字、不要人物），比反复修补正向描述更省候选图。
模板化之后，变量只留主体与少量场景词，同一套风格块可以覆盖整批素材，出图一致性会明显提升。
候选筛选与质量回归
不要让「人眼挑图」成为唯一的质量关卡。建议保留一组固定的回归提示词集合（覆盖你的主要业务题材），每次调整提示词模板或参数后重跑一遍，对比可用率，避免出现「改了一版感觉更好、整体却变差」的漂移。
筛选环节也有成本意识：给不同展示位设不同的质量阈值，头图位置允许更多候选，列表缩略图一张过即可。挑出来的不合格图要记原因（主体偏移、风格不符、构图崩坏），反馈到提示词模板的修订里，形成闭环，而不是靠调大候选数量硬扛。
批量生成与工程化落地
当调用量从每天几十张涨到每天上万张，问题就从「效果好不好」变成「流程稳不稳」。文生图天然是慢操作，把它当同步接口用，迟早会撞上超时与并发墙。
异步任务 + 结果缓存
推荐的骨架是：业务侧提交生成任务进入队列 → 工作进程调用 imagen-4.0 → 结果写入对象存储并在缓存层登记 → 业务侧通过任务状态或回调获取。这样做的收益有三点：
- 请求与生成解耦，前端不必长时间挂起等待。
- 工作进程可以按限流节奏匀速消费，削平流量尖峰。
- 相同提示词与参数组合可以命中缓存，按张计费的口径下，每命中一次省一笔。
缓存键要包含提示词、尺寸、出图数量等所有影响结果的参数，避免不同配置互相污染。对有时效性的素材（比如与当季活动绑定的图），缓存要设过期策略。
重试上限与并发控制
- 重试要有上限：建议对可重试错误（超时、限流）设置固定的最大尝试次数，超过就落失败并告警；对不可重试错误（参数非法、内容被拒）不要重试。
- 区分退避与重试：指数退避解决的是瞬时压力，不是内容问题，别用重试掩盖提示词缺陷。
- 并发与配额联动：工作进程数量要与账号配额对齐，超限后的失败重试会放大成本。
- 可观测性：按提示词模板、业务场景、错误类型三个维度记录调用量与失败率，成本异常时能立刻定位来源。
最后，给用户可见的生成结果留出降级路径：生成失败时展示占位内容或稍后重试提示，而不是让整个页面跟着一次调用一起失败。
上线前的检查清单
在放量之前，把下面几组问题逐条过一遍，每条都要有明确的负责人和结论，而不是「大概没问题」。
能力与质量
- 已确认业务只需要 text-to-image，没有隐性的图生图或多模态依赖。
- 用固定提示词集合跑过回归，记录了当前可用率基线，并知道阈值在哪里。
- 主要业务题材各有一组代表性样本，人工评审结论已归档。
- 尺寸、输出格式、返回形态与前端展示位匹配。
成本与容量
- 已按出图张数×候选数×重试率做过月度成本估算，并设置预算警戒线。
- 缓存策略与过期规则已确定，重复场景能命中缓存。
- 重试上限、并发上限、队列容量都已配置，且有超限告警。
- 计费口径以 HiAPI.ai 价格面板为准，账单与实际出图量能对上账。
合规与体验
- 版权与素材使用策略已明确：生成图的使用范围、对第三方素材的规避要求。
- 内容合规过滤已接入，被拒提示词有面向用户的友好文案。
- 用户可见处是否需要标注「AI 生成」已按业务所在地区要求确认。
- 失败与降级路径已演练，页面不会因单次生成失败而整体不可用。
运维
- 关键指标已接入监控：调用量、失败率、平均耗时、缓存命中率、消耗张数。
- 告警阈值已设定并验证能触达值班人。
- 模型或提示词模板变更时有回滚方案。
把这份清单当作上线门槛，逐项打勾后再放量。需要开始验证的话，可以从 HiAPI.ai 的 imagen-4.0 模型页跑第一批提示词开始。
