Kernlift

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.1 address cannot receive callbacks.
  • An admin account with ai.read and ai.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 running to succeeded or failed on 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-channel checks 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