Generate videos

Use POST /v2/videos/generations to start a video generation. Video generation is asynchronous, so you submit once, poll for status, and download the finished asset when it’s ready.

POST https://api.getimg.ai/v2/videos/generations
GET  https://api.getimg.ai/v2/videos/generations/{id}

The generation flow

Submit a generation request

POST to /v2/videos/generations with your model, prompt, and parameters. The API returns HTTP 202 with a generation ID and status: "pending".

Poll for completion

GET /v2/videos/generations/{id} periodically. The status will be pending, failed, or completed.

Download the video

When status is completed, download the video from the signed download URL in data[0].url.

Step 1: Submit

import GetimgAI from "getimg-ai";

const client = new GetimgAI();

const result = await client.videos.generations.create({
  model: "seedance-v1-5-pro",
  prompt: "A drone shot over a futuristic city skyline at sunset",
  aspect_ratio: "16:9",
  resolution: "1080p",
  duration: 5,
  sound: true,
});

const generationId = result.id; // e.g., "req-01HXYZVIDEO1234"

from getimg import GetimgAI

client = GetimgAI()

result = client.videos.generations.create(
    model="seedance-v1-5-pro",
    prompt="A drone shot over a futuristic city skyline at sunset",
    aspect_ratio="16:9",
    resolution="1080p",
    duration=5,
    sound=True,
)

generation_id = result.id  # e.g., "req-01HXYZVIDEO1234"

curl -X POST https://api.getimg.ai/v2/videos/generations \
  -H "Authorization: Bearer $GETIMG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-v1-5-pro",
    "prompt": "A drone shot over a futuristic city skyline at sunset",
    "aspect_ratio": "16:9",
    "resolution": "1080p",
    "duration": 5,
    "sound": true
  }'

{
  "id": "req-01HXYZVIDEO1234",
  "status": "pending"
}

Step 2: Poll for status

Poll the status endpoint with your generation ID.

Status	Meaning	Next action
`pending`	Still processing	Wait and poll again
`failed`	Generation failed	Read `error.message`, then submit a new generation if needed
`completed`	Video is ready	Download from `data[0].url`

import GetimgAI from "getimg-ai";

const client = new GetimgAI();

const result = await client.videos.generations.retrieve("req-01HXYZVIDEO1234");
console.log(result.status);

from getimg import GetimgAI

client = GetimgAI()

result = client.videos.generations.retrieve("req-01HXYZVIDEO1234")
print(result.status)

curl https://api.getimg.ai/v2/videos/generations/req-01HXYZVIDEO1234 \
  -H "Authorization: Bearer $GETIMG_API_KEY"

Completed response:

{
  "id": "req-01HXYZVIDEO1234",
  "status": "completed",
  "model": "seedance-v1-5-pro",
  "data": [
    {
      "url": "https://api.getimg.ai/v2/downloads/req-01HXYZVIDEO1234/0?exp=1760000000&sig=ca4f0f...",
      "width": 1920,
      "height": 1080,
      "duration": 5,
      "fps": 24,
      "has_sound": true,
      "mime_type": "video/mp4",
      "deletes_at": "2026-09-09T12:30:00.000Z"
    }
  ],
  "usage": {
    "total_cost": 0.25,
    "billable_unit": "video_second",
    "unit_price": 0.05,
    "quantity": 5
  }
}

Polling strategy

Poll every 5 seconds as a starting point. Set a timeout so your integration stays responsive and does not poll forever.

import GetimgAI from "getimg-ai";

const client = new GetimgAI();

async function pollVideo(generationId, interval = 5000, timeout = 300000) {
  const start = Date.now();

  while (Date.now() - start < timeout) {
    const result = await client.videos.generations.retrieve(generationId);

    if (result.status === "completed") return result;
    if (result.status === "failed") {
      throw new Error(`Generation failed: ${result.error.message}`);
    }

    await new Promise((r) => setTimeout(r, interval));
  }

  throw new Error(`Video not ready after ${timeout / 1000}s`);
}

import time
from getimg import GetimgAI

client = GetimgAI()

def poll_video(generation_id, interval=5, timeout=300):
    elapsed = 0
    while elapsed < timeout:
        result = client.videos.generations.retrieve(generation_id)

        if result.status == "completed":
            return result
        if result.status == "failed":
            raise Exception(f"Generation failed: {result.error.message}")

        time.sleep(interval)
        elapsed += interval

    raise TimeoutError(f"Video not ready after {timeout}s")

while true; do
  response=$(curl -s https://api.getimg.ai/v2/videos/generations/req-01HXYZVIDEO1234 \
    -H "Authorization: Bearer $GETIMG_API_KEY")

  status=$(printf '%s' "$response" | jq -r '.status')
  echo "Status: $status"

  if [ "$status" = "completed" ] || [ "$status" = "failed" ]; then
    printf '%s\n' "$response"
    break
  fi

  sleep 5
done

Step 3: Download

The url in each data item is a signed download URL. Generated media is retained for 24 hours, and the URL expires at the deletes_at timestamp.

import { writeFile } from "node:fs/promises";

const download = await fetch("https://api.getimg.ai/v2/downloads/req-01HXYZVIDEO1234/0?exp=1760000000&sig=ca4f0f...");
const buffer = Buffer.from(await download.arrayBuffer());
await writeFile("video.mp4", buffer);

import httpx

with open("video.mp4", "wb") as f:
    f.write(httpx.get("https://api.getimg.ai/v2/downloads/req-01HXYZVIDEO1234/0?exp=1760000000&sig=ca4f0f...").content)

curl -o video.mp4 "https://api.getimg.ai/v2/downloads/req-01HXYZVIDEO1234/0?exp=1760000000&sig=ca4f0f..."

Parameters

Parameter	Type	Default	Description
`model`	string	required	Model identifier. See Models.
`prompt`	string	required	Text description of the video to generate.
`aspect_ratio`	string	model default	e.g., `16:9`, `1:1`, `9:16`.
`resolution`	string	model default	e.g., `720p`, `1080p`.
`duration`	integer	model default	Duration in seconds.
`sound`	boolean	`false`	Generate audio, where supported by the model.
`images`	array	—	Up to 20 first frame, last frame, or reference image inputs. HTTPS URL or base64 data URL.

Using frame and reference images

Pass up to 20 images in the images array. Each item needs a url and a role. Video models support these roles:

first_frame: the opening frame of the video
last_frame: the closing frame of the video. This always requires a first_frame.
reference_image: a style or content reference when you need the output to stay closer to an existing visual direction. You cannot combine it with first_frame or last_frame.

{
  "model": "seedance-v1-5-pro",
  "prompt": "Transition from sunrise to dusk over mountain landscape",
  "images": [
    {
      "url": "https://your-bucket.s3.amazonaws.com/sunrise.png",
      "role": "first_frame"
    },
    {
      "url": "https://your-bucket.s3.amazonaws.com/dusk.png",
      "role": "last_frame"
    }
  ],
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "duration": 10
}

Not all models support all roles. A model’s supported_references field lists the roles it accepts and the maximum count for each. See Models. Unsupported roles return 400 with code invalid_parameter.

Image sources

url accepts either form:

a publicly accessible HTTPS URL
a base64 data URL, such as data:image/png;base64,...

Use a data URL when the frame only exists on your side and you don’t want to host it first.

import { readFile } from "node:fs/promises";
import GetimgAI from "getimg-ai";

const client = new GetimgAI();

const bytes = await readFile("sunrise.png");
const dataUrl = `data:image/png;base64,${bytes.toString("base64")}`;

const { id } = await client.videos.generations.create({
  model: "seedance-v1-5-pro",
  prompt: "Transition from sunrise to dusk over mountain landscape",
  images: [{ url: dataUrl, role: "first_frame" }],
  duration: 5,
});

import base64
from getimg import GetimgAI

client = GetimgAI()

with open("sunrise.png", "rb") as f:
    encoded = base64.b64encode(f.read()).decode()

submission = client.videos.generations.create(
    model="seedance-v1-5-pro",
    prompt="Transition from sunrise to dusk over mountain landscape",
    images=[{"url": f"data:image/png;base64,{encoded}", "role": "first_frame"}],
    duration=5,
)

Inline images must be PNG, JPEG, or WebP. Bare base64 without the data: prefix is rejected.

A decoded image can be up to 10 MiB, and the whole JSON request must fit within 25 MiB. Base64 adds roughly 33% to the original file size, so budget for that before you inline both a first and last frame. Pass an HTTPS URL instead when you’re close to the limit.

Failure states

Video generations can fail after submission.

If polling returns status: "failed", treat that generation as terminal.
Read error.message for the reason.
Fix the input, wait if the problem is temporary, or submit a new generation.

Sound

Set sound: true to generate audio. Supported models are listed on the Models page.

{
  "model": "seedance-v1-5-pro",
  "prompt": "Ocean waves crashing on a rocky shore",
  "duration": 10,
  "sound": true
}

Full example

import { writeFile } from "node:fs/promises";
import GetimgAI from "getimg-ai";

const client = new GetimgAI();

const { id } = await client.videos.generations.create({
  model: "seedance-v1-pro",
  prompt: "A timelapse of clouds rolling over a mountain peak",
  aspect_ratio: "16:9",
  resolution: "1080p",
  duration: 10,
  sound: true,
});
console.log(`Submitted: ${id}`);

let result = await client.videos.generations.retrieve(id);
while (result.status === "pending") {
  await new Promise((r) => setTimeout(r, 5000));
  result = await client.videos.generations.retrieve(id);
  console.log(`Status: ${result.status}`);
}

if (result.status === "failed") {
  throw new Error(`Failed: ${result.error.message}`);
}

const video = result.data[0];
const download = await fetch(video.url);
const buffer = Buffer.from(await download.arrayBuffer());
await writeFile("output.mp4", buffer);

console.log(`Saved output.mp4 (${video.width}x${video.height}, ${video.duration}s, ${video.fps}fps)`);
console.log(`Sound: ${video.has_sound}`);
console.log(`Cost: ${result.usage?.total_cost} (${result.usage?.quantity} ${result.usage?.billable_unit})`);

import time
import httpx
from getimg import GetimgAI

client = GetimgAI()

submission = client.videos.generations.create(
    model="seedance-v1-pro",
    prompt="A timelapse of clouds rolling over a mountain peak",
    aspect_ratio="16:9",
    resolution="1080p",
    duration=10,
    sound=True,
)
print(f"Submitted: {submission.id}")

result = client.videos.generations.retrieve(submission.id)
while result.status == "pending":
    time.sleep(5)
    result = client.videos.generations.retrieve(submission.id)
    print(f"Status: {result.status}")

if result.status == "failed":
    raise RuntimeError(f"Failed: {result.error.message}")

video = result.data[0]
with open("output.mp4", "wb") as f:
    f.write(httpx.get(video.url).content)

print(f"Saved output.mp4 ({video.width}x{video.height}, {video.duration}s, {video.fps}fps)")
print(f"Sound: {video.has_sound}")
if result.usage:
    print(f"Cost: {result.usage.total_cost} ({result.usage.quantity} {result.usage.billable_unit})")

submission=$(curl -s -X POST https://api.getimg.ai/v2/videos/generations \
  -H "Authorization: Bearer $GETIMG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-v1-pro",
    "prompt": "A timelapse of clouds rolling over a mountain peak",
    "aspect_ratio": "16:9",
    "resolution": "1080p",
    "duration": 10,
    "sound": true
  }')

generation_id=$(printf '%s' "$submission" | jq -r '.id')
echo "Submitted: $generation_id"

while true; do
  result=$(curl -s "https://api.getimg.ai/v2/videos/generations/$generation_id" \
    -H "Authorization: Bearer $GETIMG_API_KEY")
  status=$(printf '%s' "$result" | jq -r '.status')
  echo "Status: $status"

  if [ "$status" = "failed" ]; then
    printf '%s\n' "$result" | jq -r '.error.message'
    exit 1
  fi

  if [ "$status" = "completed" ]; then
    download_url=$(printf '%s' "$result" | jq -r '.data[0].url')
    curl -L "$download_url" -o output.mp4
    break
  fi

  sleep 5
done

Getting started

Generation

Concepts

The generation flow

Step 1: Submit

Step 2: Poll for status

Polling strategy

Step 3: Download

Parameters

Using frame and reference images

Image sources

Failure states

Sound

Full example

​The generation flow

​Step 1: Submit

​Step 2: Poll for status

​Polling strategy

​Step 3: Download

​Parameters

​Using frame and reference images

​Image sources

​Failure states

​Sound

​Full example

​Related pages

The generation flow

Step 1: Submit

Step 2: Poll for status

Polling strategy

Step 3: Download

Parameters

Using frame and reference images

Image sources

Failure states

Sound

Full example

Related pages