Async API

VEO 3.1 asynchronous API reference for batch processing scenarios

Async API: Best for batch processing scenarios. Submit tasks and retrieve results via polling. For real-time interaction, use the synchronous API.

​

Models & Pricing

VEO 3.1 offers 8 model variants with the following naming convention:

• Base name: veo-3.1
• -landscape: Landscape mode (1280x720), default is portrait (720x1280)
• -fast: Fast generation, quicker speed and lower price
• -fl: Frame-to-Video mode, supports first/last frame input

Model	Description	Resolution	Price
veo-3.1	Default portrait video	720 x 1280	$0.25
veo-3.1-fl	Portrait + frame-to-video	720 x 1280	$0.25
veo-3.1-fast	Portrait + fast	720 x 1280	$0.15
veo-3.1-fast-fl	Portrait + fast + frame-to-video	720 x 1280	$0.15
veo-3.1-landscape	Landscape video	1280 x 720	$0.25
veo-3.1-landscape-fl	Landscape + frame-to-video	1280 x 720	$0.25
veo-3.1-landscape-fast	Landscape + fast	1280 x 720	$0.15
veo-3.1-landscape-fast-fl	Landscape + fast + frame-to-video	1280 x 720	$0.15

Pay on success: Only charged for successfully generated videos. All models generate 8-second videos with auto-generated audio tracks.

​

API Endpoints

​

1. Create Video Task

/v1/videos

Create an async video generation task

Request Headers

Content-Type: application/json
Authorization: sk-APIKEY

Request Parameters

prompt · string · 必填

Text description for video generation

model · string · 必填

Model name, e.g., veo-3.1, veo-3.1-fast, etc.

Request Examples

cURL

curl --location --request POST 'https://api.apiyi.com/v1/videos' \
--header 'Authorization: sk-your-api-key' \
--header 'Content-Type: application/json' \
--data-raw '{
    "prompt": "A cute kitten playing",
    "model": "veo-3.1"
}'

import requests

url = "https://api.apiyi.com/v1/videos"
headers = {
    "Content-Type": "application/json",
    "Authorization": "sk-your-api-key"
}
data = {
    "prompt": "A cute kitten playing",
    "model": "veo-3.1"
}

response = requests.post(url, json=data, headers=headers)
print(response.json())

const response = await fetch('https://api.apiyi.com/v1/videos', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'sk-your-api-key'
  },
  body: JSON.stringify({
    prompt: 'A cute kitten playing',
    model: 'veo-3.1'
  })
});

const data = await response.json();
console.log(data);

Response Example

{
  "id": "video_abc123",
  "object": "video",
  "created": 1762181811,
  "status": "queued",
  "model": "veo-3.1"
}

​

2. Query Task Status

/v1/videos/{video_id}

Query the current status of a video generation task

Path Parameters

video_id · string · 必填

Video task ID (returned from the create endpoint)

Request Examples

cURL

curl --location --request GET 'https://api.apiyi.com/v1/videos/video_abc123' \
--header 'Authorization: sk-your-api-key'

import requests

video_id = "video_abc123"
url = f"https://api.apiyi.com/v1/videos/{video_id}"
headers = {
    "Authorization": "sk-your-api-key"
}

response = requests.get(url, headers=headers)
print(response.json())

const videoId = 'video_abc123';
const response = await fetch(`https://api.apiyi.com/v1/videos/${videoId}`, {
  headers: {
    'Authorization': 'sk-your-api-key'
  }
});

const data = await response.json();
console.log(data);

Status Reference

Status	Description	Next Action
queued	Task is queued	Continue polling
processing	Task is processing	Continue polling
completed	Generation complete	Call content endpoint
failed	Generation failed	Check error message

​

3. Get Video Content

/v1/videos/{video_id}/content

Get the actual content of a generated video

Request Examples

cURL

curl --location --request GET 'https://api.apiyi.com/v1/videos/video_abc123/content' \
--header 'Authorization: sk-your-api-key'

import requests

video_id = "video_abc123"
url = f"https://api.apiyi.com/v1/videos/{video_id}/content"
headers = {
    "Authorization": "sk-your-api-key"
}

response = requests.get(url, headers=headers)
print(response.json())

const videoId = 'video_abc123';
const response = await fetch(`https://api.apiyi.com/v1/videos/${videoId}/content`, {
  headers: {
    'Authorization': 'sk-your-api-key'
  }
});

const data = await response.json();
console.log(data);

Response Example

{
  "id": "video_abc123",
  "object": "video",
  "created": 1762181811,
  "status": "completed",
  "model": "veo-3.1",
  "prompt": "A cute kitten playing",
  "url": "https://veo-video.gptkey.asia/assets/flow/xxx.mp4",
  "duration": 8,
  "resolution": "720x1280"
}

Video URLs are typically valid for 24 hours. Download and save promptly.

​

Complete Workflow

1. Create Task

   Call POST /v1/videos to create a video generation task and get the video_id

2. Poll Status

   Use GET /v1/videos/{video_id} to poll task status (recommended: every 5-10 seconds) until status is completed

3. Get Video

   Call GET /v1/videos/{video_id}/content to get the video URL

4. Download Video

   Download and save the video file from the returned URL

​

Python Complete Example

import requests
import time

class VEOClient:
    """VEO 3.1 Async API Client"""

    def __init__(self, api_key: str, base_url: str = "https://api.apiyi.com"):
        self.base_url = base_url
        self.headers = {
            "Content-Type": "application/json",
            "Authorization": api_key
        }

    def create_video(self, prompt: str, model: str = "veo-3.1") -> str:
        """Create video task, returns video_id"""
        response = requests.post(
            f"{self.base_url}/v1/videos",
            headers=self.headers,
            json={"prompt": prompt, "model": model}
        )
        response.raise_for_status()
        return response.json()["id"]

    def get_status(self, video_id: str) -> dict:
        """Query task status"""
        response = requests.get(
            f"{self.base_url}/v1/videos/{video_id}",
            headers=self.headers
        )
        response.raise_for_status()
        return response.json()

    def get_content(self, video_id: str) -> dict:
        """Get video content"""
        response = requests.get(
            f"{self.base_url}/v1/videos/{video_id}/content",
            headers=self.headers
        )
        response.raise_for_status()
        return response.json()

    def wait_for_completion(self, video_id: str, timeout: int = 600, interval: int = 5) -> dict:
        """Wait for task completion"""
        start_time = time.time()
        while time.time() - start_time < timeout:
            status_data = self.get_status(video_id)
            status = status_data.get("status")

            if status == "completed":
                return self.get_content(video_id)
            elif status == "failed":
                raise Exception(f"Video generation failed: {status_data}")

            print(f"Task in progress... Status: {status}")
            time.sleep(interval)

        raise TimeoutError("Timeout waiting for completion")


# Usage example
if __name__ == "__main__":
    client = VEOClient("sk-your-api-key")

    try:
        # 1. Create task
        video_id = client.create_video(
            prompt="A kitten walking in a sunny garden",
            model="veo-3.1-fast"
        )
        print(f"Task created, ID: {video_id}")

        # 2. Wait for completion and get result
        result = client.wait_for_completion(video_id)
        print(f"Video generated successfully!")
        print(f"Video URL: {result['url']}")
        print(f"Resolution: {result['resolution']}")

    except Exception as e:
        print(f"Error: {e}")

​

Frame-to-Video Mode

Models with the -fl suffix support frame-to-video functionality, converting static images into dynamic videos.

Mode	Images	Description
First Frame	1	Use image as video start, AI generates the continuation
First & Last Frame	2	Use first image as start, second as end, AI generates transition

​

Request Parameters

Frame-to-video requests require multipart/form-data format (not JSON) because image files need to be uploaded.

prompt · string · 必填

Video description. Describe how the scene should move (e.g., “camera slowly zooms in”, “person walks forward”)

model · string · 必填

Must use a model with -fl suffix, e.g., veo-3.1-fl, veo-3.1-landscape-fl

input_reference · file · 必填

Image file. Pass once for first-frame mode, twice for first-and-last-frame mode

​

First Frame Mode (Single Image)

Use one image as the video start, AI automatically generates the continuation.

cURL

curl --location --request POST 'https://api.apiyi.com/v1/videos' \
--header 'Authorization: sk-your-api-key' \
--form 'prompt="Bring this scene to life, camera slowly zooms in"' \
--form 'model="veo-3.1-landscape-fl"' \
--form 'input_reference=@"/path/to/image.jpg"'

import requests

url = "https://api.apiyi.com/v1/videos"
headers = {"Authorization": "sk-your-api-key"}
data = {
    "prompt": "Bring this scene to life, camera slowly zooms in",
    "model": "veo-3.1-landscape-fl"
}

# Single image mode - first frame
files = [
    ("input_reference", ("image.jpg", open("/path/to/image.jpg", "rb"), "image/jpeg"))
]

response = requests.post(url, headers=headers, data=data, files=files)
print(response.json())

const FormData = require('form-data');
const fs = require('fs');

const form = new FormData();
form.append('prompt', 'Bring this scene to life, camera slowly zooms in');
form.append('model', 'veo-3.1-landscape-fl');
form.append('input_reference', fs.createReadStream('/path/to/image.jpg'));

const response = await fetch('https://api.apiyi.com/v1/videos', {
  method: 'POST',
  headers: {
    'Authorization': 'sk-your-api-key',
    ...form.getHeaders()
  },
  body: form
});

const data = await response.json();
console.log(data);

​

First & Last Frame Mode (Two Images)

Specify the start and end frames, AI generates the transition animation between them.

cURL

curl --location --request POST 'https://api.apiyi.com/v1/videos' \
--header 'Authorization: sk-your-api-key' \
--form 'prompt="Transition from day to night, camera stays still"' \
--form 'model="veo-3.1-landscape-fl"' \
--form 'input_reference=@"/path/to/first-frame.jpg"' \
--form 'input_reference=@"/path/to/last-frame.jpg"'

import requests

url = "https://api.apiyi.com/v1/videos"
headers = {"Authorization": "sk-your-api-key"}
data = {
    "prompt": "Transition from day to night, camera stays still",
    "model": "veo-3.1-landscape-fl"
}

# Two image mode - first and last frame
files = [
    ("input_reference", ("first.jpg", open("/path/to/first-frame.jpg", "rb"), "image/jpeg")),
    ("input_reference", ("last.jpg", open("/path/to/last-frame.jpg", "rb"), "image/jpeg"))
]

response = requests.post(url, headers=headers, data=data, files=files)
print(response.json())

const FormData = require('form-data');
const fs = require('fs');

const form = new FormData();
form.append('prompt', 'Transition from day to night, camera stays still');
form.append('model', 'veo-3.1-landscape-fl');
form.append('input_reference', fs.createReadStream('/path/to/first-frame.jpg'));
form.append('input_reference', fs.createReadStream('/path/to/last-frame.jpg'));

const response = await fetch('https://api.apiyi.com/v1/videos', {
  method: 'POST',
  headers: {
    'Authorization': 'sk-your-api-key',
    ...form.getHeaders()
  },
  body: form
});

const data = await response.json();
console.log(data);

​

Response & Next Steps

The response format is the same as text-to-video. After receiving video_id, poll for results:

{
  "id": "video_xyz789",
  "object": "video",
  "created": 1762181811,
  "status": "queued",
  "model": "veo-3.1-landscape-fl"
}

For subsequent steps, refer to the Complete Workflow section above.

​

Usage Recommendations

First Frame Mode Use Cases

• Bring static images to life
• Product showcase animations
• Generate dynamic video from portraits

First & Last Frame Use Cases

• Scene transitions (day→night, seasonal changes)
• Expression change animations
• Object morphing transitions

Prompt Tips: When using frame-to-video, describe “how the scene moves” rather than “what’s in the scene”. Examples: “camera slowly zooms in”, “person turns head and smiles”, “flower gradually blooms”.

​

Error Handling

Error Code	Description	Solution
invalid_api_key	Invalid API key	Check if API key is correct
invalid_model	Model not found	Use a supported model name
invalid_prompt	Invalid prompt	Check prompt length and content
video_not_found	Video task not found	Verify video_id is correct
video_not_ready	Video not yet generated	Continue polling status
quota_exceeded	Quota exceeded	Contact support to increase quota

Error Response Format

{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid API key provided",
    "type": "authentication_error"
  }
}

​

FAQ

How do I choose the right model?

• Best value: Choose -fast series ($0.15/video)
• Quality first: Choose standard series ($0.25/video)
• Image-to-video: Choose -fl series
• Landscape content: Choose -landscape series

How long does video generation take?

• Fast models (-fast): ~30-60 seconds
• Standard models: ~1-2 minutes

Recommended polling interval: 5-10 seconds.

How long is the video URL valid?

Video URLs are typically valid for 24 hours. Download and save promptly after generation.

Are there volume discounts?

For bulk usage, contact support for enterprise pricing: [e-mail]

​

Technical Specifications

Item	Specification
Video Duration	8 seconds
Portrait Resolution	720 x 1280 (9:16)
Landscape Resolution	1280 x 720 (16:9)
Audio Track	Auto-included
URL Validity	24 hours
Recommended Poll Interval	5-10 seconds
Maximum Wait Time	10 minutes