Grok Imagine 文生图

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

接口

POST /jobs/createTask

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

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

查询任务状态

提交任务后，可通过统一的查询端点查看任务进度并获取生成结果：

• 获取任务详情 — 了解如何查询任务状态并获取生成结果

TIP

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

相关资源

• 市场概览 — 浏览所有可用模型
• 通用 API — 查看账户积分与使用情况

请求参数

请求体 (application/json)

参数	类型	必填	说明
model	string	是	用于生成的模型名称。必填字段。 - 此端点必须使用 grok-imagine/text-to-image 默认值："grok-imagine/text-to-image"。 可选值：grok-imagine/text-to-image。 示例：grok-imagine/text-to-image。
callBackUrl	string	否	接收图像生成任务完成更新的 URL。可选但建议在生产环境中使用。 - 当图像生成完成时，系统将向此 URL POST 任务状态和结果 - 回调包含生成的图像 URL 和任务信息 - 您的回调端点应接受包含图像结果的 JSON 负载的 POST 请求 - 或者，使用获取任务详情端点轮询任务状态 - 为确保回调安全性，请参阅 Webhook 校验指南 了解签名验证实现方法 示例：https://your-domain.com/api/callback。
input	object	是	图像生成任务的输入参数
input.prompt	string	是	描述期望图像的文本提示。必填字段。 - 应该对期望的视觉元素详细具体 - 描述构图、风格、光线、情绪和其他视觉细节 - 最大长度：5000 字符 - 支持英文提示 示例：一位女性坐在黑胶唱片机旁的电影肖像，复古客厅背景，柔和的环境照明，温暖的大地色调，怀旧的1970年代服装，沉思的情绪，柔和的胶片颗粒纹理，浅景深，复古编辑摄影风格。。
input.aspect_ratio	string	是	必填。输出图片宽高比：2:3、3:2、1:1、16:9、9:16。 可选值：2:3 / 3:2 / 1:1 / 16:9 / 9:16。 示例：3:2。
input.enable_pro	boolean	否	控制请求的处理策略。 - false：对应 speed 模式，系统优先优化响应速度与吞吐量，适用于对延迟敏感的场景。 - true：对应 quality 模式，系统优先保障任务处理质量与精度，适用于对结果要求较高的场景。
input.nsfw_checker	boolean	否	默认 false。为 false 时不额外进行内容过滤，结果由模型直接返回。

请求示例

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/text-to-image",
  "callBackUrl": "https://your-domain.com/api/callback",
  "input": {
    "prompt": "Cinematic portrait of a woman sitting by a vinyl record player, retro living room background, soft ambient lighting, warm earthy tones, nostalgic 1970s wardrobe, reflective mood, gentle film grain texture, shallow depth of field, vintage editorial photography style.",
    "aspect_ratio": "3:2"
  }
}'

{
  "model": "grok-imagine/text-to-image",
  "callBackUrl": "https://your-domain.com/api/callback",
  "input": {
    "prompt": "Cinematic portrait of a woman sitting by a vinyl record player, retro living room background, soft ambient lighting, warm earthy tones, nostalgic 1970s wardrobe, reflective mood, gentle film grain texture, shallow depth of field, vintage editorial photography style.",
    "aspect_ratio": "3:2"
  }
}

响应

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 与“获取任务详细信息”端点一起查询任务状态。

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "task_grok_12345678"
  }
}

回调

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 毫秒时间戳 示例：1786431088000。
data.costTime	integer	否	处理耗时（秒），成功和失败回调都会返回。 示例：17。
data.createTime	integer	否	任务创建时间，Unix 毫秒时间戳 示例：1786431068000。
data.creditsConsumed	number	否	本任务消耗的积分；失败任务为 0。 示例：4。
data.model	string	否	图片生成使用的模型 示例：grok-imagine/text-to-image。
data.param	string	否	创建任务时提交的参数，JSON 字符串格式 示例：{"input":"{\"aspect_ratio\":\"3:2\",\"prompt\":\"Cinematic portrait of a woman sitting by a vinyl record player,retro living room background, soft ambient lighting, warm earthy tones, nostalgic 1970s wardrobe, reflective mood, gentle film grain texture,shallow depth of field, vintage editorial photography style.\"}","callBackUrl":"https://your-domain.com/api/callback","model":"grok-imagine/text-to-image"}。
data.resultJson	string	否	图片生成结果，JSON 字符串格式。resultUrls 为生成图片的 URL 列表。仅在 state 为 success 时出现。 示例：{"resultUrls":["https://tempfile.aiquickdraw.com/r/18f680df-66a2-4bab-8f2b-91b77ac31fa8.jpg","https://tempfile.aiquickdraw.com/r/80a6536a-43db-4d93-ba18-342bdb3de36b.jpg"]}。
data.state	string	否	任务状态 可选值：success / fail。 示例：success。
data.taskId	string	否	任务 ID 示例：91b9645a0c7d7aa063d18918204bd2ad。
data.updateTime	integer	否	完成时间请以 completeTime 为准；updateTime 可能与 createTime 相同。 示例：1786431088000。
data.failCode	string	否	失败码，数字字符串，如 "400"、"500"。仅在 state 为 fail 时出现。 示例：500。
data.failMsg	string	否	失败原因，仅在 state 为 fail 时出现。 示例：<error detail>。

任务成功

{
  "code": 200,
  "msg": "Playground task completed successfully.",
  "data": {
    "taskId": "91b9645a0c7d7aa063d18918204bd2ad",
    "model": "grok-imagine/text-to-image",
    "state": "success",
    "param": "{\"input\":\"{\\\"aspect_ratio\\\":\\\"3:2\\\",\\\"prompt\\\":\\\"Cinematic portrait of a woman sitting by a vinyl record player,retro living room background, soft ambient lighting, warm earthy tones, nostalgic 1970s wardrobe, reflective mood, gentle film grain texture,shallow depth of field, vintage editorial photography style.\\\"}\",\"callBackUrl\":\"https://your-domain.com/api/callback\",\"model\":\"grok-imagine/text-to-image\"}",
    "resultJson": "{\"resultUrls\":[\"https://tempfile.aiquickdraw.com/r/18f680df-66a2-4bab-8f2b-91b77ac31fa8.jpg\",\"https://tempfile.aiquickdraw.com/r/80a6536a-43db-4d93-ba18-342bdb3de36b.jpg\"]}",
    "costTime": 17,
    "createTime": 1786431068000,
    "completeTime": 1786431088000,
    "updateTime": 1786431088000,
    "creditsConsumed": 4
  }
}

任务失败

{
  "code": 501,
  "msg": "Playground task failed.",
  "data": {
    "taskId": "91b9645a0c7d7aa063d18918204bd2ad",
    "model": "grok-imagine/text-to-image",
    "state": "fail",
    "param": "{\"input\":\"{\\\"aspect_ratio\\\":\\\"3:2\\\",\\\"prompt\\\":\\\"Cinematic portrait of a woman sitting by a vinyl record player,retro living room background, soft ambient lighting, warm earthy tones, nostalgic 1970s wardrobe, reflective mood, gentle film grain texture,shallow depth of field, vintage editorial photography style.\\\"}\",\"callBackUrl\":\"https://your-domain.com/api/callback\",\"model\":\"grok-imagine/text-to-image\"}",
    "costTime": 17,
    "createTime": 1786431068000,
    "completeTime": 1786431088000,
    "updateTime": 1786431088000,
    "creditsConsumed": 0,
    "failCode": "500",
    "failMsg": "<error detail>"
  }
}