# Veo Video Generation

Source: https://docs.aicentos.com/en/veo-video

Language: en

> Call Google Veo video generation models via aicentos — text-to-video, image-to-video, first/last frames, reference images

This guide is for developers: how to call Google Veo video generation models through aicentos. The API follows the OpenAI Videos API compatible format — use the `openai` channel type when integrating downstream.

## Model capabilities

Billing is based on video generation duration in seconds. See the aicentos console for exact unit prices; the final charge is based on the system's actual billing records.

### Official capabilities vs. what aicentos exposes

| Model                           | Supported durations | Supported resolutions | Aspect ratios | Audio        | Notes                                                                                                                                  |
| ------------------------------- | ------------------- | --------------------- | ------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| `veo-3.1-generate-preview`      | 4, 6, 8             | 720p, 1080p, 4k       | 16:9, 9:16    | Native audio | 1080p and 4k support 8 seconds only; 8 seconds is recommended when using image features such as reference images or first/last frames. |
| `veo-3.1-fast-generate-preview` | 4, 6, 8             | 720p, 1080p, 4k       | 16:9, 9:16    | Native audio | 1080p and 4k support 8 seconds only; 8 seconds is recommended when using image features such as reference images or first/last frames. |

Reference docs:

* [Google Gemini API Veo video generation](https://ai.google.dev/gemini-api/video)
* [Veo reference images](https://ai.google.dev/gemini-api/video#reference_images)
* [Veo first and last frames](https://ai.google.dev/gemini-api/video#first_and_last_frame)
* [Veo aspect ratio](https://ai.google.dev/gemini-api/video#aspect_ratio)

### Aspect ratio

| Model                           | 16:9 landscape | 9:16 portrait | Default | Recommendations                                              |
| ------------------------------- | -------------- | ------------- | ------- | ------------------------------------------------------------ |
| `veo-3.1-generate-preview`      | Supported      | Supported     | 16:9    | 4K requires 8 seconds; video extension is not yet available. |
| `veo-3.1-fast-generate-preview` | Supported      | Supported     | 16:9    | 4K requires 8 seconds; video extension is not yet available. |

Set the aspect ratio via `metadata.aspectRatio` in JSON or the `aspectRatio` form field:

```bash
{
  "metadata": {
    "aspectRatio": "9:16"
  }
}
```

If `aspectRatio` is not passed explicitly, the system derives it from `size` first — for example, `1280x720` maps to 16:9 and `720x1280` to 9:16. If `size` is missing too, the upstream defaults to 16:9.

### Audio

| Model                           | Official audio capability | generateAudio support | Recommendation                                                         |
| ------------------------------- | ------------------------- | --------------------- | ---------------------------------------------------------------------- |
| `veo-3.1-generate-preview`      | Native audio              | Not supported         | Do not pass `generateAudio`; describe any sound effects in the prompt. |
| `veo-3.1-fast-generate-preview` | Native audio              | Not supported         | Do not pass `generateAudio`; describe any sound effects in the prompt. |

The Veo 3.1 series generates audio natively, but the current Gemini API Veo parameter list does not expose `generateAudio` as a controllable parameter. Passing it may cause the upstream to return `INVALID_ARGUMENT`.

To control the audio, describe the dialogue, ambient sound, sound effects or music style in the prompt, for example:

```bash
A lighthouse by the sea at dusk, waves gently lapping the rocks, low wind and distant seabirds, cinematic lighting, stable camera movement
```

## Image input capabilities

| Capability                             | Official Google Veo                             | aicentos API support | Notes                                                                                                                                |
| -------------------------------------- | ----------------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| Single initial image to video          | Supported                                       | Supported            | Upload 1 image via `input_reference` as the video's starting frame.                                                                  |
| First/last frame / frame interpolation | Veo 3.1 series supports image + lastFrame       | Supported            | First frame via `input_reference`, last frame via `last_frame` or `lastFrame`. Veo 3.1 series and 8 seconds recommended.             |
| Multiple reference images              | Veo 3.1 series supports up to 3 referenceImages | Supported            | Upload via `reference_image`, `reference_images` or `referenceImages`; `referenceType` only supports `asset`. 8 seconds recommended. |
| Video extension                        | Veo 3.1 / Fast can extend existing Veo videos   | Not yet supported    | The current aicentos API does not expose official video input.                                                                       |

* Image MIME types supported: `image/jpeg`, `image/png`, `image/webp`. Send a file or Base64; remote image URLs are not recommended.
* Reference-image note: the upstream does not support `negativePrompt` in the reference-image scenario and may return `Negative prompt is not supported in your use case`. Do not pass `negativePrompt` with reference-image requests.
* Implementation note: the Gemini API Veo `predictLongRunning` image input uses `bytesBase64Encoded` + `mimeType`, not the `inlineData` used by plain `generateContent`. aicentos converts multipart-uploaded images into the format the upstream expects.

## Billing rules

* Billed by video generation duration in seconds. Use one of the durations each model supports (see the table above); arbitrary values are not recommended.
* If the request does not specify a duration, billing defaults to 8 seconds.
* Duration resolution order: `metadata.durationSeconds` > `duration` > `seconds` > default 8 seconds.
* Resolution detection order: `metadata.resolution` > `size` > default 720p.
* 720p / 1080p / 4K are billed under the same rules; there is no separate resolution surcharge.
* `aspectRatio` only controls landscape vs. portrait; it does not change the price.
* 4K supports 8 seconds only.
* See the aicentos console for exact unit prices.

## API endpoints

These 3 endpoints are recommended:

| Purpose         | Method | Path                           |
| --------------- | ------ | ------------------------------ |
| Create task     | POST   | `/v1/videos`                   |
| Check status    | GET    | `/v1/videos/{task_id}`         |
| Download result | GET    | `/v1/videos/{task_id}/content` |

To get the result URL directly from the status query, you can also use:

| Purpose                         | Method | Path                              |
| ------------------------------- | ------ | --------------------------------- |
| Check status and get result URL | GET    | `/v1/video/generations/{task_id}` |

### Authentication

```bash
export BASE_URL="https://aicentos.com"
export AICENTOS_API_KEY="sk-xxxxxx"
```

All requests include:

```bash
-H "Authorization: Bearer $AICENTOS_API_KEY"
```

### Create a text-to-video task

```bash
curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-generate-preview",
    "prompt": "A lighthouse by the sea at dusk, slow push-in shot, waves gently lapping the rocks, cinematic lighting, stable camera movement",
    "seconds": "8",
    "size": "1280x720",
    "metadata": {
      "negativePrompt": "blurry, watermark, distorted, low quality",
      "resolution": "720p",
      "aspectRatio": "16:9",
      "seed": 20260401
    }
  }'
```

Typical response:

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

### Create an image-to-video task (first frame)

For image-to-video, `multipart/form-data` is recommended, and the first-frame image field must be named `input_reference`.

```bash
curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -H "Accept: application/json" \
  -F "model=veo-3.1-generate-preview" \
  -F "prompt=The girl in the frame turns her head toward the camera, a light breeze moves her hair, city lights in the background softly blurred, smooth steady push-in" \
  -F "input_reference=@./first-frame.png;type=image/png" \
  -F "seconds=8" \
  -F "size=1280x720" \
  -F "resolution=720p" \
  -F "aspectRatio=16:9" \
  -F "negativePrompt=blurry, watermark, deformed hands" \
  -F "seed=20260401"
```

### Create a first/last frame task

First/last frame tasks require both frames: first frame via `input_reference`, last frame via `last_frame` or `lastFrame`.

```bash
curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -H "Accept: application/json" \
  -F "model=veo-3.1-generate-preview" \
  -F "prompt=Transition naturally from the first frame with a girl to the last frame with a boy, smooth steady push-in, blurred city lights, hair and clothes moving slightly in the breeze, a natural and realistic transition" \
  -F "input_reference=@./first-frame.png;type=image/png" \
  -F "last_frame=@./last-frame.png;type=image/png" \
  -F "seconds=8" \
  -F "size=1280x720" \
  -F "resolution=720p" \
  -F "aspectRatio=16:9" \
  -F "negativePrompt=blurry, watermark, distorted face, deformed hands" \
  -F "seed=20260402"
```

### Create a reference-image task

Reference-image tasks are supported on the Veo 3.1 series only, up to 3 images, with `referenceType` limited to `asset`. Field names: `reference_image`, `reference_images` or `referenceImages`. Do not pass `negativePrompt` on reference-image tasks.

```bash
curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -H "Accept: application/json" \
  -F "model=veo-3.1-generate-preview" \
  -F "prompt=Follow the characters' appearance from the two images and the night-city atmosphere to generate a cinematic two-person street shot, smooth steady push-in, background lights softly blurred, the characters looking naturally at the camera" \
  -F "reference_image=@./ref-1.png;type=image/png" \
  -F "reference_image=@./ref-2.png;type=image/png" \
  -F "reference_type=asset" \
  -F "seconds=8" \
  -F "size=1280x720" \
  -F "resolution=720p" \
  -F "aspectRatio=16:9" \
  -F "seed=20260403"
```

JSON / Base64 is also supported:

```bash
{
  "model": "veo-3.1-generate-preview",
  "prompt": "Generate an ad shot using the product appearance from the reference images",
  "duration": 8,
  "metadata": {
    "resolution": "720p",
    "aspectRatio": "16:9",
    "referenceImages": [
      {
        "image": {
          "bytesBase64Encoded": "BASE64_IMAGE",
          "mimeType": "image/png"
        },
        "referenceType": "asset"
      }
    ]
  }
}
```

### Check task status

First save the `id` or `task_id` returned by the create endpoint:

```bash
export TASK_ID="task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

Then check the status:

```bash
curl -X GET "$BASE_URL/v1/videos/$TASK_ID" \
  -H "Authorization: Bearer $AICENTOS_API_KEY"
```

While in progress, a typical response:

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

When complete, a typical response:

```bash
{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "veo-3.1-generate-preview",
  "status": "completed",
  "progress": 100,
  "created_at": 1775025000,
  "completed_at": 1775025068
}
```

### Check task status and get the result URL

To get a downloadable URL directly from the status query, call:

```bash
curl -X GET "$BASE_URL/v1/video/generations/$TASK_ID" \
  -H "Authorization: Bearer $AICENTOS_API_KEY"
```

Typical response:

```bash
{
  "code": "success",
  "message": "",
  "data": {
    "error": null,
    "format": "mp4",
    "metadata": null,
    "status": "succeeded",
    "task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "url": "https://aicentos.com/v1/videos/task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/content"
  }
}
```

### Download the video

Once the task completes, download directly:

```bash
curl -L "$BASE_URL/v1/videos/$TASK_ID/content" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -o veo-result.mp4
```

## Status values

`GET /v1/videos/{task_id}` mainly returns these statuses:

| Status        | Meaning    |
| ------------- | ---------- |
| `queued`      | Queued     |
| `in_progress` | Generating |
| `completed`   | Completed  |
| `failed`      | Failed     |

`GET /v1/video/generations/{task_id}` mainly returns these statuses:

| Status       | Meaning    |
| ------------ | ---------- |
| `queued`     | Queued     |
| `processing` | Generating |
| `succeeded`  | Succeeded  |
| `failed`     | Failed     |

## Integration notes

* `prompt` is required.
* For image-to-video, the image field must be named `input_reference`.
* First/last frame tasks require both frames: first frame via `input_reference`, last frame via `last_frame` or `lastFrame`.
* Reference-image tasks are supported on the Veo 3.1 series only, up to 3 images, and must use 8 seconds.
* Do not pass `negativePrompt` on reference-image tasks.
* For Gemini image-to-video, remote image URLs are not recommended; send a file or Base64.
* Poll `GET /v1/videos/{task_id}` and download only after `status=completed`.
* The Veo 3.1 series accepts 4, 6 or 8 seconds; 1080p and 4k require 8 seconds. Use `aspectRatio=16:9` for landscape and `aspectRatio=9:16` for portrait; if omitted, 16:9 is assumed.
* Do not pass `generateAudio`. The Veo 3.1 series generates audio natively, but the current Gemini API does not support toggling audio via `generateAudio`; passing it may cause the upstream to return `INVALID_ARGUMENT`.
* To control the audio, describe the dialogue, ambient sound, sound effects or music style in the prompt.
* Official Veo 3.1 supports video extension, but the current aicentos API does not yet expose official video input.