Control a video job

These routes require the updated API service and worker. Check Testing and availability before using them in production.

Use a video ID from video creation or the video list. The key must have access to that video’s workspace.

Action	Training route	Marketing route
Cancel	`POST /v1/videos/{uuid}/cancel`	`POST /v1/marketing/videos/{uuid}/cancel`
Retry failed scenes	`POST /v1/videos/{uuid}/retry`	`POST /v1/marketing/videos/{uuid}/retry`
Answer or skip a creation question	`POST /v1/videos/{uuid}/clarification`	`POST /v1/marketing/videos/{uuid}/clarification`

Cancel a video

Cancel queued or active work. The server chooses planning Stop or rendering Stop from the video’s saved stage. A completed video keeps its output and returns 409.

curl --fail-with-body -X POST "$API_BASE/v1/videos/$VIDEO_UUID/cancel" \
  -H "X-API-Key: $KNOWLIFY_API_KEY"

The server records cancellation immediately. A running worker checks for Stop and releases its slot when it exits. A provider request that already started may still finish remotely.

Retry failed scenes

Retry all failed scenes while status is awaiting_scene_retry. Supply scene_idx to retry one scene. Scene indexes start at zero.

curl --fail-with-body -X POST "$API_BASE/v1/videos/$VIDEO_UUID/retry" \
  -H "X-API-Key: $KNOWLIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

The response includes status, uuid, retried_scenes, enqueued, and status_url. Retry can return 409 when the video is not waiting for failed scenes.

Answer a creation question

If video status reports required_action.kind: "clarification", read its round and question IDs. Submit an option or a custom answer when allowsCustom is true.

curl --fail-with-body -X POST "$API_BASE/v1/videos/$VIDEO_UUID/clarification" \
  -H "X-API-Key: $KNOWLIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"round":1,"answers":[{"questionId":"audience","answer":"Staff","wasCustom":false}]}'

To copy the app’s Generate anyway action, send {"round":1,"skipped":true}. Skip sends no answers. The new run uses the original request and may make assumptions about missing details. The API checks the question round before restarting. A stale answer returns 409. The new run checks video capacity again; a full account returns 429.

Overview

Guides

Endpoints

Control a video job

Cancel a video

Retry failed scenes

Answer a creation question

​Cancel a video

​Retry failed scenes

​Answer a creation question

Cancel a video

Retry failed scenes

Answer a creation question