ModelFold Docs

简体中文

English

简体中文

English

Appearance

Grok Imagine 图生图 ​

本页由 ModelFold 文档站根据上游官方 OpenAPI 文档同步生成。接口路径、参数、示例与官方保持一致；品牌与 API 域名已替换为 ModelFold。

接口 ​

POST /jobs/createTask

完整 URL: https://ai.modelfold.online/v1/jobs/createTask

鉴权：所有请求都需要 Authorization: Bearer <API_KEY> 请求头。

文件上传要求 ​

在使用图像到图像 API 之前，您需要上传您的参考图像：

第 1 步 · 上传参考图像

使用文件上传 API 上传您的参考图像。

要求：

  • 文件类型：JPEG、PNG 或 WebP 格式
  • 最大文件大小：每个文件 10MB
  • 内容：您想要用作生成参考的图像

第 2 步 · 获取文件 URL

上传后，您将收到可在 image_urls 参数中使用的文件 URL。

WARNING

  • 支持的格式：JPEG、PNG、WebP（最大：10MB）

查询任务状态 ​

提交任务后，使用统一的查询端点来检查进度并获取结果：

TIP

生产环境中，建议使用 callBackUrl 参数接收生成完成的自动通知，而非轮询状态端点。

相关资源 ​

请求参数 ​

请求体 (application/json) ​

参数类型必填说明
modelstring是用于生成任务的模型名称。必填字段。
- 此端点必须为 grok-imagine/image-to-image 默认值："grok-imagine/image-to-image"。 可选值：grok-imagine/image-to-image。 示例：grok-imagine/image-to-image。
callBackUrlstring否接收生成任务完成更新的 URL。可选但建议在生产环境中使用。
- 系统将在生成完成时向此 URL 发送 POST 请求
- 回调包含生成的内容 URL 和任务信息
- 您的回调端点应接受包含结果的 JSON 负载的 POST 请求
- 或者，使用获取任务详情端点来轮询任务状态
- 为确保回调安全性，请参阅 Webhook 校验指南 了解签名验证实现方法 示例：https://your-domain.com/api/callback。
inputobject否生成任务的输入参数
  input.promptstring否指定生成图像所需内容或样式的文本描述。（最大长度：390000 个字符） 示例：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.image_urlsarray&lt;string&gt;是1~5 张图片 URL（须为上传后的文件地址，而非文件本体）。支持类型：image/jpeg、image/png、image/webp；单张最大 10.0MB。在文本提示中可通过输入 @image(n) 并在其后加空格来引用该参考图（例如：@image1 海边日落）。
  input.nsfw_checkerboolean否默认 false。为 false 时不额外进行内容过滤，结果由模型直接返回。

请求示例 ​

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-to-image",
  "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.",
    "image_urls": [
      "https://static.aiquickdraw.com/tools/example/1767602105243_0MmMCrwq.png"
    ]
  }
}'
json
{
  "model": "grok-imagine/image-to-image",
  "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.",
    "image_urls": [
      "https://static.aiquickdraw.com/tools/example/1767602105243_0MmMCrwq.png"
    ]
  }
}

响应 ​

200 — 请求成功 ​

参数类型必填说明
codeinteger是请求状态码。请求失败时 HTTP 状态仍为 200，请始终以本字段判断：200 表示成功，其他值均表示失败，原因见 msg。常见值：401 API key 无效或缺失；402 积分不足；429 超出频率限制；422 或 500 请求未能处理（请先查看 msg、检查参数，再决定是否重试）。 可选值：200 / 401 / 402 / 404 / 422 / 429 / 433 / 455 / 500 / 501 / 505。 示例：200。
msgstring是响应消息，失败时的错误描述
dataobject是—
  data.taskIdstring是可以使用任务 ID 与“获取任务详细信息”端点一起查询任务状态。
json
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "task_grok-imagine_1767694553297"
  }
}

回调 ​

onImageGenerated ​

回调地址：{$request.body#/callBackUrl}（即请求体里的 callBackUrl）。

任务成功或失败时发送回调。

回调体参数

参数类型必填说明
codeinteger否200：成功；501：失败，原因见 data.failCode 与 data.failMsg。 可选值：200 / 501。 示例：200。
msgstring否状态消息 示例：Playground task completed successfully.。
dataobject否—
  data.completeTimeinteger否任务完成时间，Unix 毫秒时间戳 示例：1786431871000。
  data.costTimeinteger否处理耗时（秒），成功和失败回调都会返回。 示例：11。
  data.createTimeinteger否任务创建时间，Unix 毫秒时间戳 示例：1786431859000。
  data.creditsConsumednumber否本任务消耗的积分；失败任务为 0。 示例：4。
  data.modelstring否图生图任务使用的模型 示例：grok-imagine/image-to-image。
  data.paramstring否创建任务时提交的参数，JSON 字符串格式 示例：{"input":"{\"image_urls\":[\"https://static.aiquickdraw.com/tools/example/1767602105243_0MmMCrwq.png\"],\"prompt\":\"重现《泰坦尼克号》电影海报，画面中两只可爱的拟人化猫咪以相同的浪漫姿态站在船头。公猫是一只橙色虎斑猫，身穿背心，站在一位长发白猫身后，后者身着蕾丝长裙，双爪向前伸展，随风飘动。两只猫咪均采用写实风格，毛发细节丰富，毛发随风飘扬，背景灯光营造出戏剧性的日落效果（暖金色高光与冷蓝色阴影）。背景为黄昏时分的泰坦尼克号，四座烟囱、闪烁的甲板灯、平静的海洋以及橙粉相间的夕阳天空。中央标题为“CATANIC”，采用与《泰坦尼克号》相同的金色金属衬线字体，大小和位置一致。\"}","callBackUrl":"https://your-domain.com/api/callback","model":"grok-imagine/image-to-image"}。
  data.resultJsonstring否图片生成结果，JSON 字符串格式。resultUrls 为生成图片的 URL 列表。仅在 state 为 success 时出现。 示例：{"resultUrls":["https://tempfile.aiquickdraw.com/g/users/9a2eef47-0997-4343-8b25-8ff800ae0529/generated/e51cd53b-736a-4742-858b-f2b8fbe5998a/image.jpg"]}。
  data.statestring否任务状态 可选值：success / fail。 示例：success。
  data.taskIdstring否任务 ID 示例：9c6b5b687460e9fc898baff13649c2cf。
  data.updateTimeinteger否完成时间请以 completeTime 为准；updateTime 可能与 createTime 相同。 示例：1786431871000。
  data.failCodestring否失败码，数字字符串，如 "400"、"500"。仅在 state 为 fail 时出现。 示例：500。
  data.failMsgstring否失败原因，仅在 state 为 fail 时出现。 示例：&lt;error detail&gt;。

任务成功

json
{
  "code": 200,
  "msg": "Playground task completed successfully.",
  "data": {
    "taskId": "9c6b5b687460e9fc898baff13649c2cf",
    "model": "grok-imagine/image-to-image",
    "state": "success",
    "param": "{\"input\":\"{\\\"image_urls\\\":[\\\"https://static.aiquickdraw.com/tools/example/1767602105243_0MmMCrwq.png\\\"],\\\"prompt\\\":\\\"重现《泰坦尼克号》电影海报，画面中两只可爱的拟人化猫咪以相同的浪漫姿态站在船头。公猫是一只橙色虎斑猫，身穿背心，站在一位长发白猫身后，后者身着蕾丝长裙，双爪向前伸展，随风飘动。两只猫咪均采用写实风格，毛发细节丰富，毛发随风飘扬，背景灯光营造出戏剧性的日落效果（暖金色高光与冷蓝色阴影）。背景为黄昏时分的泰坦尼克号，四座烟囱、闪烁的甲板灯、平静的海洋以及橙粉相间的夕阳天空。中央标题为“CATANIC”，采用与《泰坦尼克号》相同的金色金属衬线字体，大小和位置一致。\\\"}\",\"callBackUrl\":\"https://your-domain.com/api/callback\",\"model\":\"grok-imagine/image-to-image\"}",
    "resultJson": "{\"resultUrls\":[\"https://tempfile.aiquickdraw.com/g/users/9a2eef47-0997-4343-8b25-8ff800ae0529/generated/e51cd53b-736a-4742-858b-f2b8fbe5998a/image.jpg\"]}",
    "costTime": 11,
    "createTime": 1786431859000,
    "completeTime": 1786431871000,
    "updateTime": 1786431871000,
    "creditsConsumed": 4
  }
}

任务失败

json
{
  "code": 501,
  "msg": "Playground task failed.",
  "data": {
    "taskId": "9c6b5b687460e9fc898baff13649c2cf",
    "model": "grok-imagine/image-to-image",
    "state": "fail",
    "param": "{\"input\":\"{\\\"image_urls\\\":[\\\"https://static.aiquickdraw.com/tools/example/1767602105243_0MmMCrwq.png\\\"],\\\"prompt\\\":\\\"重现《泰坦尼克号》电影海报，画面中两只可爱的拟人化猫咪以相同的浪漫姿态站在船头。公猫是一只橙色虎斑猫，身穿背心，站在一位长发白猫身后，后者身着蕾丝长裙，双爪向前伸展，随风飘动。两只猫咪均采用写实风格，毛发细节丰富，毛发随风飘扬，背景灯光营造出戏剧性的日落效果（暖金色高光与冷蓝色阴影）。背景为黄昏时分的泰坦尼克号，四座烟囱、闪烁的甲板灯、平静的海洋以及橙粉相间的夕阳天空。中央标题为“CATANIC”，采用与《泰坦尼克号》相同的金色金属衬线字体，大小和位置一致。\\\"}\",\"callBackUrl\":\"https://your-domain.com/api/callback\",\"model\":\"grok-imagine/image-to-image\"}",
    "costTime": 11,
    "createTime": 1786431859000,
    "completeTime": 1786431871000,
    "updateTime": 1786431871000,
    "creditsConsumed": 0,
    "failCode": "500",
    "failMsg": "<error detail>"
  }
}

ModelFold — 一个 API，接入所有主流 AI 模型。

© 2026 ModelFold