跳至正文
EN
获取 API Key
☰

Grok Imagine Image 2.0 API 接入文档

使用 VezAPI 密钥接入 Grok Imagine Image 2.0。下列操作共用同一个账号余额和鉴权方式。

服务地址： https://api.vezapi.com
请求头使用 Authorization: Bearer YOUR_VEZAPI_KEY。每次提交使用唯一的 Idempotency-Key，查询同一笔提交时才复用。

Grok Imagine Image 2.0 Segment Edit

POST/api/v1/jobs/createTask

模型标识： grok-imagine-image-2-0/segment-edit

参数类型说明与限制
model
必填		string

用于生成任务的模型名称。该字段为必填项。此接口必须使用 `grok-imagine-image-2-0/segment-edit` 模型。

可选值："grok-imagine-image-2-0/segment-edit"

默认："grok-imagine-image-2-0/segment-edit"

callBackUrl
可选		string

任务完成通知的回调 URL。该参数为可选项。如果提供，当任务完成时，无论成功或失败，系统都会向该 URL 发送 POST 请求。如果未提供，则不会发送回调通知。

input
必填		object

Grok Imagine 图像编辑任务的输入参数。

input.prompt
必填		string

描述所需图像的文本提示词。最多 65,000 个字符。

maxLength: 65000

input.task_id
必填		string

用于图像编辑的源任务 ID(可以是根据grok-imagine-image-2-0/text-to-image模型生成的taskid,也可以是grok-imagine-image-2-0/segment-map模型通过传递image_url生成的taskid)。

input.mask_indexs
可选		array

要编辑的分块编号，取自 segment-map 任务结果 resultObject.segments[].index（从 0 开始）。例如 [0, 2]。

minItems: 1

请求示例
curl -X POST 'https://api.vezapi.com/api/v1/jobs/createTask' \
  -H 'Authorization: Bearer YOUR_VEZAPI_KEY' \
  -H 'Idempotency-Key: your-unique-request-id' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "grok-imagine-image-2-0/segment-edit",
  "input": {
    "prompt": "Change the background to a sunset beach while preserving the subject.",
    "task_id": "task_grok_imagine_1234567890"
  }
}'
返回值与错误

HTTP 200

请求成功

参数类型说明与限制
code
可选		integer

Status code of the request. The HTTP status is 200 even when the request fails, so always check this field: 200 means success; any other value means the request failed and msg describes the reason. Common values: 401 invalid or missing API key; 402 insufficient credits; 429 rate limit exceeded; 422 or 500 the request could not be processed (read msg and check your parameters before retrying).

可选值：200, 401, 402, 404, 422, 429, 433, 455, 500, 501, 505

msg
可选		string

Response message, error description upon failure

data
必填		object
data.taskId
必填		string

The task ID can be used with the "Get Task Details" endpoint to query the task status.

Grok Imagine Image 2.0 图片编辑

POST/api/v1/jobs/createTask

模型标识： grok-imagine-image-2-0/image-edit

参数类型说明与限制
model
必填		string

用于生成的模型名称。必填字段。 - 对于此端点，必须为 `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 验证指南](/cn/common-api/webhook-verification) 以了解签名验证的实现

input
可选		object

生成任务的输入参数

input.prompt
可选		string

指定生成图像的所需内容或样式的文本描述。最长 8000 字符。

maxLength: 8000

input.aspect_ratio
必填		string

指定生成图像的宽高比。控制输出的宽高比例。此字段为必填项。

可选值："1:1", "2:3", "3:2", "16:9", "9:16", "auto"

input.image_urls
必填		array

包含最多5张，最少1张指向参考图像的 URL 字符串的数组。

maxItems: 5

请求示例
curl -X POST 'https://api.vezapi.com/api/v1/jobs/createTask' \
  -H 'Authorization: Bearer YOUR_VEZAPI_KEY' \
  -H 'Idempotency-Key: your-unique-request-id' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "grok-imagine-image-2-0/image-edit",
  "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://example.com/input.png"
    ]
  }
}'
返回值与错误

HTTP 200

请求成功

参数类型说明与限制
code
可选		integer

Status code of the request. The HTTP status is 200 even when the request fails, so always check this field: 200 means success; any other value means the request failed and msg describes the reason. Common values: 401 invalid or missing API key; 402 insufficient credits; 429 rate limit exceeded; 422 or 500 the request could not be processed (read msg and check your parameters before retrying).

可选值：200, 401, 402, 404, 422, 429, 433, 455, 500, 501, 505

msg
可选		string

Response message, error description upon failure

data
必填		object
data.taskId
必填		string

The task ID can be used with the "Get Task Details" endpoint to query the task status.

Grok Imagine Image 2.0 Segment Map

POST/api/v1/jobs/createTask

模型标识： grok-imagine-image-2-0/segment-map

参数类型说明与限制
model
必填		string

用于生成任务的模型名称。该字段为必填项。此接口必须使用 `grok-imagine-image-2-0/segment-map` 模型。

可选值："grok-imagine-image-2-0/segment-map"

默认："grok-imagine-image-2-0/segment-map"

callBackUrl
可选		string

任务完成通知的回调 URL。该参数为可选项。如果提供，当任务完成时，无论成功或失败，系统都会向该 URL 发送 POST 请求。如果未提供，则不会发送回调通知。

input
必填		object

图像分割图任务的输入参数。

请求示例
curl -X POST 'https://api.vezapi.com/api/v1/jobs/createTask' \
  -H 'Authorization: Bearer YOUR_VEZAPI_KEY' \
  -H 'Idempotency-Key: your-unique-request-id' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "grok-imagine-image-2-0/segment-map",
  "input": {
    "task_id": "task_grok_imagine_1765180586443"
  }
}'
返回值与错误

HTTP 200

请求成功

参数类型说明与限制
code
可选		integer

Status code of the request. The HTTP status is 200 even when the request fails, so always check this field: 200 means success; any other value means the request failed and msg describes the reason. Common values: 401 invalid or missing API key; 402 insufficient credits; 429 rate limit exceeded; 422 or 500 the request could not be processed (read msg and check your parameters before retrying).

可选值：200, 401, 402, 404, 422, 429, 433, 455, 500, 501, 505

msg
可选		string

Response message, error description upon failure

data
必填		object
data.taskId
必填		string

The task ID can be used with the "Get Task Details" endpoint to query the task status.

Grok Imagine Image 2.0 文生图

POST/api/v1/jobs/createTask

模型标识： grok-imagine-image-2-0/text-to-image

参数类型说明与限制
model
必填		string

用于生成任务的模型名称。该字段为必填项。此接口必须使用 `grok-imagine-image-2-0/text-to-image` 模型。

可选值："grok-imagine-image-2-0/text-to-image"

默认："grok-imagine-image-2-0/text-to-image"

callBackUrl
可选		string

任务完成通知的回调 URL。该参数为可选项。如果提供，当任务完成时，无论成功或失败，系统都会向该 URL 发送 POST 请求。如果未提供，则不会发送回调通知。

input
必填		object

图像生成任务的输入参数。

input.prompt
必填		string

用于描述所需图像的文本提示词。该字段为必填项。最多 8,000 个字符。

maxLength: 8000

input.aspect_ratio
必填		string

指定生成图像的宽高比，用于控制输出图像的画面比例。该字段为必填项。

可选值："1:1", "2:3", "3:2", "16:9", "9:16"

请求示例
curl -X POST 'https://api.vezapi.com/api/v1/jobs/createTask' \
  -H 'Authorization: Bearer YOUR_VEZAPI_KEY' \
  -H 'Idempotency-Key: your-unique-request-id' \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "grok-imagine-image-2-0/text-to-image",
  "input": {
    "prompt": "A small wooden cabin beside a calm lake at sunrise, soft mist over the water",
    "aspect_ratio": "1:1"
  }
}'
返回值与错误

HTTP 200

请求成功

参数类型说明与限制
code
可选		integer

Status code of the request. The HTTP status is 200 even when the request fails, so always check this field: 200 means success; any other value means the request failed and msg describes the reason. Common values: 401 invalid or missing API key; 402 insufficient credits; 429 rate limit exceeded; 422 or 500 the request could not be processed (read msg and check your parameters before retrying).

可选值：200, 401, 402, 404, 422, 429, 433, 455, 500, 501, 505

msg
可选		string

Response message, error description upon failure

data
必填		object
data.taskId
必填		string

The task ID can be used with the "Get Task Details" endpoint to query the task status.

任务状态与回调

异步任务请保存返回的 taskId。调用 GET /api/v1/jobs/recordInfo?taskId=... 查询，或在创建时设置 callBackUrl。只有任务所属账号可以查询任务或基于任务创建派生资源。

超时可能表示请求已经受理。请在控制台查看原请求，不要自动新建任务。回调可能重试并重复到达，请使用 X-VezAPI-Event-Id 去重。

文件、日志与计费

生成媒体通常随上游保留 14 天，上传文件在 24 小时后失效。请在过期前保存所需文件。VezAPI 仅流式转发已登记资源，不提供永久作品库。请求日志保留两个自然月。

调用前预留积分，最终按实际优惠扣分 1:1 结算。用量不明时暂停新付费请求。若保护其他任务预留后余额不足以结算，会保留待结算记录，补足余额后再扣费；模型用量不会将钱包扣成负数。按时长计价的输入文件由服务端读取时长，读取失败时不提交模型任务。