X AI Grok Imagine Video V1.5 Text To Video API Documentation

X AI Grok Imagine Video V1.5 Text To Video API Documentation

Playground

xAI Grok Imagine Video v1.5 Text to Video turns natural-language prompts into short, stylized AI videos, with 480P, 720P, and 1080P output options plus selectable aspect ratios for social media clips, creative storytelling, concept videos, marketing content, and professional text-to-video workflows. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

Features

xAI Grok Imagine Video V1.5 Text-to-Video generates short videos with synchronized audio directly from a natural-language prompt. It is designed for prompt-driven motion generation, cinematic concept clips, stylized social media content, and other text-to-video creation workflows.

Why Choose This?

• Prompt-only video generation Describe the scene, motion, and camera behavior in words and get a short video back — no input image required.

• Fine motion and camera control Use text to direct subject motion, camera moves, atmosphere, and how the scene evolves over time.

• Flexible output settings Choose 480p, 720p, or 1080p, pick an aspect ratio, and set the clip length.

• Predictable short-form generation Works well for short clips that need quick iteration and clean prompt-to-video control.

• Production-ready API Suitable for concept visualization, creator content, ads, and lightweight motion storytelling.

Parameters

How to Use

1. Write your prompt — describe the scene, subject motion, and camera behavior you want.
2. Set duration (optional) — choose an integer from 1 to 15 seconds. The default is 6.
3. Choose aspect ratio — match the target platform (e.g. 9:16 for vertical, 16:9 for landscape).
4. Choose resolution — use 480p for lower cost, 720p for balance, or 1080p for higher-resolution output.
5. Submit — run the model and download the generated video.

Pricing

Pricing depends on the requested duration and resolution. There is no per-image charge.

Example Costs

Best Use Cases

• Text-to-video generation — Turn a written idea into a short motion clip.
• Social media content — Create lightweight animated visuals for posts and promos.
• Concept visualization — Explore motion and mood directions from a description alone.
• Advertising mockups — Produce quick animated concepts for campaigns.
• Creative prototyping — Rapidly test prompt-driven motion ideas.

Pro Tips

• Be specific about camera movement, subject motion, pacing, and atmosphere.
• Match aspect_ratio to where the clip will be published.
• Start with shorter durations for fast iteration, then scale up.
• Use 480p for quick testing and 720p/1080p for final-quality clips.
• Describe how the scene changes over time rather than only its static appearance.

Notes

• prompt is required; all other parameters are optional.
• duration accepts whole seconds from 1 to 15 and defaults to 6.
• resolution defaults to 720p; aspect_ratio defaults to 16:9.
• Audio generation is enabled by default.
• Pricing depends on the requested duration and resolution, with no per-image surcharge.

Related Models

• xAI Grok Imagine Video v1.5 Image-to-Video — Animate an existing image instead of starting from text.
• xAI Grok Imagine Video v1.5 Reference-to-Video — Guide generation with up to seven reference images.

Authentication

For authentication details, please refer to the Authentication Guide.

API Endpoints

Submit Task & Query Result

set -euo pipefail

export WAVESPEED_API_KEY="your-api-key"

REQUEST_BODY=$(cat <<'JSON'
{
  "prompt": "A cinematic ocean wave at sunrise, highly detailed",
  "duration": 6,
  "aspect_ratio": "16:9",
  "resolution": "720p"
}
JSON
)

# 1. Submit the prediction once. Never retry this request automatically:
# a retry after an unclear failure can create a second, billed task.
CHECK='The task may already exist. Check History or the predictions list before submitting again.'
if ! SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  --connect-timeout 10 --max-time 60 \
  -X POST "https://api.wavespeed.ai/api/v3/x-ai/grok-imagine-video-v1.5/text-to-video" \
  -H "Authorization: Bearer ${WAVESPEED_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "${REQUEST_BODY}"); then
  printf 'Submit failed. %s\n' "${CHECK}" >&2
  exit 1
fi

TASK=$(printf '%s' "${SUBMIT_RESPONSE}" | jq 'if type == "object" and has("data") then .data else . end')
PREDICTION_ID=$(printf '%s' "${TASK}" | jq -r '.id // empty')
if [ -z "${PREDICTION_ID}" ]; then
  printf 'Submission response did not contain a prediction id. %s\n' "${CHECK}" >&2
  exit 1
fi
RESULT_URL="https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result"

# 2. Poll until the prediction reaches a final status.
BODY_FILE=$(mktemp)
trap 'rm -f "${BODY_FILE}"' EXIT
while true; do
  # Transient errors (429, 5xx) are retried, honoring Retry-After.
  HTTP_CODE=$(curl --silent --show-error --fail-with-body \
    --connect-timeout 10 --max-time 60 --retry 5 --retry-delay 2 \
    --output "${BODY_FILE}" --write-out '%{http_code}' \
    "${RESULT_URL}" \
    -H "Authorization: Bearer ${WAVESPEED_API_KEY}" || true)
  case "${HTTP_CODE}" in
    2??) ;;
    000|429|5??)  # dropped connection or temporary error: keep polling
      printf 'Task %s: HTTP %s, polling again in 10s\n' "${PREDICTION_ID}" "${HTTP_CODE}" >&2
      sleep 10; continue ;;
    *) printf 'Task %s: HTTP %s\n' "${PREDICTION_ID}" "${HTTP_CODE}" >&2
      cat "${BODY_FILE}" >&2; exit 1 ;;
  esac
  RESULT=$(jq 'if type == "object" and has("data") then .data else . end' "${BODY_FILE}")
  STATUS=$(printf '%s' "${RESULT}" | jq -r '.status // empty')

  case "${STATUS}" in
    completed) printf '%s\n' "${RESULT}" | jq '.outputs'; break ;;
    failed|cancelled|timeout|deleted)
      printf 'Task %s ended with status %s\n' "${PREDICTION_ID}" "${STATUS}" >&2
      printf '%s\n' "${RESULT}" | jq . >&2; exit 1 ;;
    *) sleep 2 ;;
  esac
done

Parameters

Task Submission Parameters

Request Parameters

Response Parameters

Result Request Parameters

Result Response Parameters