跳至正文
EN
获取 API Key
☰

Grok Imagine API 接入文档

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

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

获取任务详情

GET/api/v1/jobs/recordInfo

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

参数位置类型
taskId *querystring
请求示例
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).

可选值：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.

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.

可选值："waiting", "queuing", "generating", "success", "fail"

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 视频

POST/api/v1/jobs/createTask

模型标识： grok-imagine/extend

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

用于生成的模型名称。必填字段。 - 此端点必须使用 `grok-imagine/extend`

可选值："grok-imagine/extend"

默认："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

maxLength: 100

input.prompt
必填		string

描述所需视频运动的文本提示。必填字段。 - 详细描述您希望视频如何扩展和延续 - 可以指定镜头运动、场景变化、物体动作等 - 提示词越具体，生成效果越符合预期 - 支持中英文输入

input.extend_at
必填		number

必填。源视频中开始续写的时间点，单位秒，最小 2。

默认：2

minimum: 2

input.extend_times
必填		string

6 或 10（秒）。

可选值："6", "10"

默认："6"

请求示例
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).

可选值：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 图生图

POST/api/v1/jobs/createTask

模型标识： grok-imagine/image-to-image

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

用于生成任务的模型名称。必填字段。 - 此端点必须为 `grok-imagine/image-to-image`

可选值："grok-imagine/image-to-image"

默认："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 个字符）

maxLength: 390000

input.image_urls
必填		array

1~5 张图片 URL（须为上传后的文件地址，而非文件本体）。支持类型：image/jpeg、image/png、image/webp；单张最大 10.0MB。在文本提示中可通过输入 @image(n) 并在其后加空格来引用该参考图（例如：@image1 海边日落）。

maxItems: 5

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).

可选值：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 图生视频

POST/api/v1/jobs/createTask

模型标识： grok-imagine/image-to-video

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

用于生成的模型名称。必填字段。 - 此端点必须使用 `grok-imagine/image-to-video`

可选值："grok-imagine/image-to-video"

默认："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时只支持一张。

maxItems: 7

input.task_id
可选		string

之前生成的 Grok 图像的任务 ID。与 index 配合使用选择特定图像，不要与 image_urls 同时使用。 - 使用 grok-imagine/text-to-image 生成的任务 ID - 支持所有模式，包括 Spicy - 最大长度：100 字符

maxLength: 100

input.index
可选		integer

使用 task_id 时，指定使用第几张图（从 0 开始）。grok-imagine/text-to-image 每个任务返回 2 张，所以取值为 0 或 1，默认 0。 - 如果提供了 image_urls 则忽略此参数

默认：0

minimum: 0

maximum: 1

input.prompt
可选		string

描述期望视频运动的文本提示。可选字段。 - 应该对期望的视觉运动详细具体 - 描述运动、动作序列、摄影工作和时间安排 - 包含主体、环境和运动动态的细节 - 最大长度：5000 字符 - 支持英文提示

input.mode
可选		string

指定影响运动风格和强度的生成模式。注意：外部图像输入不支持 Spicy 模式。 - **fun**: 更有创意和趣味的解读 - **normal**: 平衡方法，具有良好的运动质量 - **spicy**: 更有活力和强烈的运动效果（外部图像不可用） 默认值：normal

可选值："fun", "normal", "spicy"

默认："normal"

input.duration
可选		number

生成的视频时长（秒）（6-30）。（最小值：6，最大值：30，步长：1）

input.resolution
可选		string

生成视频的分辨率。

可选值："480p", "720p", "1080p"

默认："480p"

input.aspect_ratio
可选		string

图像比例选择，仅适用于多图生成模式，单图模式下视频宽高参考图片宽高。

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

默认："16:9"

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).

可选值：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 文生图

POST/api/v1/jobs/createTask

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

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

用于生成的模型名称。必填字段。 - 此端点必须使用 `grok-imagine/text-to-image`

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

默认："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。

可选值："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).

可选值：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 文生视频

POST/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

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

input.mode
可选		string

指定影响运动风格和强度的生成模式。 - **fun**: 更有创意和趣味的解读 - **normal**: 平衡方法，具有良好的运动质量 - **spicy**: 更有活力和强烈的运动效果 默认值：normal

可选值："fun", "normal", "spicy"

input.duration
可选		number

生成的视频时长（秒）（6-30）。（最小值：6，最大值：30，步长：1）

input.resolution
可选		string

生成视频的分辨率。

可选值："480p", "720p", "1080p"

默认："480p"

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).

可选值：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 视频

POST/api/v1/jobs/createTask

模型标识： grok-imagine/upscale

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

用于生成的模型名称。必填字段。 - 此端点必须使用 `grok-imagine/upscale`

可选值："grok-imagine/upscale"

默认："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

maxLength: 100

input.resolution
可选		string

视频生成的分辨率。

可选值："720p", "1080p"

请求示例
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).

可选值：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 结算。用量不明时暂停新付费请求。若保护其他任务预留后余额不足以结算，会保留待结算记录，补足余额后再扣费；模型用量不会将钱包扣成负数。按时长计价的输入文件由服务端读取时长，读取失败时不提交模型任务。