Skip to main content
POST
/
v1
/
video_generation
Generate videos
curl --request POST \
  --url https://api.gately.ai/v1/video_generation \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "T2V-01-Director",
  "prompt": "A spaceship landing on a distant planet [camera panning right]"
}
'
{
  "task_id": "<string>",
  "base_resp": {
    "status_code": 123,
    "status_msg": "<string>"
  }
}

​
Video Generation API

Generate high-quality videos from text prompts or images with camera movement control.

​
Overview

The video generation API allows you to create dynamic videos from text descriptions or images. The process works asynchronously:
  1. Submit a generation task
  2. Poll the task status using the returned task ID
  3. Download the video using the file ID once the task is complete

​
Video Generation Task

The OpenAPI playground above allows you to generate videos. After submitting, you’ll receive a task_id that you can use to check the status.

​
Check Generation Status

To check the status of your video generation task, use the status endpoint: 

GET /v1/query/video_generation?task_id={task_id}
This endpoint returns the current status of your generation task. Once the status field shows “Success”, you’ll also receive a file_id that can be used to download the video.

​
Camera Movement Instructions

When using the Director models (T2V-01-Director, I2V-01-Director), you can include camera movement instructions in your prompt using square brackets:
  • Single movement: [Truck left]
  • Combined movements: [Truck left, Pan right]

​
Available Camera Movements:

  • Truck: [Truck left], [Truck right]
  • Pan: [Pan left], [Pan right]
  • Push: [Push in], [Pull out]
  • Pedestal: [Pedestal up], [Pedestal down]
  • Tilt: [Tilt up], [Tilt down]
  • Zoom: [Zoom in], [Zoom out]
  • Other: [Shake], [Tracking shot], [Static shot]

​
Download Generated Video

Once your video is ready, you can download it using the file retrieval endpoint: 

GET /v1/files/retrieve?file_id={file_id}
This endpoint provides a download URL for your generated video.

​
Complete Example (Python)

import requests
import time

API_KEY = "your-api-key"
BASE_URL = "https://api.gately.ai"

def create_video_task(prompt, model="T2V-01-Director"):
    url = f"{BASE_URL}/v1/video_generation"
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    }
    data = {
        "model": model,
        "prompt": prompt
    }
    response = requests.post(url, headers=headers, json=data)
    return response.json()["task_id"]

def check_task_status(task_id):
    url = f"{BASE_URL}/v1/query/video_generation"
    headers = {
        "Authorization": f"Bearer {API_KEY}"
    }
    params = {"task_id": task_id}
    response = requests.get(url, headers=headers, params=params)
    return response.json()

def get_video_url(file_id):
    url = f"{BASE_URL}/v1/files/retrieve"
    headers = {
        "Authorization": f"Bearer {API_KEY}"
    }
    params = {"file_id": file_id}
    response = requests.get(url, headers=headers, params=params)
    return response.json()["file"]["download_url"]

# Example usage
prompt = "[Truck left,Pan right]A woman is drinking coffee"
print("Creating video task...")
task_id = create_video_task(prompt)

while True:
    print("Checking status...")
    status = check_task_status(task_id)
    if status["status"] == "Success":
        print("Video ready!")
        video_url = get_video_url(status["file_id"])
        print(f"Download URL: {video_url}")
        break
    elif status["status"] == "Fail":
        print("Generation failed!")
        break
    print(f"Status: {status['status']}")
    time.sleep(10)

​
Error Handling

The API uses standard HTTP status codes. Common errors include:
  • 400: Bad Request - Check your request parameters
  • 401: Unauthorized - Invalid or missing API key
  • 429: Too Many Requests - Rate limit exceeded
  • 500: Internal Server Error - Contact support
For detailed error information, check the error field in the response body.

Authorizations

​
Authorization
string
header
required

Enter your API key prefixed with 'Bearer '

Body

application/json
​
model
enum<string>
required

Video generation model to use

Available options:
T2V-01-Director,
I2V-01-Director,
S2V-01,
I2V-01,
I2V-01-live,
T2V-01
​
prompt
string
required

Text description of the video to generate. Can include camera movement instructions in square brackets.

​
first_frame_image
string

Base64-encoded image data for image-to-video generation

Response

Task creation successful

​
task_id
string

Unique identifier for the generation task

​
base_resp
object