Grok Imagine API
Grok Imagine API 的模型能力、计价规格、请求参数和接入示例。使用 VezAPI 账号密钥统一接入。
Grok Imagine API 接入文档
使用 VezAPI 密钥接入 Grok Imagine。下列操作共用同一个账号余额和鉴权方式。
https://api.vezapi.com请求头使用 Authorization: Bearer YOUR_VEZAPI_KEY。每次提交使用唯一的 Idempotency-Key,查询同一笔提交时才复用。
获取任务详情
/api/v1/jobs/recordInfo模型标识: grok-imagine/text-to-image
| 参数 | 位置 | 类型 |
|---|---|---|
taskId * | query | string |
请求示例
curl -X GET 'https://api.vezapi.com/api/v1/jobs/recordInfo?taskId=YOUR_TASK_ID' \
-H 'Authorization: Bearer YOUR_VEZAPI_KEY'返回值与错误
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). 可选值: |
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. |
data.model可选 | string | The model used for this task (e.g., grok-imagine/text-to-image, seedream-4.0, kling-1.0) |
data.state可选 | string | Current state of the task. Check state to determine the outcome. 可选值: |
data.param可选 | string | JSON string containing the original request parameters used to create the task. Its `input` is itself a JSON string — parse it twice. |
data.resultJson可选 | string | Result JSON string. Present when state is success; on failure it may be null or an empty string. The structure is as follows: - For images/media/videos: {resultUrls: []} - If return_last_frame is enabled on Seedance 2.x models: {resultUrls: [], lastFrameUrl: []} - For text output: {resultObject: {}} For OmniHuman series models: - OmniHuman 1.5 Subject Detection (subject detection model): response structure is {resultObject: {mask_urls: ["url1", "url2", ...]}}, returning a list of mask image URLs corresponding to the detected subjects. The URLs returned by this model are valid for 1 hour. - OmniHuman 1.5 Human Identification (human identification model): response structure is {resultObject: {subject_status: 1}}, where `subject_status` means 0 = no subject detected, 1 = subject detected, indicating whether a human subject is detected in the image. |
data.response可选 | object | Parsed form of resultJson. Present only when state is success. |
data.failCode可选 | string | Failure code (numeric string, e.g. "500"). Present when state is fail; on success it may be null or an empty string. |
data.failMsg可选 | string | Failure reason. Present when state is fail; on success it may be null or an empty string. |
data.costTime可选 | integer | Processing time in seconds. Present for both successful and failed tasks. |
data.completeTime可选 | integer | Completion timestamp (Unix timestamp in milliseconds) |
data.createTime可选 | integer | Creation timestamp (Unix timestamp in milliseconds) |
data.creditsConsumed可选 | number | Credit consumption details for this task, indicating the actual number of credits deducted during task execution. |
HTTP 401
未授权 - API密钥无效或缺失
| 参数 | 类型 | 说明与限制 |
|---|---|---|
code必填 | integer | |
msg必填 | string |
HTTP 422
响应字段与业务状态码。
| 参数 | 类型 | 说明与限制 |
|---|---|---|
code必填 | integer | |
msg必填 | string | |
data必填 | null |
HTTP 429
速率限制 - 请求过于频繁
| 参数 | 类型 | 说明与限制 |
|---|---|---|
code必填 | integer | |
msg必填 | string |
HTTP 500
服务器错误
扩展 Grok Imagine 视频
/api/v1/jobs/createTask模型标识: grok-imagine/extend
| 参数 | 类型 | 说明与限制 |
|---|---|---|
model必填 | string | 用于生成的模型名称。必填字段。 - 此端点必须使用 `grok-imagine/extend` 可选值: 默认: |
callBackUrl可选 | string | 接收视频扩展任务完成更新的 URL。可选但建议在生产环境中使用。 - 当视频扩展完成时,系统将向此 URL POST 任务状态和结果 - 回调包含生成的续写视频 URL 和任务信息 - 您的回调端点应接受包含视频结果的 JSON 负载的 POST 请求 - 或者,使用获取任务详情端点轮询任务状态 - 为确保回调安全性,请参阅 [Webhook 校验指南](/cn/common-api/webhook-verification) 了解签名验证实现方法 |
input必填 | object | 视频扩展任务的输入参数 |
input.task_id必填 | string | 之前成功的视频生成任务的任务 ID。必填字段。 - task_id 须为成功的 grok-imagine/text-to-video 或 grok-imagine/image-to-video 任务。 - 原始视频生成必须成功完成 - 最大长度:100 字符 - 仅支持 VezAPI AI 生成的任务 ID
|
input.prompt必填 | string | 描述所需视频运动的文本提示。必填字段。 - 详细描述您希望视频如何扩展和延续 - 可以指定镜头运动、场景变化、物体动作等 - 提示词越具体,生成效果越符合预期 - 支持中英文输入 |
input.extend_at必填 | number | 必填。源视频中开始续写的时间点,单位秒,最小 2。 默认:
|
input.extend_times必填 | string | 6 或 10(秒)。 可选值: 默认: |
请求示例
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/extend",
"callBackUrl": "https://example.com/input.png",
"input": {
"task_id": "task_grok_12345678"
}
}'返回值与错误
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). 可选值: |
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 图生图
/api/v1/jobs/createTask模型标识: grok-imagine/image-to-image
| 参数 | 类型 | 说明与限制 |
|---|---|---|
model必填 | string | 用于生成任务的模型名称。必填字段。 - 此端点必须为 `grok-imagine/image-to-image` 可选值: 默认: |
callBackUrl可选 | string | 接收生成任务完成更新的 URL。可选但建议在生产环境中使用。 - 系统将在生成完成时向此 URL 发送 POST 请求 - 回调包含生成的内容 URL 和任务信息 - 您的回调端点应接受包含结果的 JSON 负载的 POST 请求 - 或者,使用获取任务详情端点来轮询任务状态 - 为确保回调安全性,请参阅 [Webhook 校验指南](/cn/common-api/webhook-verification) 了解签名验证实现方法 |
input可选 | object | 生成任务的输入参数 |
input.prompt可选 | string | 指定生成图像所需内容或样式的文本描述。(最大长度:390000 个字符)
|
input.image_urls必填 | array | 1~5 张图片 URL(须为上传后的文件地址,而非文件本体)。支持类型:image/jpeg、image/png、image/webp;单张最大 10.0MB。在文本提示中可通过输入 @image(n) 并在其后加空格来引用该参考图(例如:@image1 海边日落)。
|
input.nsfw_checker可选 | boolean | 默认 false。为 false 时不额外进行内容过滤,结果由模型直接返回。 |
请求示例
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-to-image",
"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://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). 可选值: |
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 图生视频
/api/v1/jobs/createTask模型标识: grok-imagine/image-to-video
| 参数 | 类型 | 说明与限制 |
|---|---|---|
model必填 | string | 用于生成的模型名称。必填字段。 - 此端点必须使用 `grok-imagine/image-to-video` 可选值: 默认: |
callBackUrl可选 | string | 接收视频生成任务完成更新的 URL。可选但建议在生产环境中使用。 - 当视频生成完成时,系统将向此 URL POST 任务状态和结果 - 回调包含生成的视频 URL 和任务信息 - 您的回调端点应接受包含视频结果的 JSON 负载的 POST 请求 - 或者,使用获取任务详情端点轮询任务状态 |
input必填 | object | 视频生成任务的输入参数 |
input.image_urls可选 | array | 提供一个外部图像 URL 作为视频生成的参考。支持最多7个图像,不要与 task_id 同时使用。在提示词中引用已上传图片时,请输入 @image(n),并在其后加一个空格(例如:@image1 海边日落)。 - 支持 JPEG、PNG、WEBP 格式 - 每张图像最大文件大小:10MB - 使用外部图像时 Spicy 模式不可用 - 数组最多包含七个 URL - resolution为1080p时只支持一张。
|
input.task_id可选 | string | 之前生成的 Grok 图像的任务 ID。与 index 配合使用选择特定图像,不要与 image_urls 同时使用。 - 使用 grok-imagine/text-to-image 生成的任务 ID - 支持所有模式,包括 Spicy - 最大长度:100 字符
|
input.index可选 | integer | 使用 task_id 时,指定使用第几张图(从 0 开始)。grok-imagine/text-to-image 每个任务返回 2 张,所以取值为 0 或 1,默认 0。 - 如果提供了 image_urls 则忽略此参数 默认:
|
input.prompt可选 | string | 描述期望视频运动的文本提示。可选字段。 - 应该对期望的视觉运动详细具体 - 描述运动、动作序列、摄影工作和时间安排 - 包含主体、环境和运动动态的细节 - 最大长度:5000 字符 - 支持英文提示 |
input.mode可选 | string | 指定影响运动风格和强度的生成模式。注意:外部图像输入不支持 Spicy 模式。 - **fun**: 更有创意和趣味的解读 - **normal**: 平衡方法,具有良好的运动质量 - **spicy**: 更有活力和强烈的运动效果(外部图像不可用) 默认值:normal 可选值: 默认: |
input.duration可选 | number | 生成的视频时长(秒)(6-30)。(最小值:6,最大值:30,步长:1) |
input.resolution可选 | string | 生成视频的分辨率。 可选值: 默认: |
input.aspect_ratio可选 | string | 图像比例选择,仅适用于多图生成模式,单图模式下视频宽高参考图片宽高。 可选值: 默认: |
input.nsfw_checker可选 | boolean | 默认 false。为 false 时不额外进行内容过滤,结果由模型直接返回。 |
请求示例
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-to-video",
"callBackUrl": "https://example.com/input.png",
"input": {
"image_urls": [
"https://example.com/input.png"
],
"prompt": "POV hand comes into frame handing the girl a cup of take away coffee, the girl steps out of the screen looking tired, then takes it and she says happily: \"thanks! Back to work\" she exits the frame and walks right to a different part of the office.",
"mode": "normal"
}
}'返回值与错误
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). 可选值: |
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 文生图
/api/v1/jobs/createTask模型标识: grok-imagine/text-to-image
| 参数 | 类型 | 说明与限制 |
|---|---|---|
model必填 | string | 用于生成的模型名称。必填字段。 - 此端点必须使用 `grok-imagine/text-to-image` 可选值: 默认: |
callBackUrl可选 | string | 接收图像生成任务完成更新的 URL。可选但建议在生产环境中使用。 - 当图像生成完成时,系统将向此 URL POST 任务状态和结果 - 回调包含生成的图像 URL 和任务信息 - 您的回调端点应接受包含图像结果的 JSON 负载的 POST 请求 - 或者,使用获取任务详情端点轮询任务状态 - 为确保回调安全性,请参阅 [Webhook 校验指南](/cn/common-api/webhook-verification) 了解签名验证实现方法 |
input必填 | object | 图像生成任务的输入参数 |
input.prompt必填 | string | 描述期望图像的文本提示。必填字段。 - 应该对期望的视觉元素详细具体 - 描述构图、风格、光线、情绪和其他视觉细节 - 最大长度:5000 字符 - 支持英文提示 |
input.aspect_ratio必填 | string | 必填。输出图片宽高比:2:3、3:2、1:1、16:9、9:16。 可选值: |
input.enable_pro可选 | boolean | 控制请求的处理策略。 - `false`:对应 `speed` 模式,系统优先优化响应速度与吞吐量,适用于对延迟敏感的场景。 - `true`:对应 `quality` 模式,系统优先保障任务处理质量与精度,适用于对结果要求较高的场景。 |
input.nsfw_checker可选 | boolean | 默认 false。为 false 时不额外进行内容过滤,结果由模型直接返回。 |
请求示例
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/text-to-image",
"callBackUrl": "https://example.com/input.png",
"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"
}
}'返回值与错误
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). 可选值: |
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 文生视频
/api/v1/jobs/createTask模型标识: grok-imagine/text-to-video
| 参数 | 类型 | 说明与限制 |
|---|---|---|
model必填 | string | 用于生成的模型名称。必填字段。 - 此端点必须使用 `grok-imagine/text-to-video` |
callBackUrl可选 | string | 接收视频生成任务完成更新的 URL。可选但建议在生产环境中使用。 - 当视频生成完成时,系统将向此 URL POST 任务状态和结果 - 回调包含生成的视频 URL 和任务信息 - 您的回调端点应接受包含视频结果的 JSON 负载的 POST 请求 - 或者,使用获取任务详情端点轮询任务状态 |
input必填 | object | 视频生成任务的输入参数 |
input.prompt必填 | string | 描述期望视频运动的文本提示。必填字段。 - 应该对期望的视觉运动详细具体 - 描述运动、动作序列、摄影工作和时间安排 - 包含主体、环境和运动动态的细节 - 最大长度:5000 字符 - 支持英文提示 |
input.aspect_ratio可选 | string | 指定生成视频的宽高比。控制输出的宽高比。 - **2:3**: 竖向(垂直) - **3:2**: 横向(水平) - **1:1**: 正方形 - **16:9**: 宽屏 - **9:16**: 竖屏 默认值:2:3 可选值: |
input.mode可选 | string | 指定影响运动风格和强度的生成模式。 - **fun**: 更有创意和趣味的解读 - **normal**: 平衡方法,具有良好的运动质量 - **spicy**: 更有活力和强烈的运动效果 默认值:normal 可选值: |
input.duration可选 | number | 生成的视频时长(秒)(6-30)。(最小值:6,最大值:30,步长:1) |
input.resolution可选 | string | 生成视频的分辨率。 可选值: 默认: |
input.nsfw_checker可选 | boolean | 默认 false。为 false 时不额外进行内容过滤,结果由模型直接返回。 |
请求示例
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/text-to-video",
"callBackUrl": "https://example.com/input.png",
"input": {
"prompt": "A couple of doors open to the right one by one randomly and stay open, to show the inside, each is either a living room, or a kitchen, or a bedroom or an office, with little people living inside.",
"aspect_ratio": "2:3",
"mode": "normal"
}
}'返回值与错误
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). 可选值: |
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 视频
/api/v1/jobs/createTask模型标识: grok-imagine/upscale
| 参数 | 类型 | 说明与限制 |
|---|---|---|
model必填 | string | 用于生成的模型名称。必填字段。 - 此端点必须使用 `grok-imagine/upscale` 可选值: 默认: |
callBackUrl可选 | string | 接收视频放大任务完成更新的 URL。可选但建议在生产环境中使用。 - 当视频放大完成时,系统将向此 URL POST 任务状态和结果 - 回调包含生成的放大视频 URL 和任务信息 - 您的回调端点应接受包含视频结果的 JSON 负载的 POST 请求 - 或者,使用获取任务详情端点轮询任务状态 - 为确保回调安全性,请参阅 [Webhook 校验指南](/cn/common-api/webhook-verification) 了解签名验证实现方法 |
input必填 | object | 视频放大任务的输入参数 |
input.task_id必填 | string | task_id 须为成功的 grok-imagine/text-to-video 或 grok-imagine/image-to-video 任务。必填。 - 原始视频生成必须成功完成 - 最大长度:100 字符 - 仅支持 VezAPI AI 生成的任务 ID
|
input.resolution可选 | string | 视频生成的分辨率。 可选值: |
请求示例
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/upscale",
"callBackUrl": "https://example.com/input.png",
"input": {
"task_id": "task_grok_12345678"
}
}'返回值与错误
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). 可选值: |
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 结算。用量不明时暂停新付费请求。若保护其他任务预留后余额不足以结算,会保留待结算记录,补足余额后再扣费;模型用量不会将钱包扣成负数。按时长计价的输入文件由服务端读取时长,读取失败时不提交模型任务。
使用你的 VezAPI 密钥发送请求。成功生成将消耗账号积分。
/api/v1/jobs/createTask返回结果将在这里显示。
Grok Imagine API 价格
下方费率为参考估算,最终按实际优惠扣分 1:1 结算。按标准充值包换算,1,000 积分约为 10 美元,大额充值包可降低每积分实际单价。
| 规格 | 积分 | 计价单位 | 美元参考 |
|---|---|---|---|
| grok-imagine/extend, 10s 720p | 45 | 每个视频 | $0.45 |
| grok-imagine/extend, 10s 480p | 24 | 每个视频 | $0.24 |
| grok-imagine/extend, 6s 720p | 27 | 每个视频 | $0.27 |
| grok-imagine/extend, 6s 480p | 14.4 | 每个视频 | $0.144 |
| grok-imagine, upscale, 720P → 1080P | 20 | 每次放大 | $0.2 |
| grok-imagine, upscale, 480P → 1080P | 30 | 每次放大 | $0.3 |
| grok-imagine, text-to-video, 1080p | 8 | 每秒 | $0.08 |
| grok-imagine, image-to-video, 1080p | 8 | 每秒 | $0.08 |
| grok-imagine, text-to-image(quality) | 5 | 每次生成 | $0.05 |
| grok-imagine, image-to-video, 720p | 4.5 | 每秒 | $0.045 |
| grok-imagine, text-to-video, 720p | 4.5 | 每秒 | $0.045 |
| grok-imagine, image-to-video, 480p | 2.4 | 每秒 | $0.024 |
| grok-imagine, text-to-video, 480p | 2.4 | 每秒 | $0.024 |
| grok-imagine, image-to-image | 4 | 每次生成 | $0.04 |
| grok-imagine, text-to-image | 4.0 | 每两张图片 | $0.04 |
| grok-imagine, upscale, 480p→720p | 10.0 | 每次放大 | $0.1 |