Google Veo3.1 Lite Image To Video API Documentation

Google Veo3.1 Lite Image To Video API Documentation

Playground

Google Veo 3.1 Lite Image-to-Video transforms static images into high-fidelity 720p or 1080p videos with natively generated audio. Supports many interpolation use cases, landscape and portrait aspect ratios, and customizable duration. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

Features

Veo 3.1 Lite is an efficient image-to-video model, generating high-quality cinematic video from an input image and a natural language prompt at accessible pricing. With native synchronized audio generation, negative prompt guidance, landscape and portrait aspect ratios, and resolution up to 1080p, it brings still images to life for a wide range of creative and production workflows.

• Need text-only generation? Try Veo 3.1 Lite Text-to-Video

Why Choose This?

• High-quality image animation Uses your input image as the starting frame and adds motion guided by your text description.

• Negative prompt guidance Describe unwanted elements to guide generation. Exclusion of specific elements is not guaranteed.

• Resolution options Generate at 720p or 1080p to match your quality and budget requirements. 1080p requires an 8-second duration.

• Flexible aspect ratios Supports landscape 16:9 and portrait 9:16 for cinematic and social formats.

• Seed control Set a seed when experimenting with generation settings. Identical outputs are not guaranteed.

• Synchronized audio Generates audio alongside the video. Describe dialogue, sound effects, and ambient sounds in your prompt.

Parameters

How to Use

1. Upload your image — choose a clear image containing the subject and composition you want to animate.
2. Write your prompt — describe how the subject and camera should move. Include atmosphere, sound effects, or dialogue if needed.
3. Select aspect ratio — choose 16:9 for landscape or 9:16 for portrait.
4. Set duration — choose 4, 6, or 8 seconds. Keep the duration at 8 seconds when using 1080p.
5. Select resolution — 720p for standard output, 1080p for higher-resolution results.
6. Add negative prompt (optional) — describe elements you want the model to avoid.
7. Set seed (optional) — specify a seed for controlled experimentation, without expecting exact reproduction.
8. Submit — generate, preview, and download your video.

Pricing

Best Use Cases

• Cinematic Storytelling — Animate a still frame into an atmospheric, narrative-driven scene.
• Social Media Content — Turn portraits, illustrations, and other images into short video clips with synchronized audio.
• Marketing & Advertising — Bring product images and campaign visuals to life with motion.
• Concept Visualization — Explore how a character, environment, or visual concept could move on screen.
• Audio-Visual Content — Combine image animation with ambient sounds, dialogue, and sound effects.

Pro Tips

• Start with a clear, well-composed image that shows the subject you want to animate.
• Focus your prompt on motion, camera movement, and changes over time rather than repeating everything already visible in the image.
• Choose an output aspect ratio that matches your source image where possible.
• Use negative_prompt as guidance for unwanted elements rather than a strict exclusion rule.
• Use 720p to rapidly test and iterate before committing to an 8-second 1080p final render.
• Keep the image, prompt, and settings consistent when comparing results; a fixed seed does not guarantee identical output.
• Include clear audio cues in your prompt when particular sounds or dialogue are important.

Notes

• Both prompt and image are required; all other parameters are optional.
• The default output settings are 720p, 8 seconds, and 16:9.
• 720p supports 4-, 6-, and 8-second generation. 1080p requires an 8-second duration.
• Audio generation is enabled by default.
• Please follow applicable content usage policies when providing images and crafting prompts.

Related Models

• Veo 3.1 Lite Text-to-Video — Generate cinematic video clips directly from text prompts with Veo 3.1 Lite.

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",
  "image": "https://interactive-examples.mdn.mozilla.net/media/cc0-images/painted-hand-298-332.jpg",
  "aspect_ratio": "16:9",
  "duration": 8,
  "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/google/veo3.1-lite/image-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

Every model also accepts the global request options enable_sync_mode and enable_base64_output; see their pages for details.

Response Parameters

Result Request Parameters

Result Response Parameters