文生图 API
POST /v1/image/tasks 提交生图任务 · GET /v1/image/tasks/{taskNo} 轮询取图 · 按张计费
输入 prompt 生成 1024×1024 PNG 图片。生图为异步任务:提交立即返回 taskNo,轮询到 success 后按 resultUrl 下载图片(现签链接,1 小时内有效)。model 必填,取值以模型列表接口(GET /v1/image/models)实时返回为准,当前在线模型按能力与单价分档:
| 模型 | 能力 | 参考图 |
|---|---|---|
| z-image-turbo | 中文文字渲染 + 第一梯队画质(纯文生图) | 不支持 |
| flux2-klein | 出图快 3 倍、价格更低 | 接受(initImageKey,参考图对出图结果的实际影响以平台说明为准) |
| qwen-image-edit-2511 | 基于参考图做换景/换装/改背景等编辑(Qwen-Image-Edit + Lightning 4 步蒸馏) | 支持(initImageKey) |
图生图用法:先经「上传参考图」拿到 fileKey,随任务提交 initImageKey,编辑指令写在 prompt 里(如「把她的风衣换成白色羽绒服,背景变成冬日雪景」)。质量档与性价比档为纯文生图模型,不消费参考图。
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| prompt | string | 必填 | 生成指令文本,≤2000 字符;中文/英文均可 |
| model | string | 必填 | 模型名(从模型列表接口获取,上表为当前在线模型);不在线时返回 50302 并附当前可用清单 |
| initImageKey | string | 可选 | 参考图 OSS key(upload-tickets 签发的 fileKey);仅 qwen-image-edit-2511 消费为图生图,纯文生图任务不传 |
| seed | integer | 可选 | 随机种子(非负整数):同 prompt + seed + 参考图 复现同一张图;缺省由服务端随机生成,从历史记录的 seed 字段取回后即可复现 |
响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
| taskId | string | 任务号(taskNo),用于轮询查询 |
请求示例
# 纯文生图(质量档) curl https://www.suanlinfang.cn/v1/image/tasks \ -H "Authorization: Bearer $SLF_API_KEY" -H "Content-Type: application/json" \ -d '{"model":"z-image-turbo","prompt":"一只戴眼镜的橘猫在看书,手绘插画风格,温暖光线","seed":42}' # 图生图(参考图编辑,fileKey 来自「上传参考图」小节) curl https://www.suanlinfang.cn/v1/image/tasks \ -H "Authorization: Bearer $SLF_API_KEY" -H "Content-Type: application/json" \ -d '{"model":"qwen-image-edit-2511","prompt":"把她的卡其色风衣换成白色羽绒服,背景变成冬日雪景,雪花飘落","initImageKey":"inference-media/upload/1024/3a7d92c1-....png"}'
图生图任务前先直传参考图:申请上传签名 → PUT 直传 OSS → 以 fileKey 提交任务(与 通用说明 · 文件直传同款三步流)。支持 png / jpg / jpeg,≤10MB;签名 10 分钟内有效,PUT 的 Content-Type 须与签发值一致(不一致返回 403)。
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| fileName | string | 必填 | 文件名(含扩展名),扩展名须为 .png / .jpg / .jpeg |
| sizeBytes | integer | 必填 | 文件大小(字节),≤10MB,超出拒绝签发 |
请求示例
# sizeBytes = 文件实际字节数 curl https://www.suanlinfang.cn/v1/image/upload-tickets \ -H "Authorization: Bearer $SLF_API_KEY" -H "Content-Type: application/json" \ -d '{"fileName":"product-ref.png","sizeBytes":5242880}' # 响应:fileKey 提交任务用;uploadUrl + headers 直传 OSS 用 { "fileKey": "inference-media/upload/1024/3a7d92c1-5b8e-4f0a-9c2d-7e1f6b4a8d30.png", "uploadUrl": "https://slf-media-image.oss-cn-beijing.aliyuncs.com/....?Expires=...&Signature=...", "method": "PUT", "headers": { "Content-Type": "image/png" }, "maxSizeBytes": 10485760 } # PUT 直传(Content-Type 须与签发值一致) curl -X PUT "$UPLOAD_URL" \ -H "Content-Type: image/png" \ --data-binary "@product-ref.png"
任务状态机与轮询约定见通用说明 · 异步任务:status 为 received/queued/running/aggregating/success/failed/expired。生图为单张图单单元任务,doneUnits/totalUnits 恒为 1/1;一般数十秒至三分钟内出图(视当前空闲算力而定,任务排队不额外计费)。
success 响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
| status | string | 任务状态(success) |
| resultUrl | string | 产物图片的现签下载链接(PNG,1024×1024),1 小时内有效;过期后可重新查询换取新链 |
| inputUrl | string | 图生图任务的参考图现签回看链接(纯文生图任务无此字段) |
| expireAt | string | resultUrl 失效时间 |
| failed 时 errorMsg | string | 失败原因(失败任务不扣费) |
请求示例
# 轮询(建议每 5~10 秒一次,success 后按 resultUrl 下载) curl -H "Authorization: Bearer $SLF_API_KEY" \ https://www.suanlinfang.cn/v1/image/tasks/f47ac10b-58cc-4372-a567-0e02b2c3d479 # 响应示例 { "status": "success", "totalUnits": 1, "doneUnits": 1, "resultUrl": "https://slf-media-image.oss-cn-beijing.aliyuncs.com/inference-media/result/f47ac10b-....png?Expires=...&Signature=...", "expireAt": "2026-11-14T12:34:56Z" }
生图任务历史分页查询,参数与字段结构同语音识别 · 历史记录查询;但生图行无 inputName / audioDurationSec / language / hotwords(生图无文件名、时长、语言、热词概念,也无计量字段——计费量纲为张数恒 1)。差异字段:生图行含 inputText(prompt 原文)、modelName(选用模型)、outputSize(图片字节数)、seed(随机种子,同 prompt + seed 复现同图),成功行 resultUrl 为图片现签链接;图生图行另有 inputUrl(参考图原图现签链接,长期有效可回看),文生图行无此字段。
按笔后付费:任务成功按张扣费,失败任务不扣费(排队等待也不计费)。费用明细与账户余额可在「文生图工具」页的「历史记录」与「账户信息」页查看。
按张计费(1 任务 = 1 张图,尺寸固定 1024×1024),三模型牌价不同:z-image-turbo / flux2-klein / qwen-image-edit-2511。牌价以平台实时牌价为准。程序化查询在线模型与实时牌价:GET /v1/image/models,见通用说明 · 模型列表。
网络中断可能发生在任务提交成功之后,重试同一请求会产生新的任务与计费,请结合「调用记录」核对后再重试。