ai-image-skills

# ai-image-skills ## Overview Use this skill to turn OpenAPI definitions into working image-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 an image 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 an image endpoint If `docs.json` exists, derive image endpoints from the `Images` 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/google/nano-banana-pro`). Use `references/image-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/google/nano-banana-pro \ --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/google/nano-banana-pro \ --payload '{"prompt":"Minimal product photo of a matte black coffee grinder on white background"}' \ --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/image-model-endpoints.md`: current image endpoint snapshot from `docs.json`