ai-video-skills

# ai-video-skills ## 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. ## 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. ```bash python scripts/ensure_api_key.py ``` If `ok` is `false`, tell the user to: - Open `https://skills.video/dashboard/developer` and log in - Click `Create API Key` - Export the key as `SKILLS_VIDEO_API_KEY` Example: ```bash export SKILLS_VIDEO_API_KEY="<YOUR_API_KEY>" ``` ## 1) Identify the spec Load the most specific OpenAPI first. - Prefer model-specific OpenAPI when available (for example `/v1/openapi.json` under a model namespace). - Fall back to platform-level `openapi.json`. - Use `references/open-platform-api.md` for base URL, auth, and async lifecycle. ## 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). ```bash 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. ```bash 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. ```bash 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/...`). ```bash curl -X GET "https://open.skills.video/api/v1/generation/<GENERATION_ID>" \ -H "Authorization: Bearer $SKILLS_VIDEO_API_KEY" ``` Stop polling on terminal states: - `COMPLETED` - `FAILED` - `CANCELED` Recommended helper: ```bash 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: - `400`: request format issue - `401`: missing/invalid API key - `402`: possible payment/credits issue in runtime - `404`: endpoint or generation id not found - `422`: schema validation failed Classify non-2xx runtime errors with: ```bash 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: - Open `https://skills.video/dashboard` and go to Billing/Credits - Recharge or purchase additional credits - Retry after recharge Optional balance check: ```bash 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 - `scripts/ensure_api_key.py`: validate `SKILLS_VIDEO_API_KEY` and show first-run setup guidance - `scripts/handle_runtime_error.py`: classify runtime errors and provide recharge guidance for insufficient credits - `scripts/inspect_openapi.py`: extract SSE/polling endpoint pair, contract, and payload template - `scripts/create_and_wait.py`: create via SSE and auto-fallback to polling when stream does not reach terminal status - `scripts/wait_generation.py`: poll generation status until terminal completion and return final response - `references/open-platform-api.md`: SSE-first lifecycle, fallback polling, retry baseline - `references/video-model-endpoints.md`: current video endpoint snapshot from `docs.json`