Video generation

The Video API runs video models that turn a text prompt into a short MP4 clip with sound. Generation takes minutes, so it runs as a job: you create the job, poll its status until it finishes, then download the video.

Generate your first video

You need:

• An Inworld API key. Copy its Base64 credentials from Portal or the CLI; see authentication.
• A payment method on your account.
• curl and a shell. Run these commands on your server, not in a browser.

export INWORLD_API_KEY="<your Base64 API key>"
export VIDEO_REQUEST_KEY="$(uuidgen)"

curl -X POST https://api.inworld.ai/v1/videos \
  -H "Authorization: Basic $INWORLD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $VIDEO_REQUEST_KEY" \
  -d '{
    "model": "alibaba/wan-3.0",
    "prompt": "A red fox trots across a snowy meadow at sunrise, slow tracking shot, soft golden light",
    "seconds": 5,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }'

{
  "id": "video_8f14e45fceea167a5a36dedd4bea2543",
  "object": "video",
  "model": "alibaba/wan-3.0",
  "status": "queued",
  "created_at": 1790000000,
  "seconds": 5,
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "operation": "workspaces/my-workspace/videoGenerationJobs/video_8f14e45fceea167a5a36dedd4bea2543/operations/1790000000000-a1b2c3"
}

export VIDEO_ID="video_8f14e45fceea167a5a36dedd4bea2543"

curl "https://api.inworld.ai/v1/videos/$VIDEO_ID" \
  -H "Authorization: Basic $INWORLD_API_KEY"

{
  "id": "video_8f14e45fceea167a5a36dedd4bea2543",
  "object": "video",
  "model": "alibaba/wan-3.0",
  "status": "completed",
  "created_at": 1790000000,
  "completed_at": 1790000142,
  "expires_at": 1790604942,
  "seconds": 5,
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "output": {
    "videos": [
      {
        "index": 0,
        "content_type": "video/mp4",
        "bytes": 4823311,
        "url": "https://storage.googleapis.com/...",
        "url_expires_at": 1790003742
      }
    ]
  }
}

export VIDEO_URL="<output.videos[0].url from your response>"
curl -o fox.mp4 "$VIDEO_URL"

Generate a video with a script

These scripts run the same create, poll and download flow. They read INWORLD_API_KEY and VIDEO_REQUEST_KEY from the environment, so set both as in step 1.

Because the key comes from the environment, rerunning a script after a timeout or crash returns the same job instead of creating another, and the script picks up where it left off. To generate a new video, set a new VIDEO_REQUEST_KEY first. A script that generates its own key each run starts a new paid job every time it is restarted.

python -m pip install requests

import os
import time

import requests

API = "https://api.inworld.ai/v1/videos"
HEADERS = {"Authorization": f"Basic {os.environ['INWORLD_API_KEY']}"}
# Reuse one key for every attempt at this video, including after a restart.
REQUEST_KEY = os.environ["VIDEO_REQUEST_KEY"]


def create_video():
    for attempt in range(3):
        try:
            response = requests.post(
                API,
                headers={**HEADERS, "Idempotency-Key": REQUEST_KEY},
                json={
                    "model": "alibaba/wan-3.0",
                    "prompt": "A red fox trots across a snowy meadow at sunrise, slow tracking shot, soft golden light",
                    "seconds": 5,
                    "resolution": "720p",
                    "aspect_ratio": "16:9",
                },
                timeout=30,
            )
            response.raise_for_status()
            return response.json()
        except (requests.ConnectionError, requests.Timeout):
            # Safe to resend: the same key returns the same job.
            if attempt == 2:
                raise
            time.sleep(2**attempt)


video_id = create_video()["id"]
print("Job", video_id)

# Retrieve before reading the result: only a retrieve returns the download link.
while True:
    response = requests.get(f"{API}/{video_id}", headers=HEADERS, timeout=30)
    response.raise_for_status()
    video = response.json()
    print(video["status"])
    if video["status"] not in ("queued", "in_progress"):
        break
    time.sleep(15)

if video["status"] != "completed":
    raise SystemExit(f"Job ended {video['status']}: {video.get('error')}")

# The signed link needs no Authorization header.
url = video["output"]["videos"][0]["url"]
with requests.get(url, stream=True, timeout=300) as download:
    download.raise_for_status()
    with open("fox.mp4", "wb") as f:
        for chunk in download.iter_content(chunk_size=1 << 20):
            f.write(chunk)
print("Saved fox.mp4")

python generate_video.py

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

const API = 'https://api.inworld.ai/v1/videos';
const headers = { Authorization: `Basic ${process.env.INWORLD_API_KEY}` };
// Reuse one key for every attempt at this video, including after a restart.
const requestKey = process.env.VIDEO_REQUEST_KEY;
if (!requestKey) throw new Error('Set VIDEO_REQUEST_KEY first');

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function call(url, init = {}) {
  const response = await fetch(url, {
    ...init,
    headers: { ...headers, ...init.headers },
    signal: AbortSignal.timeout(30_000),
  });
  if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
  return response.json();
}

async function createVideo() {
  for (let attempt = 0; ; attempt++) {
    try {
      return await call(API, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json', 'Idempotency-Key': requestKey },
        body: JSON.stringify({
          model: 'alibaba/wan-3.0',
          prompt: 'A red fox trots across a snowy meadow at sunrise, slow tracking shot, soft golden light',
          seconds: 5,
          resolution: '720p',
          aspect_ratio: '16:9',
        }),
      });
    } catch (error) {
      // Network errors and timeouts are safe to resend: the same key returns the same job.
      const retryable = error.name === 'TypeError' || error.name === 'TimeoutError';
      if (!retryable || attempt === 2) throw error;
      await sleep(1000 * 2 ** attempt);
    }
  }
}

const { id } = await createVideo();
console.log('Job', id);

// Retrieve before reading the result: only a retrieve returns the download link.
let video;
while (true) {
  video = await call(`${API}/${id}`);
  console.log(video.status);
  if (video.status !== 'queued' && video.status !== 'in_progress') break;
  await sleep(15_000);
}

if (video.status !== 'completed') {
  throw new Error(`Job ended ${video.status}: ${JSON.stringify(video.error)}`);
}

// The signed link needs no Authorization header.
const download = await fetch(video.output.videos[0].url);
if (!download.ok) throw new Error(`Download failed: ${download.status}`);
await writeFile('fox.mp4', Buffer.from(await download.arrayBuffer()));
console.log('Saved fox.mp4');

node generate-video.mjs

Expected output, with your job's id:

Job video_8f14e45fceea167a5a36dedd4bea2543
queued
in_progress
in_progress
completed
Saved fox.mp4

Models and parameters

Every parameter except model and prompt is optional. A parameter you leave out takes the model's default, and the job you get back shows the value used. Values outside a model's range are rejected with 400 before a job is created.

seconds is a whole number. resolution is case-insensitive. The request body accepts only these five fields; any other field is rejected, so a parameter is never silently ignored.

The API generates video from text only. Image-to-video, reference images, and extending or remixing an existing video are not supported.

Job lifecycle

A job that takes longer than 30 minutes to generate fails with generation_timeout.

Poll for the result

Retrieve the job every 10 to 20 seconds until its status is terminal. Polling more often does not make a job finish sooner. The job object has no progress percentage, so show a spinner or elapsed time rather than a progress bar.

When you track many jobs, list them instead of retrieving each one: a single list call returns up to 100 jobs with their statuses, newest first. List entries do not carry download links, so retrieve each completed job once to get its link.

Poll the operation instead

Each job is also a long-running operation, named in the job's operation field. If your app already polls Inworld operations, you can poll a video job the same way. Save the operation from your create response, replacing the example value with yours:

export OPERATION="workspaces/my-workspace/videoGenerationJobs/video_8f14e45fceea167a5a36dedd4bea2543/operations/1790000000000-a1b2c3"
curl "https://api.inworld.ai/lro/v1alpha/$OPERATION" \
  -H "Authorization: Basic $INWORLD_API_KEY"

While the job is unfinished, the operation has done: false and metadata.state is QUEUED or IN_PROGRESS. When the job finishes, done becomes true and the operation carries one of:

• response, for a completed job: the video's id, model, duration, resolution, aspectRatio, sizeBytes, mimeType and expireTime.
• error, for a failed or cancelled job. For a failed job, the error's reason is the job's error.code.

{
  "name": "workspaces/my-workspace/videoGenerationJobs/video_8f14e45fceea167a5a36dedd4bea2543/operations/1790000000000-a1b2c3",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/ai.inworld.video.v1.VideoGenerationResponse",
    "id": "video_8f14e45fceea167a5a36dedd4bea2543",
    "model": "alibaba/wan-3.0",
    "duration": "5s",
    "resolution": "720p",
    "aspectRatio": "16:9",
    "sizeBytes": "4823311",
    "mimeType": "video/mp4",
    "expireTime": "2026-09-28T14:15:42Z"
  }
}

The operation never carries the download link. When it is done, retrieve the job by its id to get the link. The operation can lag the job by a few seconds, so treat the job as the source of truth.

Download and storage

• Download links remain valid for up to one hour, capped by the video's retention deadline. url_expires_at says when. Each retrieve returns a new link, so retrieve the job again rather than storing the link.
• Videos are kept for 7 days. After the job's expires_at, the job still shows completed but has no output. Copy videos you want to keep to your own storage.
• Treat a download link like a password. Anyone who has it can download the video until it expires.
• Delete a video sooner with Delete video. Only finished jobs can be deleted.
• Save your prompt yourself. The job object does not include the prompt, and you can't get it back later.

Retries and idempotency

A create request starts a paid job. If the request times out or the connection drops, you can't tell whether the job was created, and sending it again could start a second one. To retry safely, send an Idempotency-Key header with a unique value, such as a UUID, and reuse the same value when you retry:

• A create with a key you already used returns the original job with 200, and starts nothing new.
• Keys are scoped to your workspace and can be up to 255 characters.
• The body is not compared with the original. A different request sent with a used key still returns the first job, so use a new key for every new video.
• A create that is refused with 400 or 429 starts nothing and doesn't use up the key. Fix the request or wait, then resend it with the same key.
• A retry that arrives while the first request with the same key is still being processed returns 409 with code: "idempotency_key_in_use". Wait a few seconds, then resend it with the same key.
• A key whose job you deleted can't be reused: the create returns 409 with code: "idempotency_key_reused".

Keep the key somewhere that survives a restart, such as an environment variable, a file, or the database row for the video in your app. A key generated fresh on every run protects nothing: a rerun after a timeout gets a new key and starts a second paid job.

Cancel a job

Cancel video stops a job that has not started generating, and a cancelled job is not billed. Jobs are sent for generation as soon as they are created, so a cancel usually succeeds only right after the create. After that, cancelling returns 409 with code: "video_not_cancellable", even if the job still shows queued, and the job runs to the end.

Limits

Retrieving, listing, cancelling and deleting jobs is not limited by the job limit.

Billing

You pay per second of video, at the rate for the model and resolution you chose:

For example, a 5-second Wan 3.0 video at 720p costs $0.50.

• Only completed jobs are billed. failed and cancelled jobs cost nothing.
• Billed seconds are the length of the delivered video rounded up to a whole second, and never more than the seconds you requested.
• Deleting a video does not refund it.

Errors

Video API errors use the JSON structure below, with a machine-readable code and a param naming the field when one is at fault. Authentication, permission, and some rate-limit errors may return plain text instead. Check the HTTP status and response content type before parsing the body.

{
  "error": {
    "message": "seconds must be an integer from 2 to 30",
    "type": "invalid_request_error",
    "code": "invalid_request",
    "param": "seconds"
  }
}

Job failures

A job that fails after it was created returns status: "failed" and an error object on the job itself, not an HTTP error:

Failed jobs are not billed.

Coming from other video APIs

When migrating an existing integration, update the endpoint, request fields, status handling, and download logic to match this API. Call it over HTTP rather than through another provider's SDK. Differences that commonly need changes:

• Set resolution and aspect_ratio, not size in pixels.
• seconds is a number, not a string.
• The body is JSON, not a multipart form.
• Download from output.videos[0].url; there is no /content endpoint.
• Jobs report no progress percentage.
• POST /v1/videos/{video_id}/cancel cancels a job before it starts.