Grok Imagine Video Text to Video API

xai/grok-imagine-video/text-to-video

6 / 10 seconds · 3 modes

Grok Imagine Video Text to Video turns scene descriptions into short clips with text-directed action and camera movement. Prompts shape the scene’s subjects and motion, while selectable duration, visual mode, and aspect ratio set the format for each shot.

Get API Key

Input

Prompt

664/5000

Aspect Ratio

Duration

Mode

OutputReady

Continue with

Grok Imagine Image Text to Image Grok Imagine Image Edit Grok Imagine Video Image to Video

Examples

One continuous ten-second fixed full-body shot inside a small circular circus rehearsal ring. A single adult male acrobat with closely cropped dark hair wears plain burgundy practice clothes and soft black shoes. He starts standing centered, holding one straight white baton horizontally. He tosses that single baton gently a short distance above his head, watches it, catches it cleanly with one hand, then makes a controlled half turn and gives a modest bow toward the camera. Keep his whole body and the baton visible throughout, with one consistent person and one consistent baton. Warm overhead rehearsal lighting, empty wooden benches, realistic movement, no cuts, no extra performers, no text or logos.

A single continuous six-second aerial tracking shot from behind and slightly above one small cream-yellow minibus driving forward at a steady sensible speed along a winding paved road through lush rolling green hills. Follow the same vehicle smoothly as it rounds one broad S-shaped bend. Keep its wheels on the road, preserve the road geometry, vehicle shape and forward direction. Early morning sunlight, gentle long shadows, distant layered hills, natural documentary color. No abrupt zoom, no cut, no other vehicles, no text, branding or advertising.

REST API

Quick Start

Submit a request, save task_id, and retrieve the generated file when the task finishes.

Connect to Vidgo API

Store your API key on the server and send Authorization: Bearer VIDGO_API_KEY.

Endpoint: POSThttps://api.vidgo.ai/api/generate/submit
Authentication: Authorization: Bearer VIDGO_API_KEY

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/text-to-video",
  "input": {
    "prompt": "A ceramic cup on a wooden table. Steam rises gently as the camera slowly moves closer.",
    "duration": 6,
    "mode": "normal",
    "aspect_ratio": "16:9"
  }
}'

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_startedrunningfinishedfailed

Submit 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/text-to-video",
  "input": {
    "prompt": "A ceramic cup on a wooden table. Steam rises gently as the camera slowly moves closer.",
    "duration": 6,
    "mode": "normal",
    "aspect_ratio": "16:9"
  }
}
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
done

Request 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.aspect_ratio	string	No	–	Choose 1:1, 2:3, 3:2, 16:9, or 9:16.
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_started
Accepted and queued.
running
Generation in progress.
finished
Read the generated files.
failed
Read 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	Describe the desired scene and motion. Enter 1–5,000 characters.
Output	video	6- or 10-second video.
aspect_ratio	1:1 · 2:3 · 3:2 · 16:9 · 9:16	Choose 1:1, 2:3, 3:2, 16:9, or 9:16.
mode	fun · normal · spicy	Generation style: fun, normal, or spicy.
duration	6 · 10	Video duration in seconds. Choose 6 or 10; defaults to 6.

View the Grok Imagine Video Text to Video API docs

Grok Imagine Video Text to Video

Grok Imagine Video Text to Video is xAI’s model for creating short video scenes from a written description. The prompt combines a subject, setting, action, and camera direction into a moving scene, while generation modes offer another way to explore its visual treatment. Selectable clip lengths and aspect ratios suit storyboards, product reveal concepts, and vertical social scenes developed directly from a creative brief.

Why Choose Grok Imagine Video Text to Video?

From a written scene to a moving shotA scene brief can describe both what appears and how it moves, making this endpoint useful for exploring a shot before a source image has been chosen.
Subject action and camera direction togetherThe prompt can describe an object’s movement alongside a pan, push-in, or other camera direction, connecting the subject’s action to the intended framing.
Alternative visual treatmentsThe fun, normal, and spicy modes provide selectable generation styles alongside the scene description, so the same idea can be explored with different settings.
Short clips for different placementsTwo clip lengths and five aspect ratios fit individual storyboard shots, landscape scenes, and vertical social concepts.

Parameters

Parameter	Requirement	Description
prompt	Required	Describe the desired scene and motion. Enter 1–5,000 characters.
aspect_ratio	Optional	Choose 1:1, 2:3, 3:2, 16:9, or 9:16. `1:12:33:216:99:16`
mode	Optional	Generation style: fun, normal, or spicy. `funnormalspicy`
duration	Optional	Video duration in seconds. Choose 6 or 10; defaults to 6. Default`610`

How to Use

Describe the scene and movementEnter the subject, setting, action, and camera direction.
Set the clip formatChoose Duration, Mode, and Aspect Ratio.
Run and view the resultReview the price and select Run, then preview and download the completed result.

Pricing

One credit equals $0.005.

Usage	Rate	Details
6-second video	30 credits / video	$0.150 / video
10-second video	40 credits / video	$0.200 / video

Use Cases

Storyboard motion studiesTurn a written shot description into a short moving scene to discuss subject action and camera direction before production.
Product reveal conceptsDescribe an imagined product, its surroundings, and a reveal movement to explore the timing and framing of a short introduction.
Vertical story scenesCreate a self-contained action in a portrait frame for a short social narrative, starting from the script’s scene description.

Prompt Tips

Describe the subject and setting first, then give the subject a clear action.
Distinguish subject motion from camera motion, such as “the cyclist rides past as the camera pans right.”
Plan one focused shot around the selected 6- or 10-second duration.
Choose aspect_ratio for the intended placement and describe where the action sits within that frame.
When comparing modes, keep the scene prompt, duration, and aspect_ratio the same so the setting change is easy to assess.

Usage Notes

Save the task_id to retrieve the result, or provide callback_url for a completion notification.

Related Models

Gemini Omni 1.1 Flash Text-to-Video preview

Gemini Omni 1.1 Flash Text-to-VideoGoogle Gemini Omni 1.1 Flash video model with native audio, text-to-video, first/last-frame image-to-video, reference-image video, and 3–10 second video edit at 360p to 4K.

Gemini Omni 1.1 Flash Image-to-Video preview

Gemini Omni 1.1 Flash Image-to-VideoGoogle Gemini Omni 1.1 Flash video model with native audio, text-to-video, first/last-frame image-to-video, reference-image video, and 3–10 second video edit at 360p to 4K.

Gemini Omni 1.1 Flash Reference-to-Video preview

Gemini Omni 1.1 Flash Reference-to-VideoGoogle Gemini Omni 1.1 Flash video model with native audio, text-to-video, first/last-frame image-to-video, reference-image video, and 3–10 second video edit at 360p to 4K.

Gemini Omni 1.1 Flash Video Edit preview

Gemini Omni 1.1 Flash Video EditGoogle Gemini Omni 1.1 Flash video model with native audio, text-to-video, first/last-frame image-to-video, reference-image video, and 3–10 second video edit at 360p to 4K.

Wan 3.0 Text-to-VideoAlibaba Tongyi Lab's Wan 3.0 multimodal video model with separate text-to-video, first/last-frame image-to-video, and reference-to-video workflows at 480p, 720p, or 1080p for 2 to 30 seconds.

Wan 3.0 Image-to-VideoAlibaba Tongyi Lab's Wan 3.0 multimodal video model with separate text-to-video, first/last-frame image-to-video, and reference-to-video workflows at 480p, 720p, or 1080p for 2 to 30 seconds.

Wan 3.0 Reference-to-VideoAlibaba Tongyi Lab's Wan 3.0 multimodal video model with separate text-to-video, first/last-frame image-to-video, and reference-to-video workflows at 480p, 720p, or 1080p for 2 to 30 seconds.

Wan 3.0 Prime Text-to-VideoAlibaba Wan 3.0 Prime video model with text-to-video, image-to-video, and reference-to-video workflows at 480p, 720p, or 1080p for 2 to 30 seconds with optional synchronized audio.

Wan 3.0 Prime Image-to-VideoAlibaba Wan 3.0 Prime video model with text-to-video, image-to-video, and reference-to-video workflows at 480p, 720p, or 1080p for 2 to 30 seconds with optional synchronized audio.

Wan 3.0 Prime Reference-to-Video preview

Wan 3.0 Prime Reference-to-VideoAlibaba Wan 3.0 Prime video model with text-to-video, image-to-video, and reference-to-video workflows at 480p, 720p, or 1080p for 2 to 30 seconds with optional synchronized audio.

FLUX 3 Text to VideoBlack Forest Labs FLUX 3 video model with text-to-video, image-to-video, first-last-frame, extend-video, and keyframes workflows at 720p or 1080p for 5 to 20 seconds, with optional native audio.

FLUX 3 Image to VideoBlack Forest Labs FLUX 3 video model with text-to-video, image-to-video, first-last-frame, extend-video, and keyframes workflows at 720p or 1080p for 5 to 20 seconds, with optional native audio.

FLUX 3 First Last Frame to Video preview

FLUX 3 First Last Frame to VideoBlack Forest Labs FLUX 3 video model with text-to-video, image-to-video, first-last-frame, extend-video, and keyframes workflows at 720p or 1080p for 5 to 20 seconds, with optional native audio.

FLUX 3 Extend VideoBlack Forest Labs FLUX 3 video model with text-to-video, image-to-video, first-last-frame, extend-video, and keyframes workflows at 720p or 1080p for 5 to 20 seconds, with optional native audio.

FLUX 3 Keyframes to VideoBlack Forest Labs FLUX 3 video model with text-to-video, image-to-video, first-last-frame, extend-video, and keyframes workflows at 720p or 1080p for 5 to 20 seconds, with optional native audio.

Seedance 2.5 Text-to-VideoByteDance Seed's Seedance 2.5 video model with separate text-to-video, start/end-frame image-to-video, and multimodal reference-to-video API workflows at 480p, 720p, or 1080p for 4 to 30 seconds.

Grok Imagine Video Text to Video API frequently asked questions

What is the Grok Imagine Video Text to Video API?

Grok Imagine Video Text to Video is an xAI model for creating video scenes from text. It generates 6- or 10-second clips with selectable visual modes and square, portrait, or landscape framing. The text describes the subject, setting, action, and camera direction together, giving the shot a defined scene and movement. You can call it through the API or try it in the Playground tab.

How does Grok Imagine Video Text to Video use camera instructions?

Include the intended camera movement alongside the subject’s action in prompt. For example, describe a camera moving closer to a stationary object or following a person through a scene, so subject motion and camera motion have separate roles.

Which visual modes does Grok Imagine Video Text to Video offer?

The mode field accepts fun, normal, and spicy. Select a mode alongside a scene prompt; when comparing treatments, keep the prompt and other settings unchanged to evaluate that choice.

How do I choose the duration in Grok Imagine Video Text to Video?

Set duration to 6 or 10 seconds; omitting it selects 6 seconds. Plan the action around the chosen length, using a focused movement for a short shot or more time for an action to unfold.

Which frames can Grok Imagine Video Text to Video generate?

Set aspect_ratio to 1:1, 2:3, 3:2, 16:9, or 9:16. This sets the output frame for a square post, portrait scene, or landscape composition.

When should I choose Grok Imagine Video Text to Video instead of Grok Imagine Video Image to Video?

Choose Grok Imagine Video Text to Video when the scene, subjects, and action are described in a written brief. Choose Grok Imagine Video Image to Video when an existing picture should provide the visual starting point.

What does a 10-second Grok Imagine Video Text to Video clip cost?

A 10-second clip costs 40 credits ($0.200), and a 6-second clip costs 30 credits ($0.150). Billing is per generated video at the selected duration.