xai/grok-imagine-image/editGrok Imagine Image Edit transforms a reference image through written changes to subjects, backgrounds, and visual style. The source supplies the visual starting point, while the prompt identifies what to change and which details to carry into the result.
Get API Key
Change only the adult roller skater's blue zip-up sports jacket into a warm orange corduroy jacket with clear fine vertical ribs and believable seams. Preserve the same person's face, curly dark hair, exact pose, body proportions, black knee pads, roller skates, railing, rink, daylight and framing. Keep the jacket shape practical and natural. This is a selective clothing material and color edit, not a new scene. No other changes, lettering, logos or promotional elements.
Reinterpret the supplied cargo harbor photograph as a carefully carved three-color woodcut print using only indigo, brick red and warm ivory. Preserve the exact number and placement of the main gantry cranes, the stacks of containers, the quay edge and the perspective. Replace photographic shading with carved directional hatching and confident ink shapes; retain clear mechanical silhouettes and spatial depth. Slight handmade registration texture, no new objects, labels, typography, borders or advertising.
REST API
Submit a request, save task_id, and retrieve the generated file when the task finishes.
Store your API key on the server and send Authorization: Bearer VIDGO_API_KEY.
https://api.vidgo.ai/api/generate/submitSet model and callback_url at the request root. Place the following fields inside input.
curl --request POST \
--url "https://api.vidgo.ai/api/generate/submit" \
--header "Authorization: Bearer $VIDGO_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"model": "xai/grok-imagine-image/edit",
"input": {
"prompt": "Change the background to a blue studio wall and keep the ceramic cup and its handle.",
"size": "1:1",
"image_urls": [
"https://example.com/reference.png"
]
}
}'Poll every 2–5 seconds while status is not_started or running. Stop at finished or failed.
GET https://api.vidgo.ai/api/generate/status/{task_id}Poll every 2–5 seconds while status is not_started or running. Stop at finished or failed.
not_startedrunningfinishedfailed{
"code": 200,
"data": {
"task_id": "example-task-id",
"status": "not_started",
"created_time": "2026-09-27T10:00:00Z"
}
}{
"code": 200,
"data": {
"task_id": "example-task-id",
"status": "finished",
"created_time": "2026-09-27T10:00:00Z",
"files": [
{
"file_url": "https://example.com/result.png",
"file_type": "image"
}
]
}
}Submit a request, save task_id, and retrieve the generated file when the task finishes.
set -euo pipefail
: "${VIDGO_API_KEY:?Set VIDGO_API_KEY in your environment}"
REQUEST_BODY=$(cat <<'JSON'
{
"model": "xai/grok-imagine-image/edit",
"input": {
"prompt": "Change the background to a blue studio wall and keep the ceramic cup and its handle.",
"size": "1:1",
"image_urls": [
"https://example.com/reference.png"
]
}
}
JSON
)
SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
--request POST \
--url "https://api.vidgo.ai/api/generate/submit" \
--header "Authorization: Bearer $VIDGO_API_KEY" \
--header "Content-Type: application/json" \
--data "$REQUEST_BODY")
TASK_ID=$(printf '%s' "$SUBMIT_RESPONSE" | jq -r '.data.task_id // .task_id // empty')
if [ -z "$TASK_ID" ]; then
printf 'Submit response did not include task_id:
%s
' "$SUBMIT_RESPONSE" >&2
exit 1
fi
while true; do
STATUS_RESPONSE=$(curl --silent --show-error --fail-with-body \
--url "https://api.vidgo.ai/api/generate/status/$TASK_ID" \
--header "Authorization: Bearer $VIDGO_API_KEY")
STATUS=$(printf '%s' "$STATUS_RESPONSE" | jq -r '.data.status // .status // empty')
case "$STATUS" in
finished)
printf '%s' "$STATUS_RESPONSE" | jq -r '(.data.files // .files // [])[]?.file_url'
break
;;
failed)
printf '%s' "$STATUS_RESPONSE" | jq -r '.data.error_message // .error_message // "Generation failed"' >&2
exit 1
;;
not_started|running)
sleep 2
;;
*)
printf 'Unexpected task status: %s
' "$STATUS" >&2
exit 1
;;
esac
doneSet model and callback_url at the request root. Place the following fields inside input.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| input.prompt | string | Yes | – | Describe the requested changes and source details to retain. Enter 1–5,000 characters. |
| input.image_urls | string[] | Yes | – | Provide exactly one publicly accessible HTTP(S) image URL. Use JPEG, PNG, or WebP, up to 10 MB. |
| input.size | string | No | – | Choose 1:1, 2:3, 3:2, 16:9, or 9:16. |
The submit response returns task_id. The status response returns generated files or the task error.
| Field | Type | Description |
|---|---|---|
| code | integer | Response code; 0 or 200 indicates success. |
| data.task_id | string | Task identifier for status queries. |
| data.status | string | not_started, running, finished, failed |
| data.created_time | string | Task creation timestamp. |
| data.files[].file_url | string | URL of the generated file. |
| data.files[].file_type | string | image |
| data.error_message | string | null | Reason for a failed task. |
Poll every 2–5 seconds while status is not_started or running. Stop at finished or failed.
not_startedAccepted and queued.
runningGeneration in progress.
finishedRead the generated files.
failedRead error_message and stop polling.
| Specification | Value | Details |
|---|---|---|
| Input | Prompt + Image | Describe the requested changes and source details to retain. Enter 1–5,000 characters. |
| Output | image | Generated image. |
| size | 1:1 · 2:3 · 3:2 · 16:9 · 9:16 | Choose 1:1, 2:3, 3:2, 16:9, or 9:16. |
Grok Imagine Image Edit is an xAI model for editing an existing image with text instructions. It changes subjects, backgrounds, and visual style from a single reference image, with five output aspect ratios. The image supplies the visual starting point, while the instruction identifies both the requested revision and details to retain. You can call it through the API or try it in the Playground tab.
Describe the change and name the source details to retain in the same prompt. For example: “Replace the wall with a blue studio background; keep the ceramic cup, its handle, and its position.” The reference supplies the original visual context.
Yes. Provide the product image and describe the new surroundings, surface, and lighting. Identify the product itself as the subject to retain so the editing instruction distinguishes it from the setting.
Yes. Use the illustration as the reference and name the new medium, palette, or visual treatment. Include the characters, objects, or composition details that should carry into the revised image.
Provide one JPEG, PNG, or WebP image up to 10 MB. In an API request, image_urls contains exactly one publicly accessible HTTP(S) URL; in the Playground, upload that image before running the edit.
Use size to choose 1:1, 2:3, 3:2, 16:9, or 9:16. The selected value sets the output aspect ratio; describe the subject’s desired position as part of the editing instruction.
Choose Grok Imagine Image Edit when you have a source image and a specific revision in mind. Grok Imagine Image Text to Image starts from a written brief and is suited to creating a new visual concept.
