> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unifically.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Veo 3.1

> Generate videos with Google's Veo 3.1 models. See supported inputs, parameters, pricing, response fields, and API examples.

Generate videos with Google's Veo 3.1 modes through the unified task API. Veo 3.1 supports text-to-video, first-frame, first-and-last-frame, and reference-to-video workflows.

## Models

| Mode         | Model ID                      | Character references | Notes                                                           |
| ------------ | ----------------------------- | -------------------- | --------------------------------------------------------------- |
| Lite         | `google/veo-3.1-lite`         | Yes                  | Balanced default                                                |
| Fast         | `google/veo-3.1-fast`         | Yes                  | Faster generation                                               |
| Quality      | `google/veo-3.1-quality`      | No                   | Higher quality text/image-to-video, but no character references |
| Lite Relaxed | `google/veo-3.1-lite-relaxed` | Yes                  | Relaxed queue variant                                           |

## Parameters

| Parameter              | Type      | Required | Default  | Description                                                                                                                                                                                                                                |
| ---------------------- | --------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `prompt`               | string    | Yes      | -        | Main video prompt. Use `@ImageN` or `@CharacterN` to point at a specific reference. Unknown references are left as plain text.                                                                                                             |
| `seed`                 | integer   | No       | Random   | Seed sent to Veo. If omitted, a seed is generated automatically and returned when available.                                                                                                                                               |
| `aspect_ratio`         | string    | No       | `"16:9"` | Output orientation. Allowed: `"16:9"`, `"9:16"`.                                                                                                                                                                                           |
| `duration`             | integer   | No       | `4`      | Text/start-frame requests allow `4`, `6`, or `8`. Any `reference_image_urls` or `reference_characters` reference locks duration to `8`.                                                                                                    |
| `resolution`           | string    | No       | `"720p"` | Output resolution. Allowed: `"720p"`, `"1080p"`, `"4k"`. With `"1080p"` or `"4k"`, the video is upscaled as part of the same task before it completes — no separate upscale task needed. `"720p"` returns the native, non-upscaled output. |
| `start_image_url`      | string    | No       | -        | Publicly reachable image URL used as the first frame. Cannot be combined with `reference_image_urls` or `reference_characters`.                                                                                                            |
| `end_image_url`        | string    | No       | -        | Publicly reachable image URL used as the final frame. Requires `start_image_url`; cannot be used by itself.                                                                                                                                |
| `reference_image_urls` | string\[] | No       | -        | Image references for reference-to-video. Max 3 total expanded image URLs across `reference_image_urls` and character images. Cannot be combined with start/end frame fields.                                                               |
| `reference_characters` | array     | No       | -        | Character references for reference-to-video. Max 3 total expanded image URLs across images and character `image_urls`. Not available on Quality.                                                                                           |
| `voice`                | string    | No       | -        | Request-level Google Flow voice preset ID. Requires at least one image or character reference. See [available voices](/api-reference/resources#get-google-veo-voices).                                                                     |
| `allow_audio_filtered` | boolean   | No       | `false`  | When `true`, the generation runs without audio instead of failing when the audio track is filtered.                                                                                                                                        |
| `nsfw_check`           | boolean   | No       | `true`   | Check uploaded media inputs for NSFW content                                                                                                                                                                                               |

<Warning>
  First/last-frame mode and reference mode are separate generation modes. Do not combine `start_image_url` or `end_image_url` with `reference_image_urls` or `reference_characters`.
</Warning>

## Text-to-Video

```bash theme={null}
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "google/veo-3.1-fast",
    "input": {
      "prompt": "A cinematic shot of a cat walking through a garden",
      "aspect_ratio": "16:9",
      "duration": 4,
      "resolution": "1080p"
    }
  }'
```

## First and Last Frame

Use `start_image_url` and optionally `end_image_url` to guide the video with first and final frames.

```bash theme={null}
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "google/veo-3.1-fast",
    "input": {
      "prompt": "Camera slowly zooms in",
      "start_image_url": "https://example.com/start.jpg",
      "end_image_url": "https://example.com/end.jpg",
      "aspect_ratio": "16:9",
      "duration": 6
    }
  }'
```

## References and Characters

Use `reference_image_urls` for image references and `reference_characters` for character identity consistency. Character references are supported on Lite, Fast, and Lite Relaxed. They are not supported on Quality.

```bash theme={null}
curl -X POST https://api.unifically.com/v1/tasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "google/veo-3.1-fast",
    "input": {
      "prompt": "Make @Character1 walk through a glass city at sunrise, speaking softly to camera.",
      "reference_characters": [
        {
          "image_urls": [
            "https://example.com/ada.png"
          ],
          "name": "Ada",
          "description": "warm, sharp, curious"
        }
      ],
      "duration": 8,
      "aspect_ratio": "9:16"
    }
  }'
```

## Character References

Provide each character as an object with `image_urls`. Even one-image characters must use an array.

```json theme={null}
{
  "image_urls": [
    "https://example.com/character-front.png",
    "https://example.com/character-profile.png"
  ],
  "name": "Ada",
  "description": "warm, sharp, curious"
}
```

| Field         | Type      | Required | Description                                                                                                                            |
| ------------- | --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `image_urls`  | string\[] | Yes\*    | Publicly reachable character image URLs. Use 1-10 images for a character entity. Each URL still consumes a model reference-image slot. |
| `name`        | string    | No       | Display name for the character.                                                                                                        |
| `description` | string    | No       | Character notes/personality text.                                                                                                      |

\*`image_urls` must contain at least one URL.

<Info>
  `image_url` and plain string character entries are not supported. Use `image_urls` for every character, including one-image characters.
</Info>

## Prompt References

| Token                        | Refers to                                                                                                                                        |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `@Image1`, `@Image2`         | Items from `reference_image_urls` only                                                                                                           |
| `@Character1`, `@Character2` | Items from `reference_characters` only. With multiple `image_urls`, the token points to the character item; extra images are identity references |

## Duration

| Mode                 | What you send                                    | 4s  | 6s  | 8s  |
| -------------------- | ------------------------------------------------ | --- | --- | --- |
| Text-to-video        | `prompt` only                                    | Yes | Yes | Yes |
| First-frame          | `prompt` + `start_image_url`                     | Yes | Yes | Yes |
| First-and-last-frame | `prompt` + `start_image_url` + `end_image_url`   | Yes | Yes | Yes |
| Reference-to-video   | `reference_image_urls` or `reference_characters` | No  | No  | Yes |

## Rejected Combinations

| Input                                                                                   | Why rejected                                                            |
| --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `end_image_url` without `start_image_url`                                               | The ending frame needs a starting frame.                                |
| `start_image_url`/`end_image_url` with `reference_image_urls` or `reference_characters` | First/last-frame mode and reference mode are separate generation modes. |
| `reference_characters` on `google/veo-3.1-quality`                                      | Quality does not expose character references.                           |
| Any image or character reference with `duration` other than `8`                         | Veo reference-image generation is 8 seconds only.                       |
| More than 3 total expanded image URLs                                                   | Veo reference generation limit.                                         |
| `image_url` on a character                                                              | Use `image_urls` instead, even for one image.                           |
| Plain string character entries                                                          | Character entries must be objects with `image_urls`.                    |
| Empty `image_urls`                                                                      | A character needs at least one image.                                   |
| More than 10 `image_urls` on one character                                              | Character entity image limit.                                           |

## Extend

Extend a previously generated video using `google/veo-3.1-extend`. The aspect ratio is inherited from the source task.

| Parameter  | Type    | Required | Description                                       |
| ---------- | ------- | -------- | ------------------------------------------------- |
| `prompt`   | string  | Yes      | Text prompt for the extended content              |
| `task_id`  | string  | Yes      | Task ID of a completed generation                 |
| `model`    | string  | Yes      | One of: `lite`, `fast`, `quality`, `lite-relaxed` |
| `duration` | integer | No       | Must be `8`. Default `8`.                         |
| `seed`     | integer | No       | Reproducibility seed                              |

## Upscale

Upscale a completed video to a higher resolution using `google/veo-3.1-upscale`. The same model upscales **Veo 3.1 and Gemini Omni Flash** videos (Omni Flash, Omni Flash 1.1 and their video-edit variants) — pass the `task_id` of any of them; there is no separate Omni Flash upscaler. If you already know the target resolution up front, pass `resolution` on the generation request instead — the upscale then happens within the same task.

| Parameter    | Type   | Required | Description                                                                                                                                                  |
| ------------ | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `task_id`    | string | Yes      | Task ID of a completed Veo 3.1 or Gemini Omni Flash generation                                                                                               |
| `resolution` | string | Yes      | `"720p"`, `"1080p"`, or `"4k"`. `"720p"` is only valid for 360p Gemini Omni Flash 1.1 source videos; `"1080p"`/`"4k"` are only valid for 720p source videos. |

<Info>
  360p videos (Gemini Omni Flash 1.1) can only be upscaled to 720p — not directly to 1080p or 4k. 720p videos from Veo 3.1 or Gemini Omni Flash can be upscaled to 1080p or 4k.
</Info>

## Response

```json theme={null}
{
  "code": 200,
  "success": true,
  "data": {
    "task_id": "abc123def456",
    "status": "processing"
  }
}
```

<Note>
  **Volume discounts** are available for almost all models. Reach out at [contact@unifically.com](mailto:contact@unifically.com) to discuss custom pricing.
</Note>