Grok API /v1/images/edits 参数详解：model、prompt、image 怎么传？

本文验证日期为 2026-08-17。验证范围是 POST https://api.sublyx.org/v1/images/edits/async 和任务查询接口 GET https://api.sublyx.org/v1/images/tasks/:task_id。这两个接口是异步工作流：提交请求只负责创建任务，图片结果需要稍后查询。

最小可运行请求

下面的命令将本地的 lamp.png 作为参考图上传。curl -F 会自动生成正确的 multipart 请求头，因此不要同时添加 Content-Type: application/json。

curl https://api.sublyx.org/v1/images/edits/async \
  -H "Authorization: Bearer $SUBLYX_API_KEY" \
  -F "model=grok-imagine-edit" \
  -F "prompt=Change the lamp to matte red; keep composition and shadows" \
  -F "image=@lamp.png"

提交成功后，从 JSON 响应中读取 task_id。不要假设提交响应已经包含最终图片，也不要把一次提交循环误当成同步生成。

三个核心参数

参数	传输方式	作用	注意事项
model	文本字段	指定 grok-imagine-edit	不要把文生图模型或未经确认的模型 ID 混用。
prompt	文本字段	描述要改变的内容和需要保留的内容	写清主体、区域、颜色和“不变项”，通常比笼统命令更可控。
image	文件字段	提供编辑所依据的图片	使用 @文件路径；准备好可读取的 PNG、JPG 或 WEBP 文件。

prompt 怎么写

一个实用结构是“动作 + 目标 + 保持项”：把桌面灯改成哑光红色；保持构图、阴影、背景和主体位置不变。如果只需要调整一个区域，直接指出区域；如果要保留文字、Logo 或人物身份，也应明确写出。一次请求改动越多，越难判断失败原因。

image 怎么传

-F "image=@lamp.png" 中的 @ 表示从本地读取文件。服务端需要收到实际文件，而不是文件名、网页链接或 JSON 里的 Base64 字符串。上传前检查扩展名、MIME 类型、文件大小和图片是否能正常打开；建议优先使用清晰、压缩较少的参考图。

用 task_id 轮询

用成功响应返回的任务 ID 查询 GET /v1/images/tasks/:task_id，并对 ID 做 URL 编码。首次等待几秒后再查询，之后使用约 4 秒间隔和明确的总超时；任务为 completed 时读取返回结果，failed 或 cancelled 时停止。

curl "https://api.sublyx.org/v1/images/tasks/$TASK_ID" \
  -H "Authorization: Bearer $SUBLYX_API_KEY"

不同任务状态的结果字段应以实际响应为准。生产代码要记录任务 ID、HTTP 状态和安全的错误摘要，但不要把完整图片内容或 API Key 写入日志。

重复提交风险

网络超时并不等于任务创建失败。若客户端在提交后立刻重试，可能创建两个编辑任务，造成重复结果或额外消耗。更稳妥的做法是先保存客户端请求记录，超时后优先依据已收到的 task_id 查询；只有确认没有创建结果时才重试，并在业务层做去重。

安全说明

API Key 只放在服务端环境变量或密钥管理系统中，不要放进浏览器 JavaScript、公开仓库、截图或前端日志。上传用户图片前取得必要授权，并清理临时文件和敏感 EXIF。接入前可查看 Sublyx 接入文档、模型列表，也可阅读 Grok Imagine API 总指南 与 Grok 图片编辑错误排查。