AI Gateway now supports asynchronous video generation

Video generation on AI Gateway can now run asynchronously.

By default, generateVideo keeps one HTTP request to AI Gateway open until the result is ready. Because video generation can take seconds or minutes, that request can exceed request timeouts.

With asynchronous generation, your application can receive a webhook, poll for completion, or start a generation and retrieve the result in a later request.

Choose an option based on whether your process can keep running and whether your application can receive webhooks:

Existing generateVideo calls continue to work as before. All four options support text-to-video, image-to-video, reference-to-video, and other video inputs.

Copy link to headingUpgrade the SDK

Install the latest versions of the AI SDK and AI Gateway provider:

pnpm add ai@latest @ai-sdk/gateway@latest

Copy link to headingUse asynchronous video generation

Copy link to headingWait for completion in a Workflow

An easy way to consume the completion webhook is a Workflow SDK. The workflow creates its own webhook URL, passes it to startVideo, and suspends until AI Gateway delivers the completion event.

Install the Workflow SDK alongside the AI SDK:

pnpm add workflow

1
import {
2
  experimental_getVideoStatus as getVideoStatus,
3
  experimental_startVideo as startVideo,
4
  type StartVideoResult,
5
} from 'ai';
6
import { createWebhook } from 'workflow';
7

8
const model = 'klingai/kling-v3.0-t2v';
9

10
export async function videoWorkflow(prompt: string) {
11
  'use workflow';
12
  // A durable webhook with its own URL — no route handler or token store
13
  using webhook = createWebhook();
14
  const { operation } = await startJob(prompt, webhook.url);
15
  // Suspends the run. No compute runs while the video renders.
16
  await webhook;
17
  const { status, videos } = await fetchResult(operation);
18
  if (status !== 'completed') {
19
    throw new Error(`Video generation ${status}`);
20
  }
21
  return videos;
22
}
23

24
async function startJob(prompt: string, webhookUrl: string) {
25
  'use step';
26
  const { operation } = await startVideo({ model, prompt, webhookUrl });
27
  return { operation };
28
}
29

30
async function fetchResult(operation: StartVideoResult['operation']) {
31
  'use step';
32
  return await getVideoStatus(model, { operation });
33
}

While the video renders, the workflow run is suspended and resumes when AI Gateway delivers the terminal event.

Copy link to headingUse a webhook with generateVideo

Pass webhook to generateVideo to wait for a completion event without polling. AI Gateway sends an event when the job completes or fails. The SDK waits for that event, fetches the generated videos, and resolves the original generateVideo call.

1
import { experimental_generateVideo as generateVideo } from 'ai';
2
import { randomUUID } from 'node:crypto';
3

4
// One token per generation, minted before the call. The job ID cannot serve
5
// here: it does not exist until the start request comes back.
6
const token = randomUUID();
7

8
const result = await generateVideo({
9
  model: 'klingai/kling-v3.0-t2v',
10
  prompt: 'A lighthouse beam sweeping across a foggy coast at night',
11
  webhook: async () => ({
12
    url: `https://example.com/api/video-webhook?token=${token}`,
13
    received: waitForDelivery(token), // resolves with { headers, body }
14
  }),
15
});

The calling process and webhook handler need a shared token and store so the delivery can be matched to the correct generation. generateVideo does not expose the signing secret for this job. See the webhook verification documentation for the complete receiver pattern.

Both the polling and webhook options for generateVideo return result.videos as GeneratedFile objects. The SDK downloads provider-hosted videos, making uint8Array, base64, and mediaType available in either job.

Copy link to headingPoll with generateVideo

Add poll to an existing generateVideo call:

1
const result = await generateVideo({
2
  model: 'spacexai/grok-imagine-video-1.5',
3
  prompt: {
4
    image: 'https://example.com/balloon.jpg',
5
    text: 'The camera pushes in as the balloon drifts upward',
6
  },
7
  duration: 5,
8
  poll: {
9
    intervalMs: 5000, // defaults to 5000
10
    timeoutMs: 600000, // defaults to 600000
11
  },
12
});

AI Gateway starts an asynchronous job, and the SDK sends a short status request at each interval until the job finishes. The calling process must remain running until generateVideo resolves, but no individual request to AI Gateway stays open for the full generation.

Copy link to headingStart a job and retrieve it later

startVideo returns an operation as soon as AI Gateway accepts the job, without waiting for rendering to finish. Store that operation and pass it to getVideoStatus later from the same process or another one:

1
import {
2
  experimental_getVideoStatus as getVideoStatus,
3
  experimental_startVideo as startVideo,
4
} from 'ai';
5

6
const model = 'bytedance/seedance-2.5';
7

8
const { operation } = await startVideo({
9
  model,
10
  prompt: 'A paper plane looping over a city at dusk',
11
});
12

13
// Check the job later, from this process or another one
14
const status = await getVideoStatus(model, { operation });
15
if (status.status === 'completed') {
16
  console.log(status.videos);
17
}

The operation is JSON-serializable, so it can be stored in a database or passed through a queue. Your application controls how long to keep checking the job because it has no built-in timeout.

You can also pass webhookUrl to startVideo to receive a completion event instead of checking the status. The start response includes the signing secret needed to verify the webhook.

Unlike generateVideo, getVideoStatus does not download hosted videos. It returns provider URLs or inline bytes. Hosted URLs can expire, so download any videos you need to keep.

Copy link to headingMonitor asynchronous jobs

Every asynchronous generation appears on the AI Gateway Logs page as soon as it starts. Jobs show as Running while generation is in progress and update when they complete or fail.

Under Request Mode, select Async to show only asynchronous jobs. Opening an entry shows the job ID and the request details.

Only asynchronous requests create jobs. A standard generateVideo call appears as a single completed request after the video is ready.

For size limits, idempotency for retried job starts, webhook delivery retries, and other operational details, read the asynchronous video generation documentation or browse all video models.