ai-video

---

name: ai-video

description: Build and execute skills.video video generation REST requests from OpenAPI specs. Use when user needs to create, debug, or document video generation calls on open.skills.video.

license: MIT

metadata:

openclaw:

author: skills-video

os:

- linux

- darwin

requires:

env:

- SKILLS_VIDEO_API_KEY

bins:

- python3

- curl

primaryEnv: SKILLS_VIDEO_API_KEY

cliHelp: |

Configure API key:

export SKILLS_VIDEO_API_KEY="your_api_key_here"

Verify:

python scripts/ensure_api_key.py

config:

stateDirs:

- ~/.openclaw

example: "Required env vars: SKILLS_VIDEO_API_KEY. Store the key in OpenClaw skill env or shell env and do not hardcode it in files."

links:

repository: https://github.com/skills-video/skills

homepage: https://skills.video

---

# ai-video

Overview

Use this skill to turn OpenAPI definitions into working video-generation API calls for `skills.video`.

Prefer deterministic extraction from `openapi.json` instead of guessing fields.

Prerequisites

1. Obtain an API key at: `https://skills.video/dashboard/developer`

2. Configure `SKILLS_VIDEO_API_KEY` before using the skill.

Preferred OpenClaw setup:

Equivalent config shape:

{
  "skills": {
    "entries": {
      "ai-video": {
        "enabled": true,
        "env": {
          "SKILLS_VIDEO_API_KEY": "your_api_key_here"
        }
      }
    }
  }
}

Other valid ways to provide the key:

Workflow

1. Check API key and bootstrap environment on first use.

2. Identify the active spec.

3. Select the SSE endpoint pair for a video model.

4. Extract request schema and generate a payload template.

5. Execute `POST /generation/sse/...` as default and keep the stream open.

6. If SSE does not reach terminal completion, poll `GET /generation/{id}` to terminal status.

7. Return only terminal result (`COMPLETED`/`SUCCEEDED`/`FAILED`/`CANCELED`), never `IN_PROGRESS`.

8. Apply retry and failure handling.

0) Check API key (first run)

Run this check before any API call.

python scripts/ensure_api_key.py

If `ok` is `false`, tell the user to:

Example:

export SKILLS_VIDEO_API_KEY="<YOUR_API_KEY>"

1) Identify the spec

Load the most specific OpenAPI first.

2) Select a video endpoint

If `docs.json` exists, derive video endpoints from the `Videos` navigation group.

Use `default_endpoints` from the script output as the primary list (SSE first).

python scripts/inspect_openapi.py \
  --openapi /abs/path/to/openapi.json \
  --docs /abs/path/to/docs.json \
  --list-endpoints

When `docs.json` is unavailable, pass a known endpoint directly (for example `/generation/sse/kling-ai/kling-v2.6`).

Use `references/video-model-endpoints.md` as a snapshot list.

3) Extract schema and build payload

Inspect endpoint details and generate a request template from required/default fields.

python scripts/inspect_openapi.py \
  --openapi /abs/path/to/openapi.json \
  --endpoint /generation/sse/kling-ai/kling-v2.6 \
  --include-template

Use the returned `request_template` as the starting point.

Do not add fields not defined by the endpoint schema.

Use `default_create_endpoint` from output unless an explicit override is required.

4) Execute SSE request (default) with automatic fallback

Prefer the helper script. It creates via SSE and keeps streaming; if stream ends before terminal completion, it automatically switches to polling fallback.

python scripts/create_and_wait.py \
  --sse-endpoint /generation/sse/kling-ai/kling-v2.6 \
  --payload '{"prompt":"A cinematic dolly shot of neon city rain at night"}' \
  --poll-timeout 900 \
  --poll-interval 3

Treat SSE as the default result channel.

Do not finish the task on `IN_QUEUE` or `IN_PROGRESS`.

Return only after terminal result.

5) Fall back to polling

Use polling only if SSE cannot be established, disconnects early, or does not reach a terminal state.

Use `GET /generation/{id}` (or model-spec equivalent path if the OpenAPI uses `/v1/...`).

curl -X GET "https://open.skills.video/api/v1/generation/<GENERATION_ID>" \
  -H "Authorization: Bearer $SKILLS_VIDEO_API_KEY"

Stop polling on terminal states:

Recommended helper:

python scripts/wait_generation.py \
  --generation-id <GENERATION_ID> \
  --timeout 900 \
  --interval 3

Return to user only after helper emits `event=terminal`.

6) Handle errors and retries

Handle these response codes for create, SSE, and fallback poll operations:

Classify non-2xx runtime errors with:

python scripts/handle_runtime_error.py \
  --status <HTTP_STATUS> \
  --body '<RAW_ERROR_BODY_JSON_OR_TEXT>'

If category is `insufficient_credits`, tell the user to recharge:

Optional balance check:

curl -X GET "https://open.skills.video/api/v1/credits" \
  -H "Authorization: Bearer $SKILLS_VIDEO_API_KEY"

Apply retries only for transient conditions (network failure or temporary `5xx`).

Use bounded exponential backoff (for example `1s`, `2s`, `4s`, max `16s`, then fail).

Do not retry unchanged payloads after `4xx` validation errors.

Rate limits and timeouts

Treat rate limits and server-side timeout windows as unknown unless documented in the active OpenAPI or product docs.

If unknown, explicitly note this in output and choose conservative client defaults.

Resources