Google Veo3.1 Text To Video API Documentation

Google Veo3.1 Text To Video API Documentation

Playground

Google Veo 3.1 converts text prompts into videos with synchronized audio at native 1080p for high-quality outputs. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

Features

Veo 3.1 T2V is the latest text-to-video model from Google DeepMind, designed to bring cinematic storytelling to life through text. It generates high-fidelity 1080p videos with synchronized, context-aware audio, realistic motion, and narrative consistency — making it one of the most advanced generative video systems ever released.

🌟 Why it stands out

• 🎬 Cinematic Realism Produces natural lighting, smooth camera transitions, and accurate perspective for film-like motion.

• 🔊 Native Audio Generation Generates synchronized ambient sound, dialogue, and music directly aligned with the visuals.

• 🗣️ Dialogue & Lip-Sync Supports speaking characters and realistic facial expressions — perfect for storytelling, marketing, or short-form content.

• 🧠 Subject Consistency (R2V) Maintains a character’s or object’s identity across frames using 1–3 reference images.

• 🎞️ Video Interpolation Seamlessly animates transitions between two given frames — ideal for smooth start-to-end storytelling.

• 📐 Flexible Output Supports both 720p and 1080p, at 24 FPS, duration for 4s, 6s, 8s, and in both 16:9 (landscape) and 9:16 (portrait) formats.

⚙️ Key Parameters

• prompt — Describe your scene or story (e.g., “A drone shot flying over Las Vegas, transitioning from day to night with soft jazz in the background”).
• durationSeconds — Choose video length (4s, 6s, or 8s).
• resolution — 720p or 1080p.
• aspectRatio — Landscape (16:9) or Portrait (9:16).

Pricing

Pricing depends on the requested duration, resolution, and whether audio generation is enabled.

Example Costs

Billing Rules

• Total price = requested duration × the applicable per-second rate.
• generate_audio=true uses the With Audio rate.
• generate_audio=false uses the Without Audio rate.
• Default configuration: 1080p, 8 seconds, audio enabled — $3.20.
• aspect_ratio, negative_prompt, and seed do not add separate charges.

🚀 How to Use

1. ✍️ Write a Prompt Describe the desired motion, camera style, lighting, and sound.

> Example: “A cinematic sunset over the ocean, waves glimmering as seagulls fly across the horizon.”

3. ⚙️ Adjust Parameters Select duration, resolution (720p/1080p), and aspect ratio.

4. ▶️ Generate Submit your request — Veo 3.1 will render motion, lighting, and synchronized audio.

5. 💾 Preview & Download Review your video, refine your prompt if needed, then download the final MP4.

💡 Pro Tips

• Keep prompts focused on one main action or subject for better coherence.
• Use camera verbs like “tracking,” “zoom out,” or “handheld” for cinematic control.
• Mention lighting and mood cues (e.g., “under soft moonlight,” “golden-hour glow”).
• Use R2V for character-based storytelling; Interpolation for smooth transitions.
• Avoid conflicting instructions (e.g., “fast zoom” and “slow motion” together).

🧾 Notes & Limitations

• Generation time: ~2–3 minutes for an 8-second 1080p clip.
• Frame rate fixed at 24 FPS.
• Advanced controls (R2V, I2V, Interpolation) are mutually exclusive — only one per generation.
• If your prompt is blocked, rewrite it and resubmit (safety thresholds may adjust during preview).

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",
  "aspect_ratio": "16:9",
  "duration": 8,
  "resolution": "1080p",
  "generate_audio": true
}
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/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