Veo 3.1 Image to Video API

POST /v1/tasks

All models are called through the Unified Async API POST /v1/tasks endpoint; only the input fields differ (see input parameters below).

Model summary

Model name	veo-3.1/image-to-video
Type	Video generation (image-to-video)
Endpoint	POST /v1/tasks
Pricing	See HiAPI Pricing

Google Veo 3.1 image-to-video API animates a still image into a cinematic clip with native audio, up to 4K, 4 / 6 / 8-second durations, and aspect ratio that follows the input.

Production guidance

For production, pass callback.url at the top level of the request body so HiAPI can notify your service when the task reaches a terminal state.
GET /v1/tasks/:id is better for local debugging, low-volume jobs, or fallback reconciliation if a callback is missed.
Use callback.when=final. Both success and fail are terminal states, so your service should deduplicate by taskId.

Best suited for

Animate product shots and posters

Turn static product photos, posters, or photography into cinematic clips while keeping lighting and content consistent.

image_urlprompt

Mood clips with native audio

Generate ambience and sound effects while the image comes to life — ready-to-publish clips in one call.

generate_audio

Up to 4K delivery

Outputs 720p / 1080p / 4K, upgrading static assets into high-resolution motion.

resolutionduration

Aspect ratio follows the input

aspect_ratio defaults to auto, matching the input image; force 16:9 or 9:16 when needed.

aspect_ratio

Request parameters

POST https://api.hiapi.ai/v1/tasks

# Create an async task — returns taskId immediately (generation runs async)
# Replace YOUR_API_KEY with your account API key
curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "veo-3.1/image-to-video",
  "input": {
    "prompt": "The storm intensifies: waves crash against the cliff in slow motion, the lighthouse beam sweeps across the sea, thunder rumbling",
    "image_url": "https://static.hiapi.ai/example/2026/07/02/1782991315981-ea706258e68806d3-veo-3-1-image-to-video.webp",
    "aspect_ratio": "auto",
    "resolution": "720p",
    "duration": 8,
    "generate_audio": true
  }
}'

import requests, json

# Business params — fields vary by model (see the model page)
payload = json.loads(r'''
{
  "model": "veo-3.1/image-to-video",
  "input": {
    "prompt": "The storm intensifies: waves crash against the cliff in slow motion, the lighthouse beam sweeps across the sea, thunder rumbling",
    "image_url": "https://static.hiapi.ai/example/2026/07/02/1782991315981-ea706258e68806d3-veo-3-1-image-to-video.webp",
    "aspect_ratio": "auto",
    "resolution": "720p",
    "duration": 8,
    "generate_audio": true
  }
}
''')

# Create an async task — returns taskId immediately (generation runs async)
resp = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json"},
    json=payload,
)
print(resp.json())  # Returns { code, message, data: { taskId } }

// Create an async task — returns taskId immediately (generation runs async)
// Replace YOUR_API_KEY with your account API key
const resp = await fetch("https://api.hiapi.ai/v1/tasks", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "veo-3.1/image-to-video",
  "input": {
    "prompt": "The storm intensifies: waves crash against the cliff in slow motion, the lighthouse beam sweeps across the sea, thunder rumbling",
    "image_url": "https://static.hiapi.ai/example/2026/07/02/1782991315981-ea706258e68806d3-veo-3-1-image-to-video.webp",
    "aspect_ratio": "auto",
    "resolution": "720p",
    "duration": 8,
    "generate_audio": true
  }
}),
});
console.log(await resp.json()); // Returns { code, message, data: { taskId } }

model string required

Fixed value veo-3.1/image-to-video.

example veo-3.1/image-to-video

input object required

Business parameters. Put Veo 3.1 Image to Video-specific configuration here.

prompt string required

Text prompt describing how the image should be animated.

image_url string required

URL of the input image to animate. Should be 720p or higher resolution in 16:9 or 9:16 aspect ratio; other aspect ratios are cropped to fit. SVG is not supported.

aspect_ratio enum optional

Output video aspect ratio. auto follows the input image.

default auto enum: auto16:99:16

resolution enum required

Output video resolution. Higher resolution costs more.

default 720p enum: 720p1080p4k

duration enum required

Clip length in seconds. Cost scales with duration.

default 8 enum: 468

generate_audio boolean optional

Generate a native audio track. Pricing is higher when enabled.

default true

negative_prompt string optional

Describe what to avoid in the generated video.

seed integer optional

Random seed for reproducible generation.

callback object optional

Optional callback configuration. When set, HiAPI notifies your service when the task reaches a terminal state.

url string required

Required when callback is set; HTTPS URL that receives terminal task notifications.

example https://your-domain.com/hiapi/callback

when enum optional

Callback trigger timing. Use final.

default final enum: final

Example requests

Storm lighthouse (4K with audio)

Animate a static lighthouse still: crashing waves, sweeping beam, thunder — 4K / 8s.

Request body

{
  "model": "veo-3.1/image-to-video",
  "input": {
    "prompt": "The storm intensifies: waves crash against the cliff in slow motion, the lighthouse beam sweeps across the sea, thunder rumbling",
    "image_url": "https://static.hiapi.ai/example/2026/07/02/1782991315981-ea706258e68806d3-veo-3-1-image-to-video.webp",
    "resolution": "4k",
    "duration": 8,
    "generate_audio": true
  }
}

Low-cost preview (720p, no audio)

Same input at 720p / 4s without audio — validate the motion cheaply before the 4K render.

Request body

{
  "model": "veo-3.1/image-to-video",
  "input": {
    "prompt": "Waves crash rhythmically against the rocks below the lighthouse, beam rotating, clouds drifting",
    "image_url": "https://static.hiapi.ai/example/2026/07/02/1782991315981-ea706258e68806d3-veo-3-1-image-to-video.webp",
    "resolution": "720p",
    "duration": 4,
    "generate_audio": false
  }
}

Getting the result

The response returns a taskId immediately without waiting for generation to finish.
In production, prefer waiting for callback.url to receive the terminal notification. For local debugging, poll GET /v1/tasks/:id.
When status=success, download the generated video from output[].url.
When status=fail, fix the request based on the returned error instead of retrying the same invalid payload.

FAQ

What are the input image requirements?

720p or higher resolution in 16:9 or 9:16 aspect ratio is recommended; other ratios are cropped to fit. image_url must be a publicly accessible URL. SVG is not supported.

Is prompt required?

Yes. The prompt describes how the image should be animated (motion, camera, ambience) and is required together with image_url.

Which resolutions and durations are supported, and how is it priced?

Resolutions 720p / 1080p / 4K, durations 4 / 6 / 8 seconds. Billed by resolution, audio, and duration (per second) — same rates as veo-3.1 text-to-video. See the live pricing page. View pricing

How do I get the generated video?

The response returns a taskId immediately. When the task reaches a terminal state, download the video from output[].url. In production, pass callback.url for terminal notifications.