01提交生图任务

输入 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 里(如「把她的风衣换成白色羽绒服,背景变成冬日雪景」)。质量档与性价比档为纯文生图模型,不消费参考图。

接口 POST/v1/image/tasks application/json
鉴权 Bearer API Key(通用说明)

请求参数

参数类型必填说明
promptstring必填生成指令文本,≤2000 字符;中文/英文均可
modelstring必填模型名(从模型列表接口获取,上表为当前在线模型);不在线时返回 50302 并附当前可用清单
initImageKeystring可选参考图 OSS key(upload-tickets 签发的 fileKey);仅 qwen-image-edit-2511 消费为图生图,纯文生图任务不传
seedinteger可选随机种子(非负整数):同 prompt + seed + 参考图 复现同一张图;缺省由服务端随机生成,从历史记录的 seed 字段取回后即可复现

响应字段

字段类型说明
taskIdstring任务号(taskNo),用于轮询查询

请求示例

bash · curl
# 纯文生图(质量档)
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"}'
02上传参考图(图生图)

图生图任务前先直传参考图:申请上传签名 → PUT 直传 OSS → 以 fileKey 提交任务(与 通用说明 · 文件直传同款三步流)。支持 png / jpg / jpeg,≤10MB;签名 10 分钟内有效,PUT 的 Content-Type 须与签发值一致(不一致返回 403)。

接口 POST/v1/image/upload-tickets application/json
鉴权 Bearer API Key

请求参数

参数类型必填说明
fileNamestring必填文件名(含扩展名),扩展名须为 .png / .jpg / .jpeg
sizeBytesinteger必填文件大小(字节),≤10MB,超出拒绝签发

请求示例

bash · curl
# 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"
03轮询结果
接口 GET/v1/image/tasks/{taskNo}

任务状态机与轮询约定见通用说明 · 异步任务:status 为 received/queued/running/aggregating/success/failed/expired。生图为单张图单单元任务,doneUnits/totalUnits 恒为 1/1;一般数十秒至三分钟内出图(视当前空闲算力而定,任务排队不额外计费)。

success 响应字段

字段类型说明
statusstring任务状态(success)
resultUrlstring产物图片的现签下载链接(PNG,1024×1024),1 小时内有效;过期后可重新查询换取新链
inputUrlstring图生图任务的参考图现签回看链接(纯文生图任务无此字段)
expireAtstringresultUrl 失效时间
failed 时 errorMsgstring失败原因(失败任务不扣费)

请求示例

bash · curl
# 轮询(建议每 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"
}
04历史记录查询
接口 GET/v1/image/tasks

生图任务历史分页查询,参数与字段结构同语音识别 · 历史记录查询;但生图行无 inputName / audioDurationSec / language / hotwords(生图无文件名、时长、语言、热词概念,也无计量字段——计费量纲为张数恒 1)。差异字段:生图行含 inputText(prompt 原文)、modelName(选用模型)、outputSize(图片字节数)、seed(随机种子,同 prompt + seed 复现同图),成功行 resultUrl 为图片现签链接;图生图行另有 inputUrl(参考图原图现签链接,长期有效可回看),文生图行无此字段。

05计费说明

按笔后付费:任务成功按张扣费,失败任务不扣费(排队等待也不计费)。费用明细与账户余额可在「文生图工具」页的「历史记录」与「账户信息」页查看。

按张计费(1 任务 = 1 张图,尺寸固定 1024×1024),三模型牌价不同:z-image-turbo / flux2-klein / qwen-image-edit-2511。牌价以平台实时牌价为准。程序化查询在线模型与实时牌价:GET /v1/image/models,见通用说明 · 模型列表。

网络中断可能发生在任务提交成功之后,重试同一请求会产生新的任务与计费,请结合「调用记录」核对后再重试。