For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
DashboardAPI PricingGet an API key
  • Guides
    • Introduction
    • Getting started
    • Use with AI agents
    • Examples
    • Authentication
    • Handling async tasks
      • Polling
      • Webhooks
    • File uploads
    • File hydration
    • Embedding videos
    • Errors
    • Rate limits
    • Libraries & SDKs
  • REST API Reference
    • Overview
    • Workflows
        • POSTGenerate image
        • POSTGenerate video clip
        • POSTText to speech
        • POSTGenerate sound effect
        • POSTGenerate avatar clip
        • POSTVectorize image
        • POSTRemove background from an image
        • POSTRemove background from a video
        • POSTUpscale an image
        • POSTUpscale a video
        • POSTCancel tool execution
        • GETGet tool execution info
        • GETList files
        • POSTSearch files
        • GETGet file
        • POSTCreate file upload
        • POSTHydrate file
        • POSTArchive file
        • POSTEnable public preview
        • POSTDisable public preview
        • GETList avatar presenters
        • GETList TTS voices
        • GETList webhooks
        • POSTCreate webhook
        • DELDelete webhook
  • Webhook events
    • Overview
    • Changelog
LogoLogo
DashboardAPI PricingGet an API key
On this page
  • How it works
  • Getting the result
  • Cancellation
Guides

Handling async tasks

Tool requests return immediately. You choose how to get the result.
Was this page helpful?
Previous

Polling

Poll for the result of an async tool execution.
Next
Built with

Media generation (images, video, audio) takes anywhere from a few seconds to a couple of minutes. Rather than holding a connection open for that entire time, the VideoGen API returns a response instantly with an execution id. You then choose how to receive the result: poll for it, or let us push it to you via a webhook.

How it works

POST /v1/tools/generate-image  →  { "toolExecutionId": "vg_exec_..." }

Every POST /v1/tools/... endpoint returns 202 Accepted with a toolExecutionId. The execution progresses through these statuses:

StatusMeaning
pendingQueued, waiting to start
runningGeneration in progress
succeededDone, result is ready
failedSomething went wrong
cancelledCancelled by you

succeeded, failed, and cancelled are terminal statuses. The execution won’t change after reaching one of these.

Getting the result

There are two ways to know when an execution finishes:

MethodBest for
PollingScripts, CLI tools, or any situation where you can block and wait.
WebhooksProduction backends, serverless functions, and anywhere you don’t want to hold a connection open.

Cancellation

You can cancel an in-progress execution at any time:

$POST /v1/tools/executions/{toolExecutionId}/cancel

If the execution hasn’t completed yet, its status will transition to cancelled.