Veo 3.1 Official API Forwarding

Overview

Veo 3.1 official API forwarding is now available through api.laozhang.ai. For new integrations, create a dedicated token, keep it in the default group, and set Billing mode to Pay-per-request. This page documents the API format, parameters, pricing, and code examples.

Pricing Advantage

Veo 3.1 official forwarding uses Pay-per-request billing with one unified price across supported duration and resolution combinations. Duration and resolution do not add extra charges. Based on public pricing from Google Gemini API Pricing, Google bills Veo 3.1 per second; the comparison below uses 8-second videos.

Model	LaoZhang price	Google 8s 1080p	Lower by	Google 8s 4K	Lower by
`veo-3.1-fast-generate-preview`	`$0.3/call`	`$0.96`	`68.8%`	`$2.40`	`87.5%`
`veo-3.1-generate-preview`	`$1.2/call`	`$3.20`	`62.5%`	`$4.80`	`75.0%`

This route uses the same OpenAI Videos API style as Sora2 official forwarding:

Step	Method	Path	Response
Create a video task	`POST`	`/v1/videos`	JSON task object
Poll task status	`GET`	`/v1/videos/{id}`	JSON status object
Compatibility status polling	`GET`	`/v1/video/generations/{id}`	JSON status object
Download video output	`GET`	`/v1/videos/{id}/content`	`video/mp4` bytes

Use multipart/form-data when creating video tasks. Text-to-video and image-to-video both use the same /v1/videos task API.

Do not use the legacy Veo-3.1 sync route, legacy Chat Completions examples, or old model names such as veo-3.1, veo-3.1-fast, or veo-3.1-fl. The official-forward route only uses the model names and /v1/videos task API documented here.

Token Setup

Setting	Value
Console entry	Token management → create a new token
Group	Default group
Billing mode	`Pay-per-request`
Recommendation	Create a dedicated Veo 3.1 official-forward token for easier usage review

Veo 3.1 official forwarding uses the Pay-per-request billing mode across supported duration and resolution combinations. Duration and resolution do not add extra charges.

Supported Models

Model	Price per call	Description	Best for
`veo-3.1-fast-generate-preview`	`$0.3`	Veo 3.1 Fast preview model	Quick tests, drafts, cost-sensitive workflows
`veo-3.1-generate-preview`	`$1.2`	Veo 3.1 standard preview model	Higher-quality outputs, production assets, complex shots

Parameters

Core Parameters

Parameter	Type	Required	Description
`model`	string	Yes	`veo-3.1-fast-generate-preview` or `veo-3.1-generate-preview`
`prompt`	string	Yes	Video prompt
`seconds`	string	No	Duration. For production integrations, use `"8"`
`duration`	string	No	Duration. Keep it aligned with `seconds`, such as `"8"`
`size`	string	No	Output size such as `1280x720`, `720x1280`, `1920x1080`, `1080x1920`, `3840x2160`
`resolution`	string	No	`720p`, `1080p`, or `4k`
`aspectRatio`	string	No	`16:9` or `9:16`
`metadata`	string	No	JSON string. 4K requests must include `{"durationSeconds":8,"resolution":"4k","aspectRatio":"16:9"}`
`negativePrompt`	string	No	Negative prompt, such as `blurry, watermark, distorted`
`seed`	string	No	Random seed for similar repeatability
`input_reference`	file	No	Reference image for image-to-video. Only one image is supported, uploaded as `multipart/form-data`

Do not pass generateAudio. Veo 3 / Veo 3.1 models have native audio, but this API does not support audio toggling through generateAudio. Passing it may return INVALID_ARGUMENT. To guide audio content, describe dialogue, ambient sound, effects, or music style in the prompt.

Duration and Resolution

Use case	Suggested parameters
8s landscape 720p	`seconds="8"`, `size="1280x720"`, `resolution="720p"`, `aspectRatio="16:9"`
8s landscape 1080p	`seconds="8"`, `size="1920x1080"`, `resolution="1080p"`, `aspectRatio="16:9"`
8s portrait 1080p	`seconds="8"`, `size="1080x1920"`, `resolution="1080p"`, `aspectRatio="9:16"`
8s landscape 4K	`seconds="8"`, `duration="8"`, `size="3840x2160"`, `resolution="4k"`, `aspectRatio="16:9"`, `metadata='{"durationSeconds":8,"resolution":"4k","aspectRatio":"16:9"}'`

Pass seconds and duration as strings rather than numbers. For production integrations, use 8-second requests. 1080p and 4k only support 8 seconds. For image-to-video, upload a local image file instead of a remote image URL.

Parameter limit: 1080p and 4k must be used with 8-second requests. Do not combine them with 4-second or 6-second requests. For 4K, also pass metadata.resolution="4k"; otherwise the downloaded file may be rendered as 1080p.

4K requests use the unified price. If you need to verify native 4K output, download the MP4 and inspect its media metadata. Do not rely only on create-task parameters for final file resolution.

Text-to-Video

Create a Task

curl -X POST "https://api.laozhang.ai/v1/videos" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F model="veo-3.1-fast-generate-preview" \
  -F prompt="A cinematic shot of a lighthouse at sunset, ocean waves hitting the rocks, stable slow camera push-in" \
  -F seconds="8" \
  -F duration="8" \
  -F size="1280x720" \
  -F resolution="720p" \
  -F aspectRatio="16:9" \
  -F 'metadata={"durationSeconds":8,"resolution":"720p","aspectRatio":"16:9"}' \
  -F negativePrompt="blurry, watermark, distorted, low quality" \
  -F seed="20260520"

Create Response

{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "veo-3.1-fast-generate-preview",
  "status": "queued",
  "progress": 0,
  "created_at": 1779283975
}

Image-to-Video

Image-to-video uses the same create endpoint with an additional input_reference file upload. The API supports only one initial image, and the field name must be input_reference; multiple uploaded images are not treated as multi-reference input.

curl -X POST "https://api.laozhang.ai/v1/videos" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F model="veo-3.1-generate-preview" \
  -F prompt="Animate the reference image with a gentle camera push-in, subtle background parallax, cinematic lighting" \
  -F seconds="8" \
  -F duration="8" \
  -F size="1280x720" \
  -F resolution="720p" \
  -F aspectRatio="16:9" \
  -F 'metadata={"durationSeconds":8,"resolution":"720p","aspectRatio":"16:9"}' \
  -F negativePrompt="blurry, watermark, deformed face, distorted body" \
  -F seed="20260520" \
  -F input_reference="@reference.jpg;type=image/jpeg"

4K Landscape Image-to-Video

For 4K landscape image-to-video, upload a 16:9 reference image and pass both resolution="4k" and metadata.resolution="4k".

curl -X POST "https://api.laozhang.ai/v1/videos" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F model="veo-3.1-fast-generate-preview" \
  -F prompt="Animate the 4K reference image with a slow cinematic camera push-in, subtle parallax, crisp details, stable lighting" \
  -F seconds="8" \
  -F duration="8" \
  -F size="3840x2160" \
  -F resolution="4k" \
  -F aspectRatio="16:9" \
  -F 'metadata={"durationSeconds":8,"resolution":"4k","aspectRatio":"16:9"}' \
  -F negativePrompt="blurry, watermark, distorted, low quality" \
  -F seed="20260521" \
  -F input_reference="@reference-4k.jpg;type=image/jpeg"

The reference image should match the target size when possible. For example, use a 1280x720 image when size=1280x720. JPEG, PNG, and WebP are supported. Multi-reference images, first/last-frame generation, and video extension fields are not supported; do not pass referenceImages, lastFrame, or video.

Poll Status

Save the id or task_id from the create response, then poll status.

curl "https://api.laozhang.ai/v1/videos/task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Authorization: Bearer YOUR_API_KEY"

In progress:

{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "veo-3.1-fast-generate-preview",
  "status": "in_progress",
  "progress": 50,
  "created_at": 1779283975
}

Completed:

{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "veo-3.1-fast-generate-preview",
  "status": "completed",
  "progress": 100,
  "created_at": 1779283975,
  "completed_at": 1779284026
}

Status Values

Status	Meaning
`queued`	Queued
`in_progress`	Generating
`completed`	Completed and ready to download
`failed`	Failed

Compatibility Status Polling

If existing code uses the older video generations polling path, use this compatibility endpoint:

curl "https://api.laozhang.ai/v1/video/generations/task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Authorization: Bearer YOUR_API_KEY"

This endpoint returns a task status object:

{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "veo-3.1-fast-generate-preview",
  "status": "completed",
  "progress": 100,
  "created_at": 1779283975,
  "completed_at": 1779284026
}

The compatibility polling endpoint does not return a separate public video URL. Download video results through /v1/videos/{id}/content.

Download Video

After the task completes, use /content to retrieve MP4 bytes. The API returns video file bytes, not a public video URL.

curl -L "https://api.laozhang.ai/v1/videos/task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/content" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o veo-3-1-output.mp4

The video file may lag briefly after GET /v1/videos/{id} returns completed. If the content endpoint returns task status is IN_PROGRESS, wait 10-20 seconds and retry.

Python Complete Example

import json
from pathlib import Path
import time

import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.laozhang.ai"

HEADERS = {
    "Authorization": f"Bearer {API_KEY}"
}


def video_metadata(seconds, resolution, aspect_ratio):
    return json.dumps({
        "durationSeconds": int(seconds),
        "resolution": resolution,
        "aspectRatio": aspect_ratio,
    })


def create_text_video(
    prompt,
    model="veo-3.1-fast-generate-preview",
    seconds="8",
    size="1280x720",
    resolution="720p",
    aspect_ratio="16:9",
):
    fields = {
        "model": model,
        "prompt": prompt,
        "seconds": seconds,
        "duration": seconds,
        "size": size,
        "resolution": resolution,
        "aspectRatio": aspect_ratio,
        "metadata": video_metadata(seconds, resolution, aspect_ratio),
        "negativePrompt": "blurry, watermark, distorted, low quality",
    }
    response = requests.post(
        f"{BASE_URL}/v1/videos",
        headers=HEADERS,
        files={key: (None, value) for key, value in fields.items()},
        timeout=180,
    )
    response.raise_for_status()
    return response.json()


def create_image_video(
    prompt,
    image_path,
    model="veo-3.1-generate-preview",
    seconds="8",
    size="1280x720",
    resolution="720p",
    aspect_ratio="16:9",
):
    fields = {
        "model": model,
        "prompt": prompt,
        "seconds": seconds,
        "duration": seconds,
        "size": size,
        "resolution": resolution,
        "aspectRatio": aspect_ratio,
        "metadata": video_metadata(seconds, resolution, aspect_ratio),
        "negativePrompt": "blurry, watermark, distorted, low quality",
    }
    with open(image_path, "rb") as image_file:
        files = {key: (None, value) for key, value in fields.items()}
        files["input_reference"] = (Path(image_path).name, image_file, "image/jpeg")
        response = requests.post(
            f"{BASE_URL}/v1/videos",
            headers=HEADERS,
            files=files,
            timeout=180,
        )
    response.raise_for_status()
    return response.json()


def wait_for_video(task_id, timeout=900, interval=15):
    start = time.time()
    while time.time() - start < timeout:
        response = requests.get(
            f"{BASE_URL}/v1/videos/{task_id}",
            headers=HEADERS,
            timeout=60,
        )
        response.raise_for_status()
        payload = response.json()

        status = payload.get("status")
        progress = payload.get("progress", 0)
        print(f"status={status}, progress={progress}")

        if status == "completed":
            return payload
        if status == "failed":
            raise RuntimeError(f"video generation failed: {payload}")

        time.sleep(interval)

    raise TimeoutError("video generation timed out")


def download_video(task_id, output_path, retries=8, interval=10):
    last_error = None
    for _ in range(retries):
        response = requests.get(
            f"{BASE_URL}/v1/videos/{task_id}/content",
            headers=HEADERS,
            timeout=180,
        )
        if response.status_code == 200:
            with open(output_path, "wb") as output_file:
                output_file.write(response.content)
            return output_path

        last_error = response.text
        if "IN_PROGRESS" not in response.text and "in_progress" not in response.text:
            response.raise_for_status()
        time.sleep(interval)

    raise RuntimeError(f"download failed: {last_error}")


if __name__ == "__main__":
    task = create_text_video(
        prompt="A cinematic lighthouse at sunset, ocean waves, slow camera push-in",
        model="veo-3.1-fast-generate-preview",
        seconds="8",
        size="1280x720",
    )
    task_id = task.get("id") or task.get("task_id")
    wait_for_video(task_id)
    download_video(task_id, "veo-output.mp4")

FAQ

Does the API return a video URL or file bytes?

/v1/videos/{id}/content returns video/mp4 bytes, not a public video URL. /v1/video/generations/{id} returns a task status object, not a separate public video URL. In production, download it server-side, store it in your own OSS/CDN, and return your own URL to users.

Which token group should I choose?

Use the default group for Veo 3.1 official forwarding. Create a dedicated token and set Billing mode to Pay-per-request for cleaner billing review.

Which duration and resolution should I use?

Billing uses Pay-per-request, not separate duration or resolution pricing. veo-3.1-fast-generate-preview is $0.3/call, and veo-3.1-generate-preview is $1.2/call. For production integrations, use 8-second requests; 1080p and 4k require 8 seconds. For 4K, also pass metadata.resolution="4k".

Can image-to-video use multiple images?

Only one initial image is supported, and the field name must be input_reference. Multi-reference images, first/last-frame generation, and video extension fields are not supported; do not pass referenceImages, lastFrame, or video.

Can I pass generateAudio to control sound?

Do not pass generateAudio. Veo 3 / Veo 3.1 models have native audio, but this API does not support toggling audio with generateAudio; describe the desired audio in the prompt instead.

Can I use Chat Completions?

Not recommended. Veo 3.1 official forwarding should use the same /v1/videos task API style as Sora2 official forwarding.

Getting Started

Core API

Text APIs

Video Generation APIs

Image Generation APIs

AI Understanding

Veo 3.1 Official API Forwarding

Overview

Pricing Advantage

Token Setup

Supported Models

Parameters

Core Parameters

Duration and Resolution

Text-to-Video

Create a Task

Create Response

Image-to-Video

4K Landscape Image-to-Video

Poll Status

Status Values

Compatibility Status Polling

Download Video

Python Complete Example

FAQ

Getting Started

Core API

Text APIs

Video Generation APIs

Image Generation APIs

AI Understanding

Documentation Index

​Overview

​Pricing Advantage

​Token Setup

​Supported Models

​Parameters

​Core Parameters

​Duration and Resolution

​Text-to-Video

​Create a Task

​Create Response

​Image-to-Video

​4K Landscape Image-to-Video

​Poll Status

​Status Values

​Compatibility Status Polling

​Download Video

​Python Complete Example

​FAQ

Overview

Pricing Advantage

Token Setup

Supported Models

Parameters

Core Parameters

Duration and Resolution

Text-to-Video

Create a Task

Create Response

Image-to-Video

4K Landscape Image-to-Video

Poll Status

Status Values

Compatibility Status Polling

Download Video

Python Complete Example

FAQ