Grok Imagine Image 2.0 图片编辑
本页由 ModelFold 文档站根据上游官方 OpenAPI 文档同步生成。接口路径、参数、示例与官方保持一致；品牌与 API 域名已替换为 ModelFold。
接口
POST /jobs/createTask
完整 URL: https://ai.modelfold.online/v1/jobs/createTask
鉴权：所有请求都需要
Authorization: Bearer <API_KEY>请求头。
查询任务状态
提交任务后，使用统一的查询端点来检查进度并获取结果：
- 获取任务详情 — 了解如何查询任务状态并获取生成结果
TIP
生产环境中，建议使用 callBackUrl 参数接收生成完成的自动通知，而非轮询状态端点。
相关资源
请求参数
请求体 (application/json)
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 是 | 用于生成的模型名称。必填字段。 - 对于此端点，必须为 grok-imagine-image-2-0/image-edit 默认值："grok-imagine-image-2-0/image-edit"。 可选值：grok-imagine-image-2-0/image-edit。 示例：grok-imagine-image-2-0/image-edit。 |
callBackUrl | string | 否 | 用于接收生成任务完成更新的 URL。可选，但建议在生产环境中使用。 - 当生成完成时，系统会将任务状态和结果通过 POST 请求发送到此 URL - 回调包含生成内容的 URL 和任务信息 - 您的回调端点应接受包含结果的 JSON 负载的 POST 请求 - 或者，使用“获取任务详细信息”端点来轮询任务状态 - 为了确保回调安全性，请参阅 Webhook 验证指南 以了解签名验证的实现 示例： https://your-domain.com/api/callback。 |
input | object | 否 | 生成任务的输入参数 |
input.prompt | string | 否 | 指定生成图像的所需内容或样式的文本描述。最长 8000 字符。 示例：Recreate the Titanic movie poster with two adorable anthropomorphic cats in the same romantic pose at the bow of the ship. The male cat is an orange tabby wearing a vest, standing behind a white long-haired female cat in a lace dress, holding her paws as they stretch forward in the wind. Both cats are photorealistic with detailed fur, wind-swept hair, and dramatic sunset lighting (warm golden highlights, cool blue shadows). Background: the Titanic ship at dusk with four smokestacks, glowing deck lights, calm ocean, and orange-pink sunset sky. Center title: “CATANIC” in the same gold metallic serif style as Titanic, same size and position.。 |
input.aspect_ratio | string | 是 | 指定生成图像的宽高比。控制输出的宽高比例。此字段为必填项。 可选值：1:1 / 2:3 / 3:2 / 16:9 / 9:16 / auto。 示例：1:1。 |
input.image_urls | array<string> | 是 | 包含最多5张，最少1张指向参考图像的 URL 字符串的数组。 |
请求示例
bash
curl -X POST "https://ai.modelfold.online/v1/jobs/createTask" \
-H "Authorization: Bearer $MODELFOLD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-imagine-image-2-0/image-edit",
"callBackUrl": "https://your-domain.com/api/callback",
"input": {
"prompt": "Recreate the Titanic movie poster with two adorable anthropomorphic cats in the same romantic pose at the bow of the ship. The male cat is an orange tabby wearing a vest, standing behind a white long-haired female cat in a lace dress, holding her paws as they stretch forward in the wind. Both cats are photorealistic with detailed fur, wind-swept hair, and dramatic sunset lighting (warm golden highlights, cool blue shadows). Background: the Titanic ship at dusk with four smokestacks, glowing deck lights, calm ocean, and orange-pink sunset sky. Center title: “CATANIC” in the same gold metallic serif style as Titanic, same size and position.",
"aspect_ratio": "1:1",
"image_urls": [
"https://static.aiquickdraw.com/tools/example/1767602105243_0MmMCrwq.png"
]
}
}'json
{
"model": "grok-imagine-image-2-0/image-edit",
"callBackUrl": "https://your-domain.com/api/callback",
"input": {
"prompt": "Recreate the Titanic movie poster with two adorable anthropomorphic cats in the same romantic pose at the bow of the ship. The male cat is an orange tabby wearing a vest, standing behind a white long-haired female cat in a lace dress, holding her paws as they stretch forward in the wind. Both cats are photorealistic with detailed fur, wind-swept hair, and dramatic sunset lighting (warm golden highlights, cool blue shadows). Background: the Titanic ship at dusk with four smokestacks, glowing deck lights, calm ocean, and orange-pink sunset sky. Center title: “CATANIC” in the same gold metallic serif style as Titanic, same size and position.",
"aspect_ratio": "1:1",
"image_urls": [
"https://static.aiquickdraw.com/tools/example/1767602105243_0MmMCrwq.png"
]
}
}响应
200 — 请求成功
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
code | integer | 是 | 请求状态码。请求失败时 HTTP 状态仍为 200，请始终以本字段判断：200 表示成功，其他值均表示失败，原因见 msg。常见值：401 API key 无效或缺失；402 积分不足；429 超出频率限制；422 或 500 请求未能处理（请先查看 msg、检查参数，再决定是否重试）。 可选值：200 / 401 / 402 / 404 / 422 / 429 / 433 / 455 / 500 / 501 / 505。 示例：200。 |
msg | string | 是 | 响应消息，失败时的错误描述 |
data | object | 是 | — |
data.taskId | string | 是 | 可以使用任务 ID 与“获取任务详细信息”端点一起查询任务状态。 |
json
{
"code": 200,
"msg": "success",
"data": {
"taskId": "task_grok-imagine_1767694553297"
}
}回调
onImageGenerated
回调地址：{$request.body#/callBackUrl}（即请求体里的 callBackUrl）。
任务成功或失败时发送回调。
回调体参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
code | integer | 否 | 200：成功；501：失败，原因见 data.failCode 与 data.failMsg。 可选值：200 / 501。 示例：200。 |
msg | string | 否 | 状态消息 示例：Playground task completed successfully.。 |
data | object | 否 | — |
data.completeTime | integer | 否 | 任务完成时间，以 Unix 时间戳（毫秒）表示 示例：1787284560000。 |
data.costTime | integer | 否 | 处理耗时（秒），成功和失败回调都会返回。 示例：35。 |
data.createTime | integer | 否 | 任务创建时间，以 Unix 时间戳（毫秒）表示 示例：1787284517000。 |
data.creditsConsumed | number | 否 | 本任务消耗的积分；失败任务为 0。 示例：4。 |
data.model | string | 否 | 任务使用的图像转图像模型 示例：grok-imagine-image-2-0/segment-edit。 |
data.param | string | 否 | 创建任务时提交的参数，格式为 JSON 字符串 示例：{"input":"{\"aspect_ratio\":\"auto\",\"image_urls\":[\"https://static.aiquickdraw.com/tools/example/1767602105243_0MmMCrwq.png\"],\"prompt\":\"重新创作《泰坦尼克号》电影海报：两只可爱的拟人化猫咪以同样浪漫的姿势站在船头。雄性猫咪是一只身穿马甲的橘色虎斑猫，站在穿着蕾丝裙的白色长毛雌性猫咪身后，牵着她的爪子，一同迎着风向前伸展。两只猫咪都要呈现逼真的照片质感，拥有细致的毛发、被风吹拂的毛发与戏剧性的日落光影（温暖的金色高光、冷峻的蓝色阴影）。背景为黄昏时分的泰坦尼克号，配有四根烟囱、发光的甲板灯、平静的海面以及橙粉色的日落天空。中央标题使用与《泰坦尼克号》相同的金色金属质感衬线字体、相同的大小和位置，文字为“CATANIC”。\"}","callBackUrl":"http://localhost:8555/api/v1/config/test","model":"grok-imagine-image-2-0/segment-edit"}。 |
data.resultJson | string | 否 | 图像生成结果，格式为 JSON 字符串。resultUrls 包含生成图像的 URL 列表。仅在 state 为 success 时出现。 示例：{"resultUrls":["https://tempfile.aiquickdraw.com/ggg/23e972d3-9761-4467-9cc1-29a5aa30b1a6.jpg"]}。 |
data.state | string | 否 | 任务状态 可选值：success / fail。 示例：success。 |
data.taskId | string | 否 | 任务 ID 示例：6948da647cafec99c49d1dcde91b4b05。 |
data.updateTime | integer | 否 | 完成时间请以 completeTime 为准；updateTime 可能与 createTime 相同。 示例：1787284560000。 |
data.failCode | string | 否 | 失败码，数字字符串，如 "400"、"500"。仅在 state 为 fail 时出现。 示例：500。 |
data.failMsg | string | 否 | 失败原因，仅在 state 为 fail 时出现。 示例：<error detail>。 |
任务成功
json
{
"code": 200,
"msg": "Playground task completed successfully.",
"data": {
"taskId": "6948da647cafec99c49d1dcde91b4b05",
"model": "grok-imagine-image-2-0/segment-edit",
"state": "success",
"param": "{\"input\":\"{\\\"aspect_ratio\\\":\\\"auto\\\",\\\"image_urls\\\":[\\\"https://static.aiquickdraw.com/tools/example/1767602105243_0MmMCrwq.png\\\"],\\\"prompt\\\":\\\"重新创作《泰坦尼克号》电影海报：两只可爱的拟人化猫咪以同样浪漫的姿势站在船头。雄性猫咪是一只身穿马甲的橘色虎斑猫，站在穿着蕾丝裙的白色长毛雌性猫咪身后，牵着她的爪子，一同迎着风向前伸展。两只猫咪都要呈现逼真的照片质感，拥有细致的毛发、被风吹拂的毛发与戏剧性的日落光影（温暖的金色高光、冷峻的蓝色阴影）。背景为黄昏时分的泰坦尼克号，配有四根烟囱、发光的甲板灯、平静的海面以及橙粉色的日落天空。中央标题使用与《泰坦尼克号》相同的金色金属质感衬线字体、相同的大小和位置，文字为“CATANIC”。\\\"}\",\"callBackUrl\":\"http://localhost:8555/api/v1/config/test\",\"model\":\"grok-imagine-image-2-0/segment-edit\"}",
"resultJson": "{\"resultUrls\":[\"https://tempfile.aiquickdraw.com/ggg/23e972d3-9761-4467-9cc1-29a5aa30b1a6.jpg\"]}",
"costTime": 35,
"createTime": 1787284517000,
"completeTime": 1787284560000,
"updateTime": 1787284560000,
"creditsConsumed": 4
}
}任务失败
json
{
"code": 501,
"msg": "Playground task failed.",
"data": {
"taskId": "6948da647cafec99c49d1dcde91b4b05",
"model": "grok-imagine-image-2-0/segment-edit",
"state": "fail",
"param": "{\"input\":\"{\\\"aspect_ratio\\\":\\\"auto\\\",\\\"image_urls\\\":[\\\"https://static.aiquickdraw.com/tools/example/1767602105243_0MmMCrwq.png\\\"],\\\"prompt\\\":\\\"重新创作《泰坦尼克号》电影海报：两只可爱的拟人化猫咪以同样浪漫的姿势站在船头。雄性猫咪是一只身穿马甲的橘色虎斑猫，站在穿着蕾丝裙的白色长毛雌性猫咪身后，牵着她的爪子，一同迎着风向前伸展。两只猫咪都要呈现逼真的照片质感，拥有细致的毛发、被风吹拂的毛发与戏剧性的日落光影（温暖的金色高光、冷峻的蓝色阴影）。背景为黄昏时分的泰坦尼克号，配有四根烟囱、发光的甲板灯、平静的海面以及橙粉色的日落天空。中央标题使用与《泰坦尼克号》相同的金色金属质感衬线字体、相同的大小和位置，文字为“CATANIC”。\\\"}\",\"callBackUrl\":\"http://localhost:8555/api/v1/config/test\",\"model\":\"grok-imagine-image-2-0/segment-edit\"}",
"costTime": 35,
"createTime": 1787284517000,
"completeTime": 1787284560000,
"updateTime": 1787284560000,
"creditsConsumed": 0,
"failCode": "500",
"failMsg": "<error detail>"
}
}