> ## Documentation Index
> Fetch the complete documentation index at: https://apixo.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Veo 3.1
> Google video generation API for text-to-video, first/last frame, reference-guided, and extend workflows
## Overview
Veo 3.1 is a Google video generation model for text-to-video, first/last-frame animation, reference-guided video creation, and extension of completed Veo 3.1 tasks. Use this page when you are ready to call the API after trying the model in the APIXO playground.
| Capability | Value |
| ----------------------- | --------------------------------------------------------------------------------- |
| Model ID | `veo-3-1` |
| Modes | `lite`, `fast`, `quality`, `extend-fast`, `extend-quality` |
| Generation types | `TEXT_2_VIDEO`, `FIRST_AND_LAST_FRAMES_2_VIDEO`, `REFERENCE_2_VIDEO` |
| Extend source | Completed non-extend APIXO `veo-3-1` `taskId` from the same account |
| Prompt length | 1-10000 characters |
| Supported durations | `4`, `6`, `8` seconds |
| Aspect ratios | `16:9`, `9:16`, `auto` |
| Output resolutions | `720p`, `1080p`, `4k` |
| First/last frame inputs | Up to 2 image URLs |
| Reference inputs | Up to 3 image URLs; `fast` mode only; `REFERENCE_2_VIDEO` only supports 8 seconds |
| Output | Video URLs in `resultJson.resultUrls` |
## Endpoint and authentication
Base URL:
```text theme={null}
https://api.apixo.ai/api/v1
```
| Method | Endpoint | Purpose |
| ------ | ------------------------------------- | ------------------------------------- |
| `POST` | `/generateTask/veo-3-1` | Submit a generation task |
| `GET` | `/statusTask/veo-3-1?taskId={taskId}` | Poll task status and retrieve results |
All requests require your APIXO API key:
```http theme={null}
Authorization: Bearer YOUR_API_KEY
```
Submit requests also require:
```http theme={null}
Content-Type: application/json
```
## Copy-paste async quickstart
This minimal request submits a text-to-video task and returns a `taskId`.
```bash theme={null}
curl -X POST "https://api.apixo.ai/api/v1/generateTask/veo-3-1" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"request_type": "async",
"input": {
"mode": "lite",
"prompt": "a cinematic flyover of a futuristic city at sunrise",
"generationType": "TEXT_2_VIDEO",
"duration": 6,
"resolution": "1080p",
"aspect_ratio": "16:9"
}
}'
```
Successful response:
```json theme={null}
{
"code": 200,
"message": "success",
"data": {
"taskId": "task_12345678"
}
}
```
Save the `taskId`; you need it to poll for the final result.
## Poll for result
```bash theme={null}
curl -X GET "https://api.apixo.ai/api/v1/statusTask/veo-3-1?taskId=task_12345678" \
-H "Authorization: Bearer YOUR_API_KEY"
```
Processing response:
```json theme={null}
{
"code": 200,
"message": "success",
"data": {
"taskId": "task_12345678",
"state": "processing",
"createTime": 1767965610929
}
}
```
Success response:
```json theme={null}
{
"code": 200,
"message": "success",
"data": {
"taskId": "task_12345678",
"state": "success",
"resultJson": "{\"resultUrls\":[\"https://file.apixo.ai/xxx.mp4\"]}",
"createTime": 1767965610929,
"completeTime": 1767965730929,
"costTime": 120000
}
}
```
Failed response:
```json theme={null}
{
"code": 200,
"message": "success",
"data": {
"taskId": "task_12345678",
"state": "failed",
"failCode": "SensitiveContent",
"failMsg": "Content violates safety policy, please adjust the prompt",
"createTime": 1767965610929,
"completeTime": 1767965620132,
"costTime": 9203
}
}
```
Parse `resultJson` after `state` becomes `success`:
```javascript theme={null}
const payload = JSON.parse(data.resultJson);
const videoUrls = payload.resultUrls;
```
## Request body
### Text-to-video
```json theme={null}
{
"request_type": "async",
"input": {
"mode": "lite",
"prompt": "a cinematic flyover of a futuristic city at sunrise",
"generationType": "TEXT_2_VIDEO",
"duration": 6,
"resolution": "1080p",
"aspect_ratio": "16:9"
}
}
```
### First/last frame to video
```json theme={null}
{
"request_type": "async",
"input": {
"mode": "quality",
"prompt": "a calm ocean turning into a storm",
"generationType": "FIRST_AND_LAST_FRAMES_2_VIDEO",
"duration": 6,
"resolution": "720p",
"image_urls": [
"https://example.com/frame_start.jpg",
"https://example.com/frame_end.jpg"
],
"aspect_ratio": "9:16"
}
}
```
### Reference-to-video
```json theme={null}
{
"request_type": "async",
"input": {
"mode": "fast",
"prompt": "turn these references into a dynamic action shot",
"duration": 8,
"resolution": "720p",
"generationType": "REFERENCE_2_VIDEO",
"image_urls": [
"https://example.com/ref1.jpg",
"https://example.com/ref2.jpg"
],
"aspect_ratio": "9:16"
}
}
```
### Extend a completed Veo 3.1 task
```json theme={null}
{
"request_type": "async",
"input": {
"mode": "extend-quality",
"taskId": "task_id_from_completed_veo31_task",
"prompt": "extend this scene into a dramatic sunset over the city skyline",
"watermark": "YourBrand"
}
}
```
## Parameters
Result delivery mode. Use `async` for polling with `statusTask`, or `callback` for webhook delivery.
Required when `request_type` is `callback`. Must be a public HTTPS URL that can receive the final task payload. See [Webhooks](/api-reference/webhooks).
Veo 3.1 input parameters.
Model mode. Supported values: `lite`, `fast`, `quality`, `extend-fast`, `extend-quality`. `REFERENCE_2_VIDEO` only supports `fast`.
Required only for `extend-fast` and `extend-quality`. Use the internal task ID returned by a completed non-extend `/generateTask/veo-3-1` task from the same account.
Text prompt describing the video. Supports 1-10000 characters.
Required for `lite`, `fast`, and `quality` generation modes. Supported values: `TEXT_2_VIDEO`, `FIRST_AND_LAST_FRAMES_2_VIDEO`, `REFERENCE_2_VIDEO`. Not used by `extend-fast` or `extend-quality`.
Optional video duration in seconds. Supported values: `4`, `6`, `8`. Default is `8`. For `REFERENCE_2_VIDEO`, only `8` is supported.
Optional output resolution. Supported values: `720p`, `1080p`, `4k`. Default is `720p`.
Output aspect ratio. Supported values: `16:9`, `9:16`, `auto`.
Image URLs for image-guided workflows. Required for `FIRST_AND_LAST_FRAMES_2_VIDEO` and `REFERENCE_2_VIDEO`. Supports up to 2 images for first/last-frame generation and up to 3 images for reference generation.
Optional watermark text.
Optional random seed for reproducible generation attempts.
`REFERENCE_2_VIDEO` requires `mode: "fast"`. Use up to 3 public image URLs for reference generation. It only supports `8` seconds.
`extend-fast` and `extend-quality` require `input.taskId`. The base task must be a completed non-extend Veo 3.1 task owned by the same account. An extend task cannot be used as the base task for another extend request.
Use public, directly reachable image URLs. JPG, JPEG, and PNG inputs up to 10 MB are recommended for image-guided workflows.
## Response format
### Submit task response
`POST /generateTask/veo-3-1` returns a task ID when the task is accepted:
API status code. `200` means the task was accepted.
Human-readable status message.
Unique task identifier used with the status endpoint.
### Status response fields
Unique task identifier.
Current task state: `pending`, `processing`, `success`, or `failed`.
JSON string containing the generated video URLs. Present when `state` is `success`.
Machine-readable failure code. Present when `state` is `failed`.
Human-readable failure message. Present when `state` is `failed`.
Task creation timestamp in Unix milliseconds.
Task completion timestamp in Unix milliseconds. Present after completion.
Processing duration in milliseconds. Present after successful or failed completion when available.
## Webhook callback mode
Use callback mode when your backend should receive the final result automatically instead of polling.
```bash theme={null}
curl -X POST "https://api.apixo.ai/api/v1/generateTask/veo-3-1" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"request_type": "callback",
"callback_url": "https://your-server.com/webhooks/apixo",
"input": {
"mode": "fast",
"prompt": "a product reveal shot with smooth camera motion and dramatic lighting",
"generationType": "TEXT_2_VIDEO",
"duration": 6,
"resolution": "1080p",
"aspect_ratio": "16:9"
}
}'
```
See [Webhooks](/api-reference/webhooks) for delivery requirements and retry behavior.
## Billing
Veo 3.1 is billed per generated or extended video task. For generation modes, the selected `mode` and `resolution` determine the unit price. Extend modes have their own per-task pricing on the Pricing page.
Current pricing does not change with `duration`; `4`, `6`, and `8` second requests use the same per-video price for a given `mode` + `resolution`.
| Generation mode | `720p` | `1080p` | `4k` |
| --------------- | --------------- | ---------------- | --------------- |
| `lite` | `$0.15 / video` | `$0.25 / video` | `$0.75 / video` |
| `fast` | `$0.30 / video` | `$0.375 / video` | `$0.90 / video` |
| `quality` | `$1.60 / video` | `$1.80 / video` | `$2.40 / video` |
Market reference pricing used for comparison:
| Generation mode | `720p` | `1080p` | `4k` |
| --------------- | --------------- | --------------- | --------------- |
| `lite` | `$3.20 / video` | `$3.20 / video` | `$4.80 / video` |
| `fast` | `$1.20 / video` | `$1.20 / video` | `$2.40 / video` |
| `quality` | `$3.20 / video` | `$3.20 / video` | `$4.80 / video` |
For current route and market comparison pricing, see [Pricing](https://apixo.ai/pricing).
## Latency and polling
Actual latency may vary by prompt complexity, image inputs, selected route, and current queue load.
| Mode | Typical generation time | Recommended first poll | Poll interval |
| ---------------- | ----------------------- | -------------------------- | ------------- |
| `lite` | 1-3 minutes | 60-90s after task creation | 5-10s |
| `fast` | 1-3 minutes | 60-90s after task creation | 5-10s |
| `quality` | 1-3 minutes | 90s after task creation | 5-10s |
| `extend-fast` | 1-3 minutes | 30-60s after task creation | 5-10s |
| `extend-quality` | 1-3 minutes | 60-90s after task creation | 5-10s |
For production video workloads, use callback mode to avoid frequent polling.
Rate limits and concurrency can vary by account, API key, and route. If you receive `429`, slow down requests and retry with backoff. For account-level details, see [System APIs](/api-reference/system).
## Errors and troubleshooting
### HTTP errors
| Code | Meaning | What to do |
| ----- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| `400` | Invalid request body, missing parameter, unsupported mode, unsupported generation type, or invalid image input | Fix the request before retrying |
| `401` | Missing or invalid API key | Check the `Authorization` header |
| `402` | Insufficient balance or quota | Add balance or switch account/key |
| `403` | Key or route cannot access the model | Check permissions and route strategy |
| `429` | Rate limit or concurrency limit reached | Retry with exponential backoff |
| `500` | Server error | Retry with backoff |
| `502` | Upstream service error | Retry with backoff |
| `504` | Upstream timeout | Retry or use callback mode for long-running jobs |
### Task failure codes
| Fail code | Meaning | What to do |
| ---------------------- | --------------------------------------------------- | ---------------------------------------------------------------------- |
| `SensitiveContent` | Prompt or image input was rejected by safety checks | Change the prompt or input image |
| `PromptInvalid` | Prompt is invalid or rejected upstream | Rewrite the prompt and retry |
| `ImageFormatIncorrect` | Input image format is not accepted | Use a public JPG, JPEG, or PNG URL |
| `MissingParameter` | A required parameter is missing | Check `mode`, `prompt`, `generationType`, and conditional `image_urls` |
| `RateLimited` | Upstream rate limit reached | Retry with exponential backoff |
| `Timeout` | Upstream service timed out | Retry, reduce input complexity, or use callback mode |
| `Unknown error` | Upstream service returned an unmapped failure | Retry later or contact support with the `taskId` |
### Common validation issues
| Issue | Fix |
| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
| Missing `mode` | Set `mode` to `lite`, `fast`, `quality`, `extend-fast`, or `extend-quality` |
| Missing `generationType` | For `lite`, `fast`, and `quality`, set one of the supported generation type values |
| Missing extend `taskId` | For `extend-fast` and `extend-quality`, provide the internal `taskId` from a completed non-extend Veo 3.1 task |
| Extending an extend task | Use a completed non-extend Veo 3.1 task as the base task |
| `REFERENCE_2_VIDEO` with `lite` or `quality` | Use `mode: "fast"` |
| `REFERENCE_2_VIDEO` with duration other than `8` | Use `duration: 8` |
| Too many images | Use up to 2 images for first/last-frame generation or up to 3 images for reference generation |
| Empty image URL | Provide non-empty, publicly reachable image URLs |
See [Error Codes](/api-reference/errors) for the full error reference.
## Related links
* [Generation API Overview](/models)
* [Generate Task](/api-reference/generate-task)
* [Status Task](/api-reference/status-task)
* [Webhooks](/api-reference/webhooks)
* [Error Codes](/api-reference/errors)
* [Parameter Specification](/api-reference/parameters)
* [Routing Strategies](/concepts/routing-strategies)
* [Pricing](https://apixo.ai/pricing)