Skip to Content
GGPU API图片生成

图片生成

通过 /v1/images/generations 提交图片描述,并为同步结果与异步任务两种返回路径做好处理。

图片模型支持的尺寸、数量和返回形式可能不同。先确认当前账号可用的模型,再以实际接口响应为准,不要只根据示例推断能力。

发起最小请求

curl -X POST "${BASE_API_URI}/v1/images/generations" \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer <access-credential-secret>' \ -d '{ "model": "image-model-name", "prompt": "一张干净的产品架构图,白色背景,现代科技风格", "size": "1024x1024" }'

第一次调试时先生成一张图,只保留模型、描述与尺寸。确认链路成功后,再根据模型能力增加其他参数。

组织请求参数

字段是否必填作用检查重点
model是指定图片模型名称来自当前账号可用列表
prompt是描述要生成的画面主体、环境、构图和风格表达清楚
size否指定输出尺寸使用模型实际支持的规格
n否指定生成数量先确认模型支持,再评估额外用量

一个便于复用的描述通常按“主体 → 场景 → 构图 → 视觉要求 → 不希望出现的内容”组织。业务需要稳定结果时,应固定一组真实样例反复验证,而不是只看单次生成效果。

识别返回路径

返回内容会随模型能力和账号配置不同而变化,常见形式包括:

返回形式客户端动作
图片 URL读取并展示 URL 指向的资源,按业务需要决定是否持久化
base64 图片数据解码为正确的图片格式,再交给存储或展示层
任务 ID保存任务 ID,转到任务接口查询状态与最终结果

不要同时假设这三种形式都存在。客户端应先检查实际字段,再进入对应分支。

返回任务 ID 时

保存任务标识

任务 ID 是后续查询、取消和排障的关联键。创建成功后立即与当前业务记录绑定。

查询任务详情

调用 GET /v1/tasks/{task_id} 获取最新状态。查询频率应有合理间隔,避免高频轮询。

读取完成结果

任务完成后,从实际返回结构中读取图片结果;任务失败时保留错误信息,不要继续无限轮询。

结束跟踪

完成、失败或取消后停止轮询。业务不再需要的任务是否删除,应根据接口支持与自身留存策略决定。

生产接入检查

关注点建议
模型能力用真实请求验证尺寸、数量与返回形式
请求超时同步生成允许更长读取时间,异步生成及时转入任务跟踪
结果校验检查字段、文件类型和内容是否可读取
存储策略明确 URL 或 base64 结果由谁保存、保存多久
失败处理参数错误直接修正;限流和临时服务错误按策略重试
用量观察记录模型、尺寸、数量、任务 ID 与请求时间

继续接入