Veo 3.1

Overview

Veo 3.1 is a Google video generation model for text-to-video, first/last-frame animation, and reference-guided video creation. 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	`quality`, `fast`
Generation types	`TEXT_2_VIDEO`, `FIRST_AND_LAST_FRAMES_2_VIDEO`, `REFERENCE_2_VIDEO`
Prompt length	1-10000 characters
Aspect ratios	`16:9`, `9:16`, `auto`
First/last frame inputs	Up to 2 image URLs
Reference inputs	Up to 3 image URLs; `fast` mode and `16:9` only
Output	Video URLs in `resultJson.resultUrls`

Endpoint and authentication

Base URL:

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:

Authorization: Bearer YOUR_API_KEY

Submit requests also require:

Content-Type: application/json

Copy-paste async quickstart

This minimal request submits a text-to-video task and returns a taskId.

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": "quality",
      "prompt": "a cinematic flyover of a futuristic city at sunrise",
      "generationType": "TEXT_2_VIDEO",
      "aspect_ratio": "16:9"
    }
  }'

Successful response:

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678"
  }
}

Save the taskId; you need it to poll for the final result.

Poll for result

curl -X GET "https://api.apixo.ai/api/v1/statusTask/veo-3-1?taskId=task_12345678" \
  -H "Authorization: Bearer YOUR_API_KEY"

Processing response:

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "processing",
    "createTime": 1767965610929
  }
}

Success response:

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "success",
    "resultJson": "{\"resultUrls\":[\"https://r2.apixo.ai/xxx.mp4\"]}",
    "createTime": 1767965610929,
    "completeTime": 1767965730929,
    "costTime": 120000
  }
}

Failed response:

{
  "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:

const payload = JSON.parse(data.resultJson);
const videoUrls = payload.resultUrls;

Request body

Text-to-video

{
  "request_type": "async",
  "input": {
    "mode": "quality",
    "prompt": "a cinematic flyover of a futuristic city at sunrise",
    "generationType": "TEXT_2_VIDEO",
    "aspect_ratio": "16:9"
  }
}

First/last frame to video

{
  "request_type": "async",
  "input": {
    "mode": "quality",
    "prompt": "a calm ocean turning into a storm",
    "generationType": "FIRST_AND_LAST_FRAMES_2_VIDEO",
    "image_urls": [
      "https://example.com/frame_start.jpg",
      "https://example.com/frame_end.jpg"
    ],
    "aspect_ratio": "9:16"
  }
}

Reference-to-video

{
  "request_type": "async",
  "input": {
    "mode": "fast",
    "prompt": "turn these references into a dynamic action shot",
    "generationType": "REFERENCE_2_VIDEO",
    "image_urls": [
      "https://example.com/ref1.jpg",
      "https://example.com/ref2.jpg"
    ],
    "aspect_ratio": "16:9"
  }
}

Parameters

request_type

string

default:"async"

required

Result delivery mode. Use async for polling with statusTask, or callback for webhook delivery.

callback_url

string

Required when request_type is callback. Must be a public HTTPS URL that can receive the final task payload. See Webhooks.

input

object

required

Veo 3.1 input parameters.

Show properties

mode

string

required

Model mode. Supported values: quality, fast. REFERENCE_2_VIDEO only supports fast.

prompt

string

required

Text prompt describing the video. Supports 1-10000 characters.

generationType

string

required

Generation workflow. Supported values: TEXT_2_VIDEO, FIRST_AND_LAST_FRAMES_2_VIDEO, REFERENCE_2_VIDEO.

aspect_ratio

string

Output aspect ratio. Supported values: 16:9, 9:16, auto. REFERENCE_2_VIDEO only supports 16:9.

image_urls

string[]

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.

watermark

string

default:""

Optional watermark text.

seed

integer

Optional random seed for reproducible generation attempts.

REFERENCE_2_VIDEO requires mode: "fast" and aspect_ratio: "16:9". Other combinations are rejected.

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:

code

integer

API status code. 200 means the task was accepted.

message

string

Human-readable status message.

data.taskId

string

Unique task identifier used with the status endpoint.

Status response fields

taskId

string

Unique task identifier.

state

string

Current task state: pending, processing, success, or failed.

resultJson

string

JSON string containing the generated video URLs. Present when state is success.

failCode

string

Machine-readable failure code. Present when state is failed.

failMsg

string

Human-readable failure message. Present when state is failed.

createTime

integer

Task creation timestamp in Unix milliseconds.

completeTime

integer

Task completion timestamp in Unix milliseconds. Present after completion.

costTime

integer

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.

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",
      "aspect_ratio": "16:9"
    }
  }'

See Webhooks for delivery requirements and retry behavior.

Billing

Veo 3.1 is billed per generated video. The selected mode determines the unit price.

Mode	APIXO price
`fast`	`$0.20 / video`
`quality`	`$1.50 / video`

For current route and market comparison pricing, see 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
`fast`	1-3 minutes	60-90s after task creation	5-10s
`quality`	1-3 minutes	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.

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 `quality` or `fast`
Missing `generationType`	Set one of the supported generation type values
`REFERENCE_2_VIDEO` with `quality`	Use `mode: "fast"`
`REFERENCE_2_VIDEO` with `9:16` or `auto`	Use `aspect_ratio: "16:9"`
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 for the full error reference.

Getting Started

Image Models

Video Models

Audio Models

Overview

Endpoint and authentication

Copy-paste async quickstart

Poll for result

Request body

Text-to-video

First/last frame to video

Reference-to-video

Parameters

Response format

Submit task response

Status response fields

Webhook callback mode

Billing

Latency and polling

Errors and troubleshooting

HTTP errors

Task failure codes

Common validation issues

Getting Started

Image Models

Video Models

Audio Models

Documentation Index

​Overview

​Endpoint and authentication

​Copy-paste async quickstart

​Poll for result

​Request body

​Text-to-video

​First/last frame to video

​Reference-to-video

​Parameters

​Response format

​Submit task response

​Status response fields

​Webhook callback mode

​Billing

​Latency and polling

​Errors and troubleshooting

​HTTP errors

​Task failure codes

​Common validation issues

​Related links

Overview

Endpoint and authentication

Copy-paste async quickstart

Poll for result

Request body

Text-to-video

First/last frame to video

Reference-to-video

Parameters

Response format

Submit task response

Status response fields

Webhook callback mode

Billing

Latency and polling

Errors and troubleshooting

HTTP errors

Task failure codes

Common validation issues

Related links