Animate the reference as one quiet continuous six-second wildlife shot. The same pangolin slowly raises its small head to sniff the damp air; its long scaled tail makes a slight natural movement without changing shape. One droplet falls from a bamboo leaf near it. Preserve the pangolin's anatomy, scale pattern, position and the bamboo forest composition. Subtle breathing and gentle background leaf motion, soft overcast light, locked camera, no walking away, no extra limbs, no transformation, no cuts or text.
Grok Imagine Video Image to Video API
xai/grok-imagine-video/image-to-videoGrok Imagine Video Image to Video turns a still image into a short clip with text-directed subject action and camera movement. The reference establishes the scene’s appearance, while the motion prompt guides how that scene develops over the selected duration.
Get API Key579/5000
1/1
OutputReady
Continue with
Examples
REST API
Quick Start
Submit a request, save task_id, and retrieve the generated file when the task finishes.
01
Connect to Vidgo API
Store your API key on the server and send Authorization: Bearer VIDGO_API_KEY.
- Endpoint
- POST
https://api.vidgo.ai/api/generate/submit - Authentication
- Authorization: Bearer VIDGO_API_KEY
02
Submit a generation task
Set model and callback_url at the request root. Place the following fields inside input.
Submit request
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-video/image-to-video",
"input": {
"prompt": "Keep the cup centered. Add gently rising steam while the camera slowly moves closer.",
"duration": 6,
"mode": "normal",
"image_urls": [
"https://example.com/reference.png"
]
}
}'03
Retrieve the result
Poll every 2–5 seconds while status is not_started or running. Stop at finished or failed.
Track status
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_startedrunningfinishedfailedSubmit response
{
"code": 200,
"data": {
"task_id": "example-task-id",
"status": "not_started",
"created_time": "2026-09-27T10:00:00Z"
}
}Finished response
{
"code": 200,
"data": {
"task_id": "example-task-id",
"status": "finished",
"created_time": "2026-09-27T10:00:00Z",
"files": [
{
"file_url": "https://example.com/result.mp4",
"file_type": "video"
}
]
}
}Complete polling example
Submit a request, save task_id, and retrieve the generated file when the task finishes.
Complete polling example
set -euo pipefail
: "${VIDGO_API_KEY:?Set VIDGO_API_KEY in your environment}"
REQUEST_BODY=$(cat <<'JSON'
{
"model": "xai/grok-imagine-video/image-to-video",
"input": {
"prompt": "Keep the cup centered. Add gently rising steam while the camera slowly moves closer.",
"duration": 6,
"mode": "normal",
"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
doneRequest Parameters
Set 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 desired scene and motion. Enter 1–5,000 characters. |
| input.image_urls | string[] | Yes | – | Provide exactly one publicly accessible HTTP(S) image URL. |
| input.mode | string | No | – | Generation style: fun, normal, or spicy. |
| input.duration | integer | No | 6 | Video duration in seconds. Choose 6 or 10; defaults to 6. |
Response Fields
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 | video |
| data.error_message | string | null | Reason for a failed task. |
Task Lifecycle
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.
Polling and Errors
- PollingPoll every 2–5 seconds while status is not_started or running. Stop at finished or failed.
- Retry a status queryBack off on 429 and temporary server errors, then query the same task_id.
- CallbackProvide a public callback_url at the request root to receive completion notifications.
Model Specifications
| Specification | Value | Details |
|---|---|---|
| Input | Prompt + Image | Describe the desired scene and motion. Enter 1–5,000 characters. |
| Output | video | 6- or 10-second video. |
| mode | fun · normal · spicy | Generation style: fun, normal, or spicy. |
| duration | 6 · 10 | Video duration in seconds. Choose 6 or 10; defaults to 6. |
Related Models
Grok Imagine Video Image to Video API frequently asked questions
What is the Grok Imagine Video Image to Video API?
Grok Imagine Video Image to Video is an xAI model for animating a still image with text instructions. It creates 6- or 10-second clips with motion prompts and selectable generation modes. The reference establishes the subject and scene, while the prompt directs the action and camera movement added to that visual starting point. You can call it through the API or try it in the Playground tab.
How should I prepare a reference for Grok Imagine Video Image to Video?
Choose one image with a clear main subject and readable surroundings. Provide it as the single URL in image_urls, or upload it in the Playground, then describe the motion to develop from the visible scene.
How do I describe motion for Grok Imagine Video Image to Video?
Name the subject that should move and specify the camera’s role. For example: “Keep the cup centered; let steam rise while the camera moves closer.” This distinguishes the source appearance from the requested motion.
Can Grok Imagine Video Image to Video animate a product picture?
Yes. A product picture can supply the reference scene, with the prompt describing a camera movement or motion in the surroundings. Identify the product and the intended movement so the shot has a clear focus.
How long are Grok Imagine Video Image to Video clips?
Select 6 or 10 seconds using duration. The default is 6 seconds when the field is omitted; choose the length around the action you want to develop from the reference image.
Which modes can I use in Grok Imagine Video Image to Video?
The mode field accepts fun, normal, and spicy. Keep the same reference and motion prompt when comparing modes to explore their treatment of the scene.
When should I choose Grok Imagine Video Image to Video instead of Grok Imagine Video Text to Video?
Choose Grok Imagine Video Image to Video when you already have the photograph or illustration that should establish the scene. Grok Imagine Video Text to Video starts from a written scene description.
How is Grok Imagine Video Image to Video animation priced?
A 6-second video costs 30 credits ($0.150); a 10-second video costs 40 credits ($0.200). Each generated clip is billed at the selected duration’s rate.