Webhook Callbacks

Overview

Task-style endpoints default to polling GET /api/generate/status/{task_id} for completion. When the upstream model supports webhook callbacks, you can pass a publicly reachable HTTPS URL via input.metadata.callback_url at submit time, and the upstream will POST directly to your endpoint on terminal states — no polling required.

The platform does not rewrite callbacks

The platform only forwards callback_url to the upstream as-is. The callback request is issued by the upstream provider directly, with that provider's payload schema, signing scheme, and retry policy. Implement your receiver against the upstream's official documentation.

Supported upstreams

Upstream / model family	Field	Documentation
Kling	`metadata.callback_url`	Kling docs
ByteDance Doubao	`metadata.callback_url`	Volcengine Ark console
MiniMax Hailuo	`metadata.callback_url`	MiniMax open platform
Vidu	`metadata.callback_url`	Vidu open platform

Other upstreams (OpenAI Sora / Google Veo / Gemini Nano-Banana / OpenAI GPT Image, etc.) currently support polling only — use Get Task Status.

Enabling callbacks at submit

callback_url always lives under input.metadata — it is not permitted at the top of input:

POST /api/generate/submit
Authorization: Bearer sk-xxxxxx
Content-Type: application/json

{
  "model": "kling-v1",
  "input": {
    "prompt": "A cat playing piano in the garden",
    "metadata": {
      "callback_url": "https://your.domain/hooks/kling"
    }
  }
}

The submit response is identical to the no-callback case:

{
  "code": 200,
  "data": {
    "task_id": "task_01HF8Z3KQX2A6Y4N3R8M5W7V9P",
    "status": "not_started",
    "created_time": "2026-06-14T10:30:00"
  }
}

Receiver implementation notes

HTTPS endpoint — most upstreams reject plain HTTP.
Return 200 fast — acknowledge first, process asynchronously to avoid upstream timeout retries.
Idempotency — dedupe by task_id; callbacks may arrive multiple times due to network retries.
Signature verification — when the upstream signs the request (e.g. Kling JWT / timestamp), validate before trusting the payload.
Polling fallback — keep a status-polling path as a safety net in case a callback is lost.

Relationship with status polling

The payload you receive is the upstream's original body. If you want a uniform shape, call Get Task Status on receipt to obtain the platform-normalized files[] / status / progress.