KDCN Video API

Expose KDCN video models through the KDCN public API.

The KDCN Video API exposes an asynchronous KDCN model surface under `/api/kdcn/v1`. List the available model schemas, submit the selected model with prompt/media/options, receive a `request_id`, then poll until the generated MP4 URL is ready.

GET/api/kdcn/v1/models

List KDCN model schemas

Returns the current KDCN model catalog, including model ids, categories, required fields, and parameter schemas that callers can send through `options`.

POST/api/kdcn/v1/videos/generations

Start a KDCN video job

Validates the team API key, injects the tenant-scoped KDCN provider key server-side, records usage, and queues the Django/Celery KDCN worker.

GET/api/kdcn/v1/videos/{request_id}

Poll KDCN job status

Returns `queued`, `processing`, `done`, `failed`, or `canceled`. When complete, `video.url` points to the generated MP4 stored by this site.

GET /api/kdcn/v1/models

Sample

curl -sS \
  -H "x-api-key: YOUR_API_KEY" \
  "https://kaleidovid.com/api/kdcn/v1/models"

Model catalog response example

Sample

{
  "object": "list",
  "provider": "kdcn",
  "base_url": "/api/kdcn/v1/videos",
  "data": [
    {
      "id": "kdcn:xai-grok-imagine-image-to-video-official-stable",
      "title": "Xai-grok-imagine-image-to-video-official-stable",
      "category": "image-to-video",
      "required": ["prompt", "imageUrl"],
      "parameters": [
        { "name": "prompt", "type": "string", "required": true },
        { "name": "imageUrl", "type": "string", "format": "uri", "required": true }
      ]
    }
  ]
}

JSON request fields

Use the model catalog as the source of truth for model-specific `options`. Common fields fill obvious schema slots, while `options` lets callers pass exact KDCN parameter names for advanced models.

Field	Type	Required	Notes
`model`	string	Yes	A KDCN model id from `GET /api/kdcn/v1/models`. Bare model ids are also accepted when they match a KDCN model.
`prompt`	string	Maybe	Required for models whose schema includes a required prompt field. You can also pass model-specific prompt fields inside `options`.
`inputs.images[] / inputs.videos[] / inputs.audios[]`	array	Maybe	Media inputs used to fill the model's URI parameters. Each item is `{ "url": "..." }`. URLs may be public `http(s)` URLs, same-site `/uploads/...` paths, or base64 data URLs.
`duration`	integer / string	No	Optional common duration hint. The selected model schema ultimately coerces or defaults this value.
`resolution`	string	No	Optional common resolution hint such as `720p`. Model-specific allowed values are visible in the model catalog response.
`aspect_ratio`	string	No	Optional common aspect-ratio hint. The camelCase alias `aspectRatio` is also accepted.
`options`	object	No	Model-specific fields from the catalog, for example `movementAmplitude`, `bgm`, `negativePrompt`, or exact URI parameter names. `options` values override common field mapping.
`seed`	integer	No	Use `-1` or omit the field for model default/random behavior. Non-negative seeds are clamped to the service-safe range.

POST /api/kdcn/v1/videos/generations

Sample

curl -sS \
  -X POST \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "model": "kdcn:xai-grok-imagine-image-to-video-official-stable",
    "prompt": "A calm cinematic camera push over the product.",
    "inputs": {
      "images": [
        { "url": "https://example.com/product.png" }
      ]
    },
    "duration": 6,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "options": {
      "movementAmplitude": "auto"
    }
  }' \
  "https://kaleidovid.com/api/kdcn/v1/videos/generations"

Queued response example

Sample

{
  "request_id": "a4377c13-c2a6-4974-81df-0f0ccbf701dc",
  "status": "queued",
  "model": "kdcn:xai-grok-imagine-image-to-video-official-stable",
  "provider": "kdcn"
}

Status response fields

Field	Type	Required	Notes
`request_id`	string	Always	Celery task id used to poll the status endpoint.
`status`	string	Always	One of `queued`, `processing`, `done`, `failed`, or `canceled`.
`provider`	string	Always	Always `kdcn` for this public surface.
`model`	string	Maybe	The normalized `kdcn:` model id. It is always present in the queued response and present in status once the worker has model metadata.
`video.url`	string	When done	Relative or absolute URL of the generated MP4. Present only when `status=done`.
`progress`	object	Maybe	Best-effort task progress metadata, including remote KDCN task state when available.
`error`	string	On failure	Failure reason returned when the job fails.

GET /api/kdcn/v1/videos/{request_id}

Sample

curl -sS \
  -H "x-api-key: YOUR_API_KEY" \
  "https://kaleidovid.com/api/kdcn/v1/videos/a4377c13-c2a6-4974-81df-0f0ccbf701dc"

Done response example

Sample

{
  "request_id": "a4377c13-c2a6-4974-81df-0f0ccbf701dc",
  "status": "done",
  "provider": "kdcn",
  "model": "kdcn:xai-grok-imagine-image-to-video-official-stable",
  "video": {
    "url": "/uploads/generations/video/runninghub_image-to-video/clip.mp4"
  }
}

Python polling example

Sample

# pip install requests

import time
import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://kaleidovid.com/api/kdcn/v1"

start = requests.post(
    f"{BASE_URL}/videos/generations",
    headers={"x-api-key": API_KEY},
    json={
        "model": "kdcn:xai-grok-imagine-image-to-video-official-stable",
        "prompt": "A calm cinematic camera push over the product.",
        "inputs": {
            "images": [{"url": "https://example.com/product.png"}],
        },
        "duration": 6,
        "resolution": "720p",
        "aspect_ratio": "16:9",
        "options": {"movementAmplitude": "auto"},
    },
    timeout=180,
)
start.raise_for_status()
request_id = start.json()["request_id"]

while True:
    status = requests.get(f"{BASE_URL}/videos/{request_id}", headers={"x-api-key": API_KEY}, timeout=60)
    status.raise_for_status()
    payload = status.json()
    if payload["status"] in {"done", "failed", "canceled"}:
        break
    time.sleep(5)

print(payload)

Failed response example

Sample

{
  "request_id": "a4377c13-c2a6-4974-81df-0f0ccbf701dc",
  "status": "failed",
  "provider": "kdcn",
  "model": "kdcn:xai-grok-imagine-image-to-video-official-stable",
  "error": "KDCN generation failed: upstream message"
}

KDCN uses the platform-owned KDCN key configured in Admin API Configuration; clients only send their KaleidoVid team API key. Remote media URLs must be publicly reachable and cannot resolve to private network hosts. For complex models, inspect `/models` and pass exact schema fields through `options`.