联系我们控制台

图像生成与图生图 API

文生图和图生图统一使用海宇平台 API Key。模型是否已开放，以模型广场实际展示为准。

当前提供以下模型 ID：image-1k-2k-4k-th、image-2、image-2.5-flare、image-2.5-sunburst、image-2.5。

文生图

向 POST /v1/images/generations 发送 JSON。首次接入建议省略尺寸，使用已验收的默认参数。

curl https://api.haiyushuke.com/v1/images/generations \
  -H "Authorization: Bearer $HAIYU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"image-2.5","prompt":"白色桌面上的蓝色陶瓷杯，产品摄影","n":1}'

model 和 prompt 必填。n 默认 1，最大值以模型实际开放能力为准。size 可省略，仅接受已验收尺寸。当前验收通过的返回格式为 URL，response_format 请省略或设为 url。

图生图

向 POST /v1/images/edits 发送 multipart 表单，上传参考图并描述修改要求。不要手工设置 multipart 的 Content-Type，客户端会自动生成 boundary。

curl https://api.haiyushuke.com/v1/images/edits \
  -H "Authorization: Bearer $HAIYU_API_KEY" \
  -F "model=image-2.5" \
  -F "prompt=保留杯子的形状，将背景改为浅灰色" \
  -F "n=1" \
  -F "image=@reference.png"

参考图支持 PNG、JPEG、WebP，每张不超过 10 MiB，当前每次支持 1 张，使用 image 字段。参考图在任务处理期间临时加密保存，任务结束后清理；处理总时限为 15 分钟，缓存另留 1 分钟清理余量，不写入调用日志。

异步任务与幂等

建议为每次新的生成操作设置唯一的 Idempotency-Key，同一次操作因断线重新提交时保留原 Key、原参数和原幂等键。相同幂等键修改参数返回 409，不会创建新任务。海宇按用户及平台 Key 隔离任务，其他用户或其他平台 Key 无法查询该任务。

请求添加 "async": true 可先取得任务编号；图生图表单使用 -F "async=true"。未开启异步时，平台等待最多约 230 秒，未完成也返回 202，后台继续处理。

curl https://api.haiyushuke.com/v1/images/generations \
  -H "Authorization: Bearer $HAIYU_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: image-order-20261017-001" \
  -d '{"model":"image-2.5","prompt":"蓝色陶瓷杯产品摄影","n":1,"async":true}'
{"id":"海宇任务UUID","object":"image.task","status":"queued","model":"image-2.5"}

读取 Retry-After 后查询原任务，不要重新创建生成请求：

curl https://api.haiyushuke.com/v1/images/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer $HAIYU_API_KEY"

查询 HTTP 200 表示成功读取状态。queued 为排队，running 为生成，delivering 为图片校验；succeeded 才可从 result.data 读取图片。查询不会重复生成或重复收费。后台处理与浏览器等待分离，刷新页面可在体验中心的图片任务记录中继续查看。

{"id":"海宇任务UUID","object":"image.task","status":"succeeded","model":"image-2.5","result":{"created":1792195200,"data":[{"url":"https://example.com/generated.png"}]}}

failed 表示没有可交付结果，检查 error.code 并联系支持；结果不明不会自动重新采购。成功结果记录保留 12 小时，之后查询可能返回 expired，已结算费用不会因记录过期而自动退回。外部图片链接可能有独立有效期，请及时下载保存。停止前端等待不等于取消任务。

响应与计费

{"created":1792195200,"data":[{"url":"https://example.com/generated.png"}]}

图片也可能通过 data[].b64_json 返回。请检查实际图片结果，HTTP 成功或仅有任务 ID 不代表生成成功。

文生图、图生图均按 0.03 元/成功图片计费，参考图不另收费。调用前预留所请求张数的余额和适用 Key 额度；部分成功仅收成功部分，失败与未生成部分退回预留。预留和最终结算记录可用于对账。

任务ID和 202 不计成功图片。平台完成图片校验后按可交付张数结算，重复查询、幂等重放、恢复处理不会重复结算。到达处理总时限仍无法确认结果的任务释放客户预留并转入核对，不自动补扣客户。

错误与重试

  • 400：参数、尺寸或参考图格式不符。
  • 402：余额或 API Key 额度不足。
  • 403：Key 未授权当前模型。
  • 404：模型不存在或未上线。
  • 409：同一幂等键被用于不同参数。
  • 429：可用渠道已满，按 Retry-After 提示稍后再试。
  • 502 / 503：上游失败或服务暂不可用。

发送后超时、连接中断或收到结算待处理提示时，请保留 X-Request-ID 查询记录，避免自动重发造成重复生成。平台仅在确认上游尚未接受请求时进行安全切换。

也可以在体验中心 选择模型，切换文生图／图生图，上传参考图并查看、下载结果。