Receive async results (polling and webhooks)
Image, video and audio tasks that finish later reach a final status, and their credits are charged or returned.
Many image, video and audio providers answer with a task ID and deliver the result later. You choose per provider, or per provider scene, whether the app polls for the status or the provider calls back. Text is always a direct response, so skip this guide for chat models.
Before you begin
- A provider and provider scene for an image, video or audio model, with response parsing set. See Connect an AI provider.
- Either a status URL you can query, or a public deployment the provider can call back. A local
127.0.0.1address cannot receive callbacks. - An admin account with
ai.readandai.write.
Choose how results arrive
Select polling
On Settings → AI Config, open the provider (or a provider scene) and choose Status polling under result handling.
Set the status URL
Fill in Status URL template, Interval sec and Timeout sec. {{externalTaskId}} in the template is the provider's task ID. Click Save.
Two things query the status URL
A client that reads the task through GET /api/status?taskId=... triggers a query once the interval has passed. Tasks nobody is reading are advanced by the ai-channel-tasks scheduled job, once a minute, so they still finish and settle credits. That job only runs where background jobs run.
Read the task status
Start a task and follow the statusUrl it returns. Reading status needs a session or an API key with Read AI task status, and only returns tasks the caller owns.
curl -X POST https://your-domain.example/api/video-creation/generate \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt":"A drone shot over a coastline","mediaType":"video"}'
# => { "taskId": "ai_task_...", "status": "running", "statusUrl": "/api/status?taskId=...",
# "estimatedPriceCredits": 12, "resultMode": "polling" }
curl "https://your-domain.example/api/status?taskId=ai_task_..." \
-H "Authorization: Bearer $API_KEY"When the task succeeds, URLs in its output are copied into the user's /generated storage folder. Without file storage the task still succeeds, and its events note that the storage import was skipped.
Verify
- The task moves from
runningtosucceededorfailedon the user's/app/ai/<taskId>page, which also shows the credits charged or returned. - Platform → AI Tasks (
/admin/ai/tasks) shows the final status. Failures are listed at/admin/ai/failed. pnpm validate:ai-channelchecks webhook signatures, polling and refunds.
Troubleshooting
An asynchronous task stays running
Check that polling has a Status URL template, and that either a client reads GET /api/status?taskId=... or background jobs are running so the ai-channel-tasks job can advance the task. For webhook mode, check that the provider calls the webhook URL with the task ID.
The webhook returns 401
Webhook secret is not configured. means neither the provider nor the provider scene has a Webhook signing secret. Save one. Webhook signature verification failed. means x-ai-signature is missing or is not the HMAC of the exact raw body. The task does not change.
The webhook returns 400
The callback does not name a task (taskId is required.), the callback URL names another provider (Webhook channel does not match task.), or the body is not JSON. The task does not change.
The task status or output looks wrong
The parser reads the wrong fields of the provider's response. Paste a real response on the provider form, click Test parser, and fix Output path or Status mapping.
Reference
Next steps
Route scenes and set pricing
Your product exposes named AI scenes such as chat or image-creation, each routed to a model and priced in credits.
Get image and video generation working
Wire an image or video provider so a generation completes end to end: request variables, array parser paths, status polling, storage of the result, and the picture or clip shown in the agent conversation.