Poll Video Generation Status

GET 
https://api.knox.chat/v1/videos/:jobId

Poll a video generation job created by POST /v1/videos. Use the id (or polling_url) from the submit response. Keep polling while status is pending or in_progress. When status is completed, download the file from GET /v1/videos/{jobId}/content or use unsigned_urls.

Jobs are scoped to the authenticated user. Polling another account's jobId returns 404.

Request

Path Parameters

Name	Type	Required	Description
jobId	String	Yes	Job ID returned by submit, for example job-3c91a0e8b7d24f11.

Request Headers

Name	Type	Required	Description
Authorization	String	Yes	Bearer authentication in the form Bearer <token>.

This endpoint has no request body.

cURL Example

curl -X GET https://api.knox.chat/v1/videos/job-3c91a0e8b7d24f11 \
     -H "Authorization: Bearer $KNOXCHAT_API_KEY"

Poll every few seconds until the job leaves pending / in_progress. Video generation often takes tens of seconds to a few minutes depending on model, duration, and resolution.

while true; do
  resp=$(curl -s -X GET "https://api.knox.chat/v1/videos/job-3c91a0e8b7d24f11" \
    -H "Authorization: Bearer $KNOXCHAT_API_KEY")
  status=$(printf '%s' "$resp" | python -c "import sys,json; print(json.load(sys.stdin).get('status',''))")
  echo "$status"
  case "$status" in
    completed|failed|cancelled|expired) echo "$resp"; break ;;
  esac
  sleep 5
done

Response

In progress (200)

{
  "generation_id": "gen-8f2c1a9b4d6e7f01",
  "id": "job-3c91a0e8b7d24f11",
  "polling_url": "/v1/videos/job-3c91a0e8b7d24f11",
  "status": "in_progress"
}

Completed (200)

{
  "generation_id": "gen-8f2c1a9b4d6e7f01",
  "id": "job-3c91a0e8b7d24f11",
  "polling_url": "/v1/videos/job-3c91a0e8b7d24f11",
  "status": "completed",
  "unsigned_urls": [
    "https://image.knox.chat/videos/job-3c91a0e8b7d24f11/0_e081f0c0ab29f22a.mp4"
  ],
  "usage": {
    "cost": 0.415
  }
}

unsigned_urls are Knox-hosted download links (presigned object storage or custom domain). Upstream provider URLs are never returned.

Failed (200)

{
  "generation_id": "gen-8f2c1a9b4d6e7f01",
  "id": "job-3c91a0e8b7d24f11",
  "polling_url": "/v1/videos/job-3c91a0e8b7d24f11",
  "status": "failed",
  "error": "The upstream provider rejected this generation request"
}

A failed poll still returns HTTP 200 with status: "failed". Use the error field for the reason.

Response Schema

Name	Type	Description
generation_id	string	Unique generation identifier (gen-...).
id	string	Job ID (job-...). Always the Knox job ID, not an upstream ID.
polling_url	string	Relative poll URL for this job.
status	string	pending, in_progress, completed, failed, cancelled, or expired.
error	string	Present when status is failed.
unsigned_urls	array of strings	Knox-hosted video URLs when status is completed.
usage	object	Present when billing has been finalized.
usage.cost	number	Cost in USD.

Error Responses

{
  "error": {
    "code": 404,
    "message": "Resource not found"
  }
}

Status	Message	When
401	Missing Authentication header	Missing or invalid API key.
404	Resource not found	Unknown jobId, or the job belongs to another user.
500	Internal Server Error	Unexpected server error.