The guitarist by the campfire strums a slow chord progression, sparks rising into the night sky, firelight flickering across the guitar body and the surrounding pines. Natural sound: fingerpicked acoustic guitar, crackling fire, crickets. Realistic motion, no text, no logos.
Veo 3.1 Lite Official Image-to-Video API
google/veo3.1-lite/image-to-videoVeo 3.1 Lite Official is the ultra cost-effective rapid image-to-video exploration prototype: awaken a single start frame, or draft first-to-last transitions with dual keyframes. Retain camera control and optional native audio at 720p/1080p with extremely low per-second rates—so you lock the best motion path before committing Fast/Quality finals.
Input
275/1000
Drag and drop files, paste from clipboard, or provide a URL.
1/1 files added
Drag and drop files, paste from clipboard, or provide a URL.
Output
ReadyContinue with
Examples
REST API
Quick Start
Authenticate with the API, submit the inputs and instructions, then retrieve the video using the task ID.
01
Connect to the Vidgo API
Create an API key, keep it only on your 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 one generation task
Fill in the inputs and settings for this endpoint using the request example, then save the returned task_id to query generation progress and results.
Submit request
REQUEST_BODY=$(cat <<'JSON'
{
"model": "google/veo3.1-lite/image-to-video",
"input": {
"prompt": "The guitarist by the campfire strums a slow chord progression, sparks rising into the night sky, firelight flickering across the guitar body and the surrounding pines. Natural sound: fingerpicked acoustic guitar, crackling fire, crickets. Realistic motion, no text, no logos.",
"duration": 8,
"aspect_ratio": "16:9",
"sound": true,
"resolution": "720p",
"image_urls": [
"https://cdn.vidgo.ai/apis/models/google/veo-3.1-lite-official/image-to-video/v1/01/input-start-frame.png"
]
}
}
JSON
)
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")
CODE=$(printf '%s' "$RESPONSE" | jq -r '.code // empty')
if [ "$CODE" != "0" ] && [ "$CODE" != "200" ]; then
printf 'API error: %s
' "$RESPONSE" >&2
exit 1
fi
printf '%s
' "$RESPONSE"03
Wait for the result
Query with task_id, continue for not_started/running, and stop for finished/failed. On success, read data.files[].file_url.
Track status
GET https://api.vidgo.ai/api/generate/status/{task_id}Poll status with a 2-second base interval, and increase the interval for longer tasks. Continue only while status is not_started or running, and stop once finished or failed. You can also specify callback_url in the request payload to receive webhook notifications.
not_startedrunningfinishedfailedSubmit response
{
"code": 200,
"data": {
"task_id": "task-unified-...",
"status": "running",
"created_time": "2026-09-17T10:00:00Z"
}
}Finished response
{
"code": 200,
"data": {
"task_id": "task-unified-...",
"status": "finished",
"files": [
{
"file_url": "https://storage.vidgo.ai/generated/video.mp4",
"file_type": "video"
}
],
"created_time": "2026-08-22T10:00:00Z",
"progress": 100,
"error_message": null
}
}Complete runnable example
Expand for a complete script with HTTP and business-code checks, task_id validation, polling, terminal-state handling, and a timeout boundary.
Complete runnable example
set -euo pipefail
: "${VIDGO_API_KEY:?Set VIDGO_API_KEY in your environment}"
REQUEST_BODY=$(cat <<'JSON'
{
"model": "google/veo3.1-lite/image-to-video",
"input": {
"prompt": "The guitarist by the campfire strums a slow chord progression, sparks rising into the night sky, firelight flickering across the guitar body and the surrounding pines. Natural sound: fingerpicked acoustic guitar, crackling fire, crickets. Realistic motion, no text, no logos.",
"duration": 8,
"aspect_ratio": "16:9",
"sound": true,
"resolution": "720p",
"image_urls": [
"https://cdn.vidgo.ai/apis/models/google/veo-3.1-lite-official/image-to-video/v1/01/input-start-frame.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')
BUSINESS_CODE=$(printf '%s' "$SUBMIT_RESPONSE" | jq -r '.code // empty')
if [ "$BUSINESS_CODE" != "0" ] && [ "$BUSINESS_CODE" != "200" ]; then
printf 'Submit failed:
%s
' "$SUBMIT_RESPONSE" >&2
exit 1
fi
if [ -z "$TASK_ID" ]; then
printf 'Submit response did not include task_id:
%s
' "$SUBMIT_RESPONSE" >&2
exit 1
fi
START_TIME=$(date +%s)
POLL_DELAY=2
while true; do
if [ $(( $(date +%s) - START_TIME )) -ge 600 ]; then
printf 'Timed out after 600 seconds
' >&2
exit 1
fi
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')
BUSINESS_CODE=$(printf '%s' "$STATUS_RESPONSE" | jq -r '.code // empty')
if [ "$BUSINESS_CODE" != "0" ] && [ "$BUSINESS_CODE" != "200" ]; then
printf 'Status request failed:
%s
' "$STATUS_RESPONSE" >&2
exit 1
fi
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 "$POLL_DELAY"
if [ "$POLL_DELAY" -lt 10 ]; then POLL_DELAY=$((POLL_DELAY + 1)); fi
;;
*)
printf 'Unexpected task status: %s
' "$STATUS" >&2
exit 1
;;
esac
doneInput parameters
The table lists available input parameters, types, and defaults. Request examples also include the required top-level model field. Prepare the inputs for this task and configure the output.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| prompt | string | Yes | — | 1–1,000 characters after trimming. |
| image_urls | array | Yes | — | 1 or 2 public image URLs. Two images also send generation_type as frame. |
| generation_type | string | No | frame with two images | Optional. Omitted with one image; defaults to frame with two images. Explicit frame requires exactly two images. |
| duration | integer | No | 8 | 4, 6, or 8, in seconds. |
| aspect_ratio | string | No | 16:9 | auto, 16:9, or 9:16. |
| resolution | string | No | 720p | 720p / 1080p. |
| sound | boolean | No | true | true generates native audio; false returns a silent clip. |
Response Fields
A successful submission returns a task ID. Status queries provide progress, output files, and error details when a task fails.
| Field | Type | Description |
|---|---|---|
| code | integer | Application result code; successful responses use 0 or 200. |
| message | string | Human-readable message or error detail when present. |
| data.task_id | string | Task ID used in the status endpoint path. |
| data.status | string | not_started, running, finished, or failed. |
| data.created_time | string | Task creation time in date-time format. |
| data.progress | integer | Task progress from 0 to 100, when included in the response. |
| data.files[] | array | All output files from a successful task, in response order. |
| data.files[].file_url | string | Public URL for a generated video. |
| data.files[].file_type | string | File type, such as video. |
| data.error_message | string | null | Failure detail when status is failed. |
Task Lifecycle
Continue querying while the status is not_started or running. End polling at finished or failed, then process the output files or error details respectively.
not_startedThe task was accepted and is waiting to begin.
runningGeneration is in progress. Continue polling the same task_id.
finishedGeneration succeeded. Read every video URL from data.files[].file_url.
failedGeneration stopped with an error. Read data.error_message and stop polling.
Polling and Errors
- AuthenticationFor a 401 response, check the Bearer API key in Authorization, update the credentials, and retry.
- ValidationFor a 400 response, use the response details to check required inputs, parameter values, and available credits, then make the indicated adjustments before submitting again.
- Network and timeoutIf a status query encounters a network error or timeout, retain the original task_id and retry the query, then handle the result according to the returned task status.
- Polling intervalPoll status with a 2-second base interval, and gradually increase the interval for longer tasks.
- Terminal statesContinue only for not_started or running. Stop immediately on finished or failed.
- Callback optionProvide callback_url at the request top level to receive the final flat task object; polling remains available if delivery fails.
Endpoint limits
| Specification | Value | Details |
|---|---|---|
| Input mode | Image plus text | A start image is required. An optional end image uses first/last-frame control. |
| Output | Video with optional native audio | The endpoint returns an asynchronous task ID; finished tasks include a video file. |
| Resolution | 720p / 1080p | Default is 720p. |
| Duration | 4 / 6 / 8 seconds | Default is 8 seconds. |
| Aspect ratio | auto / 16:9 / 9:16 | Default is 16:9. |
| Billing basis | Per second | 720p silent 3.6 credits/s; audio 6 credits/s. 1080p silent 6 credits/s; audio 9.6 credits/s, 8 seconds only. |
Related Models
Veo 3.1 Lite Official Image-to-Video API frequently asked questions
What is the Veo 3.1 Lite Official Image-to-Video API?
Veo 3.1 Lite Official Image-to-Video is the ultra cost-effective rapid exploration tier for image-driven generation in Google's Veo 3.1 family. Draft motion from a single start frame or validate first/last-frame transitions at 720p/1080p with optional native audio—built for bulk asset screening and keyframe prototyping via Vidgo API or the playground.
What model ID should I use in API requests?
Set the model field to google/veo3.1-lite/image-to-video. For Fast or Quality, use google/veo3.1-fast/image-to-video and google/veo3.1/image-to-video respectively. Do not submit URLs containing -official.
How many images can I submit and what are the modes?
You can submit 1 or 2 images. One image activates start-frame mode for rapid opening-motion validation. Two images activate first/last-frame mode (automatically submitting generation_type: "frame") for low-cost transition drafts (Lite dual-image jobs support 8 seconds only).
How should I use native audio on Lite image-to-video most efficiently?
Lite supports action-aligned native audio via sound: true. Keep audio off during bulk motion/keyframe trials; enable it for a sync preview once the transition is locked, then graduate winners to Fast/Quality for finals.
How does 'auto' aspect ratio help exploration?
Choosing 'auto' preserves the source image's native ratio so cropping does not distract from judging motion and transitions. Specify 16:9 or 9:16 when you need channel-specific review framing.
When should I choose Lite, Fast, or Quality?
Choose Lite for rapid, cost-effective validation of animation feasibility and keyframe transitions; choose Fast for high-throughput production with 4K headroom; choose Quality for flagship fidelity and commercial finals. Lite is the highest-leverage first stop in an image-driven tiered pipeline.
What practical notes apply to Lite resolution and duration?
Lite supports 720p and 1080p (no 4K). 1080p and first/last-frame (dual-image) jobs support 8 seconds only. Prefer 720p during exploration; switch to 1080p when stakeholders need a clearer internal review.
What image specifications are supported?
The endpoint accepts JPEG, PNG, and WebP files up to 10 MB each. Clear subjects and well-defined lighting help the model extract structure and depth more stably—raising draft success rates.