Task Callbacks

Set callback_url at the top level of POST /v1/tasks. LLMAPI sends an HTTP POST after the task reaches succeeded, failed, timeout, or canceled.

{
  "model": "seedance-2-0-fast",
  "modality": "video",
  "callback_url": "https://client.example.com/webhooks/llmapi",
  "params": {
    "prompt": "Sunrise by the sea with a slow camera push-in",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }
}

callback_url must be an absolute HTTP(S) URL no longer than 2048 bytes, without user info or a fragment. It must be publicly reachable from the LLMAPI server. Private, loopback, and other restricted targets are blocked by SSRF protection, and redirects are not followed.

Payload

{
  "id": "75d9fb6592f64a75a4bd8f868db31752.1785987723000000000",
  "type": "task.succeeded",
  "created_at": 1785987723,
  "data": {
    "task": {
      "id": "75d9fb6592f64a75a4bd8f868db31752",
      "status": "succeeded",
      "modality": "video",
      "model": "seedance-2-0-fast",
      "created_at": "2026-08-06T00:01:03Z",
      "finished_at": "2026-08-06T00:02:03Z",
      "estimated_cost": 0.75,
      "actual_cost": 0.75,
      "result": {
        "duration": 5,
        "data": [{ "index": 0, "kind": "video", "url": "https://..." }]
      },
      "assets": [{ "index": 0, "kind": "video", "url": "https://..." }]
    }
  }
}

data.task matches the public response from GET /v1/tasks/{id}. Asset URLs expire; download promptly or use the Task API key with Download Assets for later retrieval.

Signature Verification

Each request includes:

X-LLMAPI-Delivery: 75d9fb6592f64a75a4bd8f868db31752.1785987723000000000
X-LLMAPI-Timestamp: 1785987723
X-LLMAPI-Signature: v1=<hex-encoded-hmac>

The signing secret is the Task API key used to submit the task. Sign the exact raw bytes of:

X-LLMAPI-Delivery + "." + X-LLMAPI-Timestamp + "." + raw_request_body

Compute HMAC-SHA256 and compare it in constant time with the hexadecimal value after v1=. Also reject timestamps outside your accepted replay window.

Retries and Idempotency

• Any 2xx response acknowledges the delivery. Network errors, timeouts, and non-2xx responses receive a limited number of retries with exponential backoff.
• Delivery is at least once. Retries for the same terminal run keep the same X-LLMAPI-Delivery; deduplicate on this value and return 2xx only after committing your own state.
• Callback failure never changes task status, results, assets, or billing. The query API remains available after automatic retries stop.
• Callbacks report terminal states only. If callback_url is omitted, poll GET /v1/tasks/{id}.